Skip to content

Files

Latest commit

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

History

History
340 lines (261 loc) · 14.4 KB

custom-roles-rest.md

File metadata and controls

340 lines (261 loc) · 14.4 KB
title description services documentationcenter author manager editor ms.assetid ms.service ms.workload ms.tgt_pltfrm ms.topic ms.date ms.author ms.reviewer
Create or update Azure custom roles using the REST API - Azure RBAC
Learn how to list, create, update, or delete Azure custom roles using the REST API and Azure role-based access control (Azure RBAC).
active-directory
na
rolyon
karenhoran
1f90228a-7aac-4ea7-ad82-b57d222ab128
role-based-access-control
multiple
rest-api
how-to
03/19/2020
rolyon
bagovind

Create or update Azure custom roles using the REST API

Important

Adding a management group to AssignableScopes is currently in preview. This preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

If the Azure built-in roles don't meet the specific needs of your organization, you can create your own custom roles. This article describes how to list, create, update, or delete custom roles using the REST API.

List custom roles

To list all custom roles in a directory, use the Role Definitions - List REST API.

  1. Start with the following request:

    GET https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?api-version=2015-07-01&$filter={filter}

  2. Replace {filter} with the role type.

    [!div class="mx-tableFixed"]

    Filter Description
    $filter=type+eq+'CustomRole' Filter based on the CustomRole type

List custom roles at a scope

To list custom roles at a scope, use the Role Definitions - List REST API.

  1. Start with the following request:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?api-version=2015-07-01&$filter={filter}

  2. Within the URI, replace {scope} with the scope for which you want to list the roles.

    [!div class="mx-tableFixed"]

    Scope Type
    subscriptions/{subscriptionId1} Subscription
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Resource group
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} Resource
    providers/Microsoft.Management/managementGroups/{groupId1} Management group

  3. Replace {filter} with the role type.

    [!div class="mx-tableFixed"]

    Filter Description
    $filter=type+eq+'CustomRole' Filter based on the CustomRole type

List a custom role definition by name

To get information about a custom role by its display name, use the Role Definitions - Get REST API.

  1. Start with the following request:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?api-version=2015-07-01&$filter={filter}

  2. Within the URI, replace {scope} with the scope for which you want to list the roles.

    [!div class="mx-tableFixed"]

    Scope Type
    subscriptions/{subscriptionId1} Subscription
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Resource group
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} Resource
    providers/Microsoft.Management/managementGroups/{groupId1} Management group

  3. Replace {filter} with the display name for the role.

    [!div class="mx-tableFixed"]

    Filter Description
    $filter=roleName+eq+'{roleDisplayName}' Use the URL encoded form of the exact display name of the role. For instance, $filter=roleName+eq+'Virtual%20Machine%20Contributor'

List a custom role definition by ID

To get information about a custom role by its unique identifier, use the Role Definitions - Get REST API.

  1. Use the Role Definitions - List REST API to get the GUID identifier for the role.

  2. Start with the following request:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2015-07-01

  3. Within the URI, replace {scope} with the scope for which you want to list the roles.

    [!div class="mx-tableFixed"]

    Scope Type
    subscriptions/{subscriptionId1} Subscription
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Resource group
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1} Resource
    providers/Microsoft.Management/managementGroups/{groupId1} Management group

  4. Replace {roleDefinitionId} with the GUID identifier of the role definition.

Create a custom role

To create a custom role, use the Role Definitions - Create Or Update REST API. To call this API, you must be signed in with a user that is assigned a role that has the Microsoft.Authorization/roleDefinitions/write permission on all the assignableScopes. Of the built-in roles, only Owner and User Access Administrator include this permission.

  1. Review the list of resource provider operations that are available to create the permissions for your custom role.

  2. Use a GUID tool to generate a unique identifier that will be used for the custom role 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/roleDefinitions/{roleDefinitionId}?api-version=2015-07-01
    {
  "name": "{roleDefinitionId}",
  "properties": {
    "roleName": "",
    "description": "",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [

        ],
        "notActions": [

        ]
      }
    ],
    "assignableScopes": [
      "/subscriptions/{subscriptionId1}",
      "/subscriptions/{subscriptionId2}",
      "/subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}",
      "/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroup2}",
      "/providers/Microsoft.Management/managementGroups/{groupId1}"
    ]
  }
}

  4. Within the URI, replace {scope} with the first assignableScopes of the custom role.

    [!div class="mx-tableFixed"]

    Scope Type
    subscriptions/{subscriptionId1} Subscription
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Resource group
    providers/Microsoft.Management/managementGroups/{groupId1} Management group

  5. Replace {roleDefinitionId} with the GUID identifier of the custom role.

  6. Within the request body, replace {roleDefinitionId} with the GUID identifier.

  7. If assignableScopes is a subscription or resource group, replace the {subscriptionId} or {resourceGroup} instances with your identifiers.

  8. If assignableScopes is a management group, replace the {groupId} instance with your management group identifier. Adding a management group to assignableScopes is currently in preview.

  9. In the actions property, add the actions that the role allows to be performed.

  10. In the notActions property, add the actions that are excluded from the allowed actions.

  11. In the roleName and description properties, specify a unique role name and a description. For more information about the properties, see Azure custom roles.

    The following shows an example of a request body:

    {
  "name": "88888888-8888-8888-8888-888888888888",
  "properties": {
    "roleName": "Virtual Machine Operator",
    "description": "Can monitor and restart virtual machines.",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [
          "Microsoft.Storage/*/read",
          "Microsoft.Network/*/read",
          "Microsoft.Compute/*/read",
          "Microsoft.Compute/virtualMachines/start/action",
          "Microsoft.Compute/virtualMachines/restart/action",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Support/*"
        ],
        "notActions": []
      }
    ],
    "assignableScopes": [
      "/subscriptions/00000000-0000-0000-0000-000000000000",
      "/providers/Microsoft.Management/managementGroups/marketing-group"
    ]
  }
}

Update a custom role

To update a custom role, use the Role Definitions - Create Or Update REST API. To call this API, you must be signed in with a user that is assigned a role that has the Microsoft.Authorization/roleDefinitions/write permission on all the assignableScopes. Of the built-in roles, only Owner and User Access Administrator include this permission.

  1. Use the Role Definitions - List or Role Definitions - Get REST API to get information about the custom role. For more information, see the earlier List custom roles section.

  2. Start with the following request:

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

  3. Within the URI, replace {scope} with the first assignableScopes of the custom role.

    [!div class="mx-tableFixed"]

    Scope Type
    subscriptions/{subscriptionId1} Subscription
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Resource group
    providers/Microsoft.Management/managementGroups/{groupId1} Management group

  4. Replace {roleDefinitionId} with the GUID identifier of the custom role.

  5. Based on the information about the custom role, create a request body with the following format:

    {
  "name": "{roleDefinitionId}",
  "properties": {
    "roleName": "",
    "description": "",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [

        ],
        "notActions": [

        ]
      }
    ],
    "assignableScopes": [
      "/subscriptions/{subscriptionId1}",
      "/subscriptions/{subscriptionId2}",
      "/subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}",
      "/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroup2}",
      "/providers/Microsoft.Management/managementGroups/{groupId1}"
    ]
  }
}

  6. Update the request body with the changes you want to make to the custom role.

    The following shows an example of a request body with a new diagnostic settings action added:

    {
  "name": "88888888-8888-8888-8888-888888888888",
  "properties": {
    "roleName": "Virtual Machine Operator",
    "description": "Can monitor and restart virtual machines.",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [
          "Microsoft.Storage/*/read",
          "Microsoft.Network/*/read",
          "Microsoft.Compute/*/read",
          "Microsoft.Compute/virtualMachines/start/action",
          "Microsoft.Compute/virtualMachines/restart/action",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Insights/diagnosticSettings/*",
          "Microsoft.Support/*"
        ],
        "notActions": []
      }
    ],
    "assignableScopes": [
      "/subscriptions/00000000-0000-0000-0000-000000000000",
      "/providers/Microsoft.Management/managementGroups/marketing-group"
    ]
  }
}

Delete a custom role

To delete a custom role, use the Role Definitions - Delete REST API. To call this API, you must be signed in with a user that is assigned a role that has the Microsoft.Authorization/roleDefinitions/delete permission on all the assignableScopes. Of the built-in roles, only Owner and User Access Administrator include this permission.

  1. Use the Role Definitions - List or Role Definitions - Get REST API to get the GUID identifier of the custom role. For more information, see the earlier List custom roles section.

  2. Start with the following request:

    DELETE https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2015-07-01

  3. Within the URI, replace {scope} with the scope that you want to delete the custom role.

    [!div class="mx-tableFixed"]

    Scope Type
    subscriptions/{subscriptionId1} Subscription
    subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1} Resource group
    providers/Microsoft.Management/managementGroups/{groupId1} Management group

  4. Replace {roleDefinitionId} with the GUID identifier of the custom role.

Next steps