Create custom roles for Azure resources using the REST API

If the built-in roles for Azure resources don't meet the specific needs of your organization, you can create your own custom roles. This article describes how to create and manage 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.

    Filter Description
    $filter=type%20eq%20'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.

    Scope Type
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource
  3. Replace {filter} with the role type.

    Filter Description
    $filter=type%20eq%20'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.

    Scope Type
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource
  3. Replace {filter} with the display name for the role.

    Filter Description
    $filter=roleName%20eq%20'{roleDisplayName}' Use the URL encoded form of the exact display name of the role. For instance, $filter=roleName%20eq%20'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.

    Scope Type
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource
  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/{subscriptionId}"
        ]
      }
    }
    
  4. Within the URI, replace {scope} with the first assignableScopes of the custom role.

    Scope Type
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource
  5. Replace {roleDefinitionId} with the GUID identifier of the custom role.

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

  7. Replace {subscriptionId} with your subscription identifier.

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

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

  10. In the roleName and description properties, specify a unique role name and a description. For more information about the properties, see 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"
        ]
      }
    }
    

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.

    Scope Type
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource
  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/{subscriptionId}"
        ]
      }
    }
    
  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"
        ]
      }
    }
    

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.

    Scope Type
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource
  4. Replace {roleDefinitionId} with the GUID identifier of the custom role.

Next steps