Create governanceRoleAssignmentRequest

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Caution

This version of the Privileged Identity Management (PIM) API for Azure resources will be deprecated soon. Please use the new Azure REST PIM API for Azure resource roles.

Create a role assignment request to represent the operation you want on a role assignment. The following table lists the operations.

Operation Type
Assign a role assignment AdminAdd
Activate an eligible role assignment UserAdd
Deactivate an activated role assignment UserRemove
Remove a role assignment AdminRemove
Update a role assignment AdminUpdate
Request to extend my role assignment UserExtend
Extend a role assignment AdminExtend
Request to renew my expired role assignment UserRenew
Renew an expired role assignment AdminRenew

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet

Permissions

The following table shows the least privileged permission or permissions required to call this API on each supported resource type. Follow best practices to request least privileged permissions. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Supported resource Delegated (work or school account) Delegated (personal Microsoft account) Application
Microsoft Entra ID PrivilegedAccess.ReadWrite.AzureAD Not supported. Not supported.
Azure resources PrivilegedAccess.ReadWrite.AzureResources Not supported. Not supported.
group PrivilegedAccess.ReadWrite.AzureADGroup Not supported. Not supported.

HTTP request

POST /privilegedAccess/azureResources/roleAssignmentRequests

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-type application/json

Request body

In the request body, supply a JSON representation of a governanceRoleAssignmentRequest object.

Property Type Description
resourceId String The unique identifier of the Azure resource that is associated with the role assignment request. Azure resources can include subscriptions, resource groups, virtual machines, and SQL databases. Required.
roleDefinitionId String The identifier of the Azure role definition that the role assignment request is associated with. Required.
subjectId String The unique identifier of the principal or subject that the role assignment request is associated with. Principals can be users, groups, or service principals. Required.
assignmentState String The state of assignment. The value can be Eligible and Active. Required.
type String The request type. The value can be AdminAdd, UserAdd, AdminUpdate, AdminRemove, UserRemove, UserExtend, UserRenew, AdminRenewand AdminExtend. Required.
reason String The reason needs to be provided for the role assignment request for audit and review purpose.
schedule governanceSchedule The schedule of the role assignment request. For request type of UserAdd, AdminAdd, AdminUpdate, and AdminExtend, it is required.

Response

If successful, this method returns a 201 Created response code and a governanceRoleAssignmentRequest object in the response body.

Error codes

This API returns the standard HTTP error codes. In addition, it also returns the error codes listed in the following table.

Error code Error message Details
400 BadRequest RoleNotFound The roleDefinitionId provided in the request body cannot be found.
400 BadRequest ResourceIsLocked The resource provided in the request body is in state of Locked and cannot create role assignment requests.
400 BadRequest SubjectNotFound The subjectId provided in the request body cannot be found.
400 BadRequest PendingRoleAssignmentRequest There already exists a pending governanceRoleAssignmentRequest in the system.
400 BadRequest RoleAssignmentExists The governanceRoleAssignment requested to be created already exists in the system.
400 BadRequest RoleAssignmentDoesNotExist The governanceRoleAssignment requested to be updated/extended does not exist in the system.
400 BadRequest RoleAssignmentRequestPolicyValidationFailed The governanceRoleAssignmentRequest does not meet internal policies and cannot be created.

Examples

The following examples show how to use this API.

Example 1: Administrator assigns user to a role

In this example, an administrator assigns user nawu@contoso.com to the Billing Reader role.

Note: In addition to the permission, this example requires that the requester have at least one Active administrator role assignment (owner or user access administrator) on the resource.

Property Type Required Value
resourceId String Yes <resourceId>
roleDefinitionId String Yes <roleDefinitionId>
subjectId String Yes <subjectId>
assignmentState String Yes Eligible / Active
type String Yes AdminAdd
reason String depends on role Settings
schedule governanceSchedule Yes

Request

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "ea48ad5e-e3b0-4d10-af54-39a45bbfe68d",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Eligible",
  "type": "AdminAdd",
  "reason": "Assign an eligible role",
  "schedule": {
    "startDateTime": "2018-05-12T23:37:43.356Z",
    "endDateTime": "2018-11-08T23:37:43.356Z",
    "type": "Once"
  }
}

Response

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "1232e4ea-741a-4be5-8044-5edabdd61672",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "ea48ad5e-e3b0-4d10-af54-39a45bbfe68d",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminAdd",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Evaluate Only",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:37:43.356Z",
    "endDateTime": "2018-11-08T23:37:43.356Z",
    "duration": "PT0S"
  }
}

Example 2: User activates eligible role

In this example, the user nawu@contoso.com activates the eligible Billing Reader role.

Property Type Required Value
resourceId String Yes <resourceId>
roleDefinitionId String Yes <roleDefinitionId>
subjectId String Yes <subjectId>
assignmentState String Yes Active
type String Yes UserAdd
reason String depends on role Settings
schedule governanceSchedule Yes

Request

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "8b4d1d51-08e9-4254-b0a6-b16177aae376",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Active",
  "type": "UserAdd",
  "reason": "Activate the owner role",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:28:43.537Z",
    "duration": "PT9H"
  },
  "linkedEligibleRoleAssignmentId": "e327f4be-42a0-47a2-8579-0a39b025b394"
}

Response

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "3ad49a7c-918e-4d86-9f84-fab28f8658c0",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "8b4d1d51-08e9-4254-b0a6-b16177aae376",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "e327f4be-42a0-47a2-8579-0a39b025b394",
  "type": "UserAdd",
  "assignmentState": "Active",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Activate the owner role",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "EligibilityRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      },
      {
        "key": "JustificationRule",
        "value": "Grant"
      },
      {
        "key": "ActivationDayRule",
        "value": "Grant"
      },
      {
        "key": "ApprovalRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:28:43.537Z",
    "endDateTime": "0001-01-01T00:00:00Z",
    "duration": "PT9H"
  }
}

Example 3: User deactivates an assigned role

In this example, the user nawu@contoso.com deactivates the active Billing Reader role.

Property Type Required Value
resourceId String Yes <resourceId>
roleDefinitionId String Yes <roleDefinitionId>
subjectId String Yes <subjectId>
assignmentState String Yes Active
type String Yes UserRemove
reason String No
schedule governanceSchedule No

Request

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "bc75b4e6-7403-4243-bf2f-d1f6990be122",
  "resourceId": "fb016e3a-c3ed-4d9d-96b6-a54cd4f0b735",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "assignmentState": "Active",
  "type": "UserRemove",
  "reason": "Deactivate the role",
  "linkedEligibleRoleAssignmentId": "cb8a533e-02d5-42ad-8499-916b1e4822ec"
}

Response

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "abfcdb57-8e5d-42a0-ae67-7598b96fddb1",
  "resourceId": "fb016e3a-c3ed-4d9d-96b6-a54cd4f0b735",
  "roleDefinitionId": "bc75b4e6-7403-4243-bf2f-d1f6990be122",
  "subjectId": "918e54be-12c4-4f4c-a6d3-2ee0e3661c51",
  "linkedEligibleRoleAssignmentId": "cb8a533e-02d5-42ad-8499-916b1e4822ec",
  "type": "UserRemove",
  "assignmentState": "Active",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "Evaluate only",
  "schedule": null,
  "status": {
    "status": "Closed",
    "subStatus": "Revoked",
    "statusDetails": []
  }
}

Example 4: Administrator removes user from a role

In this example, an administrator removes the user nawu@contoso.com from the Billing Reader role.

Note: In addition to the permission, this example requires that the requester have at least one Active administrator role assignment (owner or user access administrator) on the resource.

Property Type Required Value
resourceId String Yes <resourceId>
roleDefinitionId String Yes <roleDefinitionId>
subjectId String Yes <subjectId>
assignmentState String Yes Eligible / Active
type String Yes AdminRemove
reason String No
schedule governanceSchedule No

Request

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "65bb4622-61f5-4f25-9d75-d0e20cf92019",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "assignmentState": "Eligible",
  "type": "AdminRemove"
}

Response

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "c934fcb9-cf53-42ac-a8b4-6246f6726299",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "65bb4622-61f5-4f25-9d75-d0e20cf92019",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminRemove",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": null,
  "status": {
    "status": "Closed",
    "subStatus": "Revoked",
    "statusDetails": []
  },
  "schedule": null
}

Example 5: Administrator updates role assignment

In this example, administrators update the role assignment for the user nawu@contoso.com to Owner.

Note: In addition to the permission, this example requires that the requester have at least one Active administrator role assignment (owner or user access administrator) on the resource.

Property Type Required Value
resourceId String Yes <resourceId>
roleDefinitionId String Yes <roleDefinitionId>
subjectId String Yes <subjectId>
assignmentState String Yes Eligible / Active
type String Yes AdminUpdate
reason String depends on roleSettings
schedule governanceSchedule Yes

Request

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "70521f3e-3b95-4e51-b4d2-a2f485b02103",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "1566d11d-d2b6-444a-a8de-28698682c445",
  "assignmentState": "Eligible",
  "type": "AdminUpdate",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-03-08T05:42:45.317Z",
    "endDateTime": "2018-06-05T05:42:31.000Z"
  }
}

Response

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "4f6d4802-b3ac-4f5a-86d7-a6a4edd7d383",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "70521f3e-3b95-4e51-b4d2-a2f485b02103",
  "subjectId": "1566d11d-d2b6-444a-a8de-28698682c445",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminUpdate",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": null,
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-03-08T05:42:45.317Z",
    "endDateTime": "2018-06-05T05:42:31Z",
    "duration": "PT0S"
  }
}

Example 6: Administrator extends expiring role assignment

This example extends the expiring role assignment for user ANUJCUSER to API Management Service Contributor.

Note: In addition to the permission, this example requires that the requester have at least one Active administrator role assignment (owner or user access administrator) on the resource.

Property Type Required Value
resourceId String Yes <resourceId>
roleDefinitionId String Yes <roleDefinitionId>
subjectId String Yes <subjectId>
assignmentState String Yes Eligible / Active
type String Yes AdminExtend
reason String depends on roleSettings
schedule governanceSchedule Yes

Request

POST https://graph.microsoft.com/beta/privilegedAccess/azureResources/roleAssignmentRequests
Content-type: application/json

{
  "roleDefinitionId": "0e88fd18-50f5-4ee1-9104-01c3ed910065",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "assignmentState": "Eligible",
  "type": "AdminExtend",
  "reason": "extend role assignment",
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:53:55.327Z",
    "endDateTime": "2018-08-10T23:53:55.327Z"
  }
}

Response

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#governanceRoleAssignmentRequests/$entity",
  "id": "486f0c05-47c8-4498-9c06-086a78c83004",
  "resourceId": "e5e7d29d-5465-45ac-885f-4716a5ee74b5",
  "roleDefinitionId": "0e88fd18-50f5-4ee1-9104-01c3ed910065",
  "subjectId": "74765671-9ca4-40d7-9e36-2f4a570608a6",
  "linkedEligibleRoleAssignmentId": "",
  "type": "AdminExtend",
  "assignmentState": "Eligible",
  "requestedDateTime": "0001-01-01T00:00:00Z",
  "reason": "extend role assignment",
  "status": {
    "status": "InProgress",
    "subStatus": "Granted",
    "statusDetails": [
      {
        "key": "AdminRequestRule",
        "value": "Grant"
      },
      {
        "key": "ExpirationRule",
        "value": "Grant"
      },
      {
        "key": "MfaRule",
        "value": "Grant"
      }
    ]
  },
  "schedule": {
    "type": "Once",
    "startDateTime": "2018-05-12T23:53:55.327Z",
    "endDateTime": "2018-08-10T23:53:55.327Z",
    "duration": "PT0S"
  }
}