Edit

Create unifiedRoleAssignment

  • Article

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.

Create a new unifiedRoleAssignment object.

This API is available in the following national cloud deployments.

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

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

For the directory (Microsoft Entra ID) provider

Permission type Permissions (from least to most privileged)
Delegated (work or school account) RoleManagement.ReadWrite.Directory
Delegated (personal Microsoft account) Not supported.
Application RoleManagement.ReadWrite.Directory

For the entitlement management provider

Permission type Permissions (from least to most privileged)
Delegated (work or school account) EntitlementManagement.ReadWrite.All
Delegated (personal Microsoft account) Not supported.
Application Not supported.

For an Exchange Online provider

Permission type Permissions (from least to most privileged)
Delegated (work or school account) RoleManagement.ReadWrite.Exchange
Delegated (personal Microsoft account) Not supported.
Application RoleManagement.ReadWrite.Exchange

HTTP request

Create a role assignment for the directory provider:

POST /roleManagement/directory/roleAssignments

Create a role assignment for the entitlement management provider:

POST /roleManagement/entitlementManagement/roleAssignments

Create a role assignment for the Exchange Online provider:

POST /roleManagement/exchange/roleAssignments

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.

Request body

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

You can specify the following properties when creating a unifiedRoleAssignment.

Property Type Description
appScopeId String Required. Identifier of the app specific scope when the assignment scope is app specific. The scope of an assignment determines the set of resources for which the principal has been granted access. App scopes are scopes that are defined and understood by a resource application only.

For the entitlement management provider, use this property to specify a catalog, for example /AccessPackageCatalog/beedadfe-01d5-4025-910b-84abb9369997.

Either appScopeId or directoryScopeId must be specified.
directoryScopeId String Required. Identifier of the directory object representing the scope of the assignment. The scope of an assignment determines the set of resources for which the principal has been granted access. Directory scopes are shared scopes stored in the directory that are understood by multiple applications, unlike app scopes that are defined and understood by a resource application only.

For the directory (Microsoft Entra ID) provider, this property supports the following formats:
  • / for tenant-wide scope
  • /administrativeUnits/{administrativeunit-ID} to scope to an administrative unit
  • /{application-objectID} to scope to a resource application
  • /attributeSets/{attributeSet-ID} to scope to an attribute set

    For entitlement management provider, / for tenant-wide scope. To scope to an access package catalog, use the appScopeId property.

    For Exchange Online provider, this property supports following formats:
  • / for tenant-wide scope
  • /Users/{ObjectId of user} to scope the role assignment to a specific user
  • /AdministrativeUnits/{ObjectId of AU} to scope the role assignment to an administrative unit
  • /Groups/{ObjectId of group} to scope the role assinment to direct members of a specific group

    Either appScopeId or directoryScopeId must be specified.
    		•
    principalId String Required. Identifier of the principal to which the assignment is granted.
    roleDefinitionId String Identifier of the unifiedRoleDefinition the assignment is for. Read-only. Supports $filter (eq, in).

    Response

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

    Examples

    Example 1: Create a role assignment with tenant scope

    Request

    The following example shows a request. Note the use of the roleTemplateId for roleDefinitionId. roleDefinitionId can be either the service-wide template Id or the directory-specific roleDefinitionId.

    POST https://graph.microsoft.com/beta/roleManagement/directory/roleAssignments
Content-type: application/json

{ 
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "roleDefinitionId": "c2cf284d-6c41-4e6b-afac-4b80928c9034",
    "principalId": "f8ca5a85-489a-49a0-b555-0a6d81e56f0d",
    "directoryScopeId": "/"
}

    Response

    The following example shows the response.

    Note: The response object shown here might be shortened for readability.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/directory/roleAssignments/$entity",
    "id": "YUb1sHQtUEyvox7IA_Eu_mm3jqnUe4lEhvatluHVi2I-1",
    "roleDefinitionId": "c2cf284d-6c41-4e6b-afac-4b80928c9034",
    "principalId": "f8ca5a85-489a-49a0-b555-0a6d81e56f0d",
    "directoryScopeId": "/"
}

    Example 2 : Create a role assignment with administrative unit scope

    Request

    The following example assigns the User Administrator role to a principal with administrative unit scope.

    POST https://graph.microsoft.com/beta/roleManagement/directory/roleAssignments
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
    "principalId": "f8ca5a85-489a-49a0-b555-0a6d81e56f0d",
    "directoryScopeId": "/administrativeUnits/5d107bba-d8e2-4e13-b6ae-884be90e5d1a"
}

    Response

    The following example shows the response.

    Note: The response object shown here might be shortened for readability.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/directory/roleAssignments/$entity",
    "id": "BH21sHQtUEyvox7IA_Eu_mm3jqnUe4lEhvatluHIWb7-1",
    "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
    "principalId": "f8ca5a85-489a-49a0-b555-0a6d81e56f0d",
    "directoryScopeId": "/administrativeUnits/5d107bba-d8e2-4e13-b6ae-884be90e5d1a"
}

    Example 3 : Create a role assignment with attribute set scope

    Request

    The following example assigns the Attribute Assignment Administrator role to a principal with an attribute set scope named Engineering. For more information about Microsoft Entra custom security attributes and attribute set scope, see Manage access to custom security attributes in Microsoft Entra ID.

    POST https://graph.microsoft.com/beta/roleManagement/directory/roleAssignments
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "roleDefinitionId": "58a13ea3-c632-46ae-9ee0-9c0d43cd7f3d",
    "principalId": "f8ca5a85-489a-49a0-b555-0a6d81e56f0d",
    "directoryScopeId": "/attributeSets/Engineering"
}

    Response

    The following example shows the response.

    Note: The response object shown here might be shortened for readability.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/directory/roleAssignments/$entity",
    "id": "oz6hWDLGrkae4JwNQ81_PU-mYqx8m71OpqEQPdN1u",
    "roleDefinitionId": "58a13ea3-c632-46ae-9ee0-9c0d43cd7f3d",
    "principalId": "f8ca5a85-489a-49a0-b555-0a6d81e56f0d",
    "directoryScopeId": "/attributeSets/Engineering"
}

    Example 4: Create a role assignment with access package catalog scope

    Request

    The following example shows a request.

    POST https://graph.microsoft.com/beta/roleManagement/entitlementManagement/roleAssignments
Content-type: application/json

{
    "principalId": "679a9213-c497-48a4-830a-8d3d25d94ddc",
    "roleDefinitionId": "ae79f266-94d4-4dab-b730-feca7e132178",
    "appScopeId": "/AccessPackageCatalog/beedadfe-01d5-4025-910b-84abb9369997"
}

    Response

    The following example shows the response.

    Note: The response object shown here might be shortened for readability.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/entitlementManagement/roleAssignments/$entity",
    "id": "f3092518-7874-462e-93e9-0cd6c11ffc52",
    "principalId": "679a9213-c497-48a4-830a-8d3d25d94ddc",
    "roleDefinitionId": "ae79f266-94d4-4dab-b730-feca7e132178",
    "appScopeId": "/AccessPackageCatalog/beedadfe-01d5-4025-910b-84abb9369997"
}

    Example 5: Create a role assignment for Exchange Online provider with administrative unit scope

    Request

    The following example shows a request.

    POST https://graph.microsoft.com/beta/roleManagement/exchange/roleAssignments
Content-type: application/json

{
    "principalId": "/ServicePrincipals/0451dbb9-6336-42ea-b58f-5953dc053ece",
    "roleDefinitionId": "f66ab1ee-3cac-4d03-8a64-dadc56e563f8",
    "directoryScopeId": "/AdministrativeUnits/8b532c7a-4d3e-4e99-8ffa-2dfec92c62eb",
    "appScopeId": null
}

    Response

    The following example shows the response.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/exchange/roleAssignments/$entity",
    "id": "c5dd3ab8-374f-42e9-b163-eb7c54b53755",
    "principalId": "/ServicePrincipals/0451dbb9-6336-42ea-b58f-5953dc053ece",
    "roleDefinitionId": "f66ab1ee-3cac-4d03-8a64-dadc56e563f8",
    "directoryScopeId": "/AdministrativeUnits/8b532c7a-4d3e-4e99-8ffa-2dfec92c62eb",
    "appScopeId": null
}