Skip to content

Files

Latest commit

DavidCBerry13DavidCBerry13
(bulk) Update DevLang Metadata - Remove "na" - 12
Jan 1, 2022
a4ddf4a · Jan 1, 2022

History

History
133 lines (102 loc) · 6.42 KB

role-assignments-rest.md

File metadata and controls

133 lines (102 loc) · 6.42 KB
title description services author manager ms.service ms.workload ms.tgt_pltfrm ms.topic ms.date ms.author
Assign Azure roles using the REST API - Azure RBAC
Learn how to grant access to Azure resources for users, groups, service principals, or managed identities using the REST API and Azure role-based access control (Azure RBAC).
active-directory
rolyon
karenhoran
role-based-access-control
multiple
rest-api
how-to
04/06/2021
rolyon

Assign Azure roles using the REST API

[!INCLUDE Azure RBAC definition grant access] This article describes how to assign roles using the REST API.

Prerequisites

[!INCLUDE Azure role assignment prerequisites]

Assign an Azure role

To assign a role, use the Role Assignments - Create REST API and specify the security principal, role definition, and scope. To call this API, you must have access to the Microsoft.Authorization/roleAssignments/write action. Of the built-in roles, only Owner and User Access Administrator are granted access to this action.

  1. Use the Role Definitions - List REST API or see Built-in roles to get the identifier for the role definition you want to assign.

  2. Use a GUID tool to generate a unique identifier that will be used for the role assignment identifier. The identifier has the format: 00000000-0000-0000-0000-000000000000

  3. Start with the following request and body:

    PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignments/{roleAssignmentId}?api-version=2015-07-01
    {
  "properties": {
    "roleDefinitionId": "/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "principalId": "{principalId}"
  }
}

  4. Within the URI, replace {scope} with the scope for the role assignment.

    [!div class="mx-tableFixed"]

    Scope Type
    providers/Microsoft.Management/managementGroups/{groupId1} Management group
    subscriptions/{subscriptionId1} Subscription
    subscriptions/{subscriptionId1}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId1}/resourceGroups/myresourcegroup1/providers/microsoft.web/sites/mysite1 Resource

    In the previous example, microsoft.web is a resource provider that refers to an App Service instance. Similarly, you can use any other resource providers and specify the scope. For more information, see Azure Resource providers and types and supported Azure resource provider operations.

  5. Replace {roleAssignmentId} with the GUID identifier of the role assignment.

  6. Within the request body, replace {scope} with the scope for the role assignment.

    [!div class="mx-tableFixed"]

    Scope Type
    providers/Microsoft.Management/managementGroups/{groupId1} Management group
    subscriptions/{subscriptionId1} Subscription
    subscriptions/{subscriptionId1}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId1}/resourceGroups/myresourcegroup1/providers/microsoft.web/sites/mysite1 Resource

  7. Replace {roleDefinitionId} with the role definition identifier.

  8. Replace {principalId} with the object identifier of the user, group, or service principal that will be assigned the role.

The following request and body assigns the Backup Reader role to a user at subscription scope:

PUT https://management.azure.com/subscriptions/{subscriptionId1}/providers/microsoft.authorization/roleassignments/{roleAssignmentId1}?api-version=2015-07-01
{
  "properties": {
    "roleDefinitionId": "/subscriptions/{subscriptionId1}/providers/Microsoft.Authorization/roleDefinitions/a795c7a0-d4a2-40c1-ae25-d81f01202912",
    "principalId": "{objectId1}"
  }
}

The following shows an example of the output:

{
    "properties": {
        "roleDefinitionId": "/subscriptions/{subscriptionId1}/providers/Microsoft.Authorization/roleDefinitions/a795c7a0-d4a2-40c1-ae25-d81f01202912",
        "principalId": "{objectId1}",
        "scope": "/subscriptions/{subscriptionId1}",
        "createdOn": "2020-05-06T23:55:23.7679147Z",
        "updatedOn": "2020-05-06T23:55:23.7679147Z",
        "createdBy": null,
        "updatedBy": "{updatedByObjectId1}"
    },
    "id": "/subscriptions/{subscriptionId1}/providers/Microsoft.Authorization/roleAssignments/{roleAssignmentId1}",
    "type": "Microsoft.Authorization/roleAssignments",
    "name": "{roleAssignmentId1}"
}

New service principal

If you create a new service principal and immediately try to assign a role to that service principal, that role assignment can fail in some cases. For example, if you create a new managed identity and then try to assign a role to that service principal, the role assignment might fail. The reason for this failure is likely a replication delay. The service principal is created in one region; however, the role assignment might occur in a different region that hasn't replicated the service principal yet.

To address this scenario, use the Role Assignments - Create REST API and set the principalType property to ServicePrincipal. You must also set the apiVersion to 2018-09-01-preview or later.

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignments/{roleAssignmentId}?api-version=2018-09-01-preview
{
  "properties": {
    "roleDefinitionId": "/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "principalId": "{principalId}",
    "principalType": "ServicePrincipal"
  }
}

Next steps