List Azure role assignments using the REST API

  • Article

Azure role-based access control (Azure RBAC) is the authorization system you use to manage access to Azure resources. To determine what resources users, groups, service principals, or managed identities have access to, you list their role assignments. This article describes how to list role assignments using the REST API.

Note

If your organization has outsourced management functions to a service provider who uses Azure Lighthouse, role assignments authorized by that service provider won't be shown here. Similarly, users in the service provider tenant won't see role assignments for users in a customer's tenant, regardless of the role they've been assigned.

Note

For information about viewing or deleting personal data, see Azure Data Subject Requests for the GDPR. For more information about GDPR, see the GDPR section of the Microsoft Trust Center and the GDPR section of the Service Trust portal.

Prerequisites

You must use the following version:

  • 2015-07-01 or later
  • 2022-04-01 or later to include conditions

For more information, see API versions of Azure RBAC REST APIs.

List role assignments

In Azure RBAC, to list access, you list the role assignments. To list role assignments, use one of the Role Assignments Get or List REST APIs. To refine your results, you specify a scope and an optional filter.

  1. Start with the following request:

    GET https://management.chinacloudapi.cn/{scope}/providers/Microsoft.Authorization/roleAssignments?api-version=2022-04-01&$filter={filter}

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

    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.

  3. Replace {filter} with the condition that you want to apply to filter the role assignment list.

    Filter Description
    $filter=atScope() Lists role assignments for only the specified scope, not including the role assignments at subscopes.
    $filter=assignedTo('{objectId}') Lists role assignments for a specified user or service principal.
    If the user is a member of a group that has a role assignment, that role assignment is also listed. This filter is transitive for groups which means that if the user is a member of a group and that group is a member of another group that has a role assignment, that role assignment is also listed.
    This filter only accepts an object ID for a user or a service principal. You cannot pass an object ID for a group.
    $filter=atScope()+and+assignedTo('{objectId}') Lists role assignments for the specified user or service principal and at the specified scope.
    $filter=principalId+eq+'{objectId}' Lists role assignments for a specified user, group, or service principal.

The following request lists all role assignments for the specified user at subscription scope:

GET https://management.chinacloudapi.cn/subscriptions/{subscriptionId1}/providers/Microsoft.Authorization/roleAssignments?api-version=2022-04-01&$filter=atScope()+and+assignedTo('{objectId1}')

The following shows an example of the output:

{
    "value": [
        {
            "properties": {
                "roleDefinitionId": "/subscriptions/{subscriptionId1}/providers/Microsoft.Authorization/roleDefinitions/2a2b9908-6ea1-4ae2-8e65-a410df84e7d1",
                "principalId": "{objectId1}",
                "principalType": "User",
                "scope": "/subscriptions/{subscriptionId1}",
                "condition": null,
                "conditionVersion": null,
                "createdOn": "2022-01-15T21:08:45.4904312Z",
                "updatedOn": "2022-01-15T21:08:45.4904312Z",
                "createdBy": "{createdByObjectId1}",
                "updatedBy": "{updatedByObjectId1}",
                "delegatedManagedIdentityResourceId": null,
                "description": null
            },
            "id": "/subscriptions/{subscriptionId1}/providers/Microsoft.Authorization/roleAssignments/{roleAssignmentId1}",
            "type": "Microsoft.Authorization/roleAssignments",
            "name": "{roleAssignmentId1}"
        }
    ]
}

Next steps