Manage access to custom security attributes in Azure AD (Preview)

Important

Custom security attributes are currently in PREVIEW. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

For people in your organization to effectively work with custom security attributes, you must grant the appropriate access. Depending on the information you plan to include in custom security attributes, you might want to restrict custom security attributes or you might want to make them broadly accessible in your organization. This article describes how to manage access to custom security attributes.

Prerequisites

To manage access to custom security attributes, you must have:

Important

By default, Global Administrator and other administrator roles do not have permissions to read, define, or assign custom security attributes.

Step 1: Figure out how to organize your attributes

Every custom security attribute must be part of an attribute set. An attribute set is a way to group and manage related custom security attributes. You'll need to figure out how you want to add attributes sets for your organization. For example, you might want to add attribute sets based on departments, teams, or projects. Your ability to grant access to custom security attributes will depend on how you organize your attribute sets.

Diagram showing an attribute set by department.

Step 2: Identify the needed scope

Scope is the set of resources that the access applies to. For custom security attributes, you can assign roles at tenant scope or at attribute set scope. If you want to assign broad access, you can assign roles at tenant scope. However, if you want to limit access to particular attribute sets, you can assign roles at attribute set scope.

Diagram showing tenant scope and attribute set scope.

Azure AD role assignments are an additive model, so your effective permissions are the sum of your role assignments. For example, if you assign a user a role at tenant scope and assign the same user the same role at attribute set scope, the user will still have permissions at tenant scope.

Step 3: Review the available roles

You need to determine who needs access to work with custom security attributes in your organization. To help you manage access to custom security attributes, there are four Azure AD built-in roles. By default, Global Administrator and other administrator roles do not have permissions to read, define, or assign custom security attributes. If necessary, a Global Administrator can assign these roles to themselves.

The following table provides a high-level comparison of the custom security attributes roles.

Permission Global Administrator Attribute Definition Admin Attribute Assignment Admin Attribute Definition Reader Attribute Assignment Reader
Read attribute sets ✔️ ✔️ ✔️ ✔️
Read attribute definitions ✔️ ✔️ ✔️ ✔️
Read attribute assignments for users and applications (service principals) ✔️ ✔️
Add or edit attribute sets ✔️
Add, edit, or deactivate attribute definitions ✔️
Assign attributes to users and applications (service principals) ✔️

Step 4: Determine your delegation strategy

This step describes two ways you can manage access to custom security attributes. The first way is to manage them centrally and the second way is to delegate management to others.

Manage attributes centrally

An administrator that has been assigned the Attribute Definition Administrator and Attribute Assignment Administrator roles at tenant scope can manage all aspects of custom security attributes. The following diagram shows how custom security attributes are defined and assigned by a single administrator.

Diagram showing attributes managed centrally.

  1. The administrator (Xia) has both the Attribute Definition Administrator and Attribute Assignment Administrator roles assigned at tenant scope. The administrator adds attribute sets and defines attributes.
  2. The administrator assigns attributes to Azure AD objects.

Managing attributes centrally has the advantage that it can be managed by one or two administrators. The disadvantage is that the administrator might get several requests to define or assign custom security attributes. In this case, you might want to delegate management.

Manage attributes with delegation

An administrator may not know all the situations of how custom security attributes should be defined and assigned. Typically it's users within the respective departments, teams, or projects who know the most about their area. Instead of assigning one or two administrators to manage all custom security attributes, you can instead delegate the management at attribute set scope. This also follows the best practice of least privilege to grant just the permissions other administrators need to do their job and avoid unnecessary access. The following diagram shows how the management of custom security attributes can be delegated to multiple administrators.

Diagram showing attributes managed with delegation.

  1. The administrator (Xia) with the Attribute Definition Administrator role assigned at tenant scope adds attribute sets. The administrator also has permissions to assign roles to others (Privileged Role Administrator) and delegates who can read, define, or assign custom security attributes for each attribute set.
  2. The delegated Attribute Definition Administrators (Alice and Bob) define attributes in the attribute sets they have been granted access to.
  3. The delegated Attribute Assignment Administrators (Chandra and Bob) assign attributes from their attribute sets to Azure AD objects.

Step 5: Select the appropriate roles and scope

Once you have a better understanding of how your attributes will be organized and who needs access, you can select the appropriate custom security attribute roles and scope. The following table can help you with the selection.

I want to grant this access Assign this role Scope
Attribute Definition Administrator Icon for tenant scope.
Tenant
Attribute Definition Administrator Icon for attribute set scope.
Attribute set
Attribute Assignment Administrator Icon for tenant scope.
Tenant
Attribute Assignment Administrator Icon for attribute set scope.
Attribute set
  • Read all attribute sets in a tenant
  • Read all attribute definitions in a tenant
Attribute Definition Reader Icon for tenant scope.
Tenant
  • Read attribute definitions in a scoped attribute set
  • Cannot read other attribute sets
Attribute Definition Reader Icon for attribute set scope.
Attribute set
  • Read all attribute sets in a tenant
  • Read all attribute definitions in a tenant
  • Read all attribute assignments in a tenant for users
  • Read all attribute assignments in a tenant for applications (service principals)
Attribute Assignment Reader Icon for tenant scope.
Tenant
  • Read attribute definitions in a scoped attribute set
  • Read attribute assignments that use attributes in a scoped attribute set for users
  • Read attribute assignments that use attributes in a scoped attribute set for applications (service principals)
  • Cannot read attributes in other attribute sets
  • Cannot read attribute assignments that use attributes in other attribute sets
Attribute Assignment Reader Icon for attribute set scope.
Attribute set

Step 6: Assign roles

To grant access to the appropriate people, follow these steps to assign one of the custom security attribute roles.

Assign roles at attribute set scope

Azure portal

  1. Sign in to the Azure portal or Azure AD admin center.

  2. Click Azure Active Directory.

  3. In the left navigation menu, click Custom security attributes (Preview).

  4. Click the attribute set you want grant access to.

  5. Click Roles and administrators.

    Screenshot of assigning attribute roles at attribute set scope.

  6. Add assignments for the custom security attribute roles.

    Note

    If you are using Azure AD Privileged Identity Management (PIM), eligible role assignments at attribute set scope currently aren't supported. Permanent role assignments at attribute set scope are supported, but the Assigned roles page for a user doesn't list the role assignments.

PowerShell

Use New-AzureADMSRoleAssignment to assign the role. The following example assigns the Attribute Assignment Administrator role to a principal with an attribute set scope named Engineering.

$roleDefinitionId = "58a13ea3-c632-46ae-9ee0-9c0d43cd7f3d"
$directoryScope = "/attributeSets/Engineering"
$principalId = "f8ca5a85-489a-49a0-b555-0a6d81e56f0d"
$roleAssignment = New-AzureADMSRoleAssignment -DirectoryScopeId $directoryScope -RoleDefinitionId $roleDefinitionId -PrincipalId $principalId

Microsoft Graph API

Use the Create unified Role Assignment API to assign the role. The following example assigns the Attribute Assignment Administrator role to a principal with an attribute set scope named Engineering.

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"
}

Assign roles at tenant scope

Azure portal

  1. Sign in to the Azure portal or Azure AD admin center.

  2. Click Azure Active Directory.

  3. In the left navigation menu, click Roles and administrators.

    Screenshot of assigning attribute roles at tenant scope.

  4. Add assignments for the custom security attribute roles.

PowerShell

Use New-AzureADMSRoleAssignment to assign the role. For more information, see Assign Azure AD roles at different scopes.

Microsoft Graph API

Use the Create unified Role Assignment API to assign the role. For more information, see Assign Azure AD roles at different scopes.

View audit logs for attribute changes

Sometimes you need information about custom security attribute changes, such as for auditing or troubleshooting purposes. Anytime someone makes changes to definitions or assignments, the changes get logged in the Azure AD audit logs.

Here are the custom security attribute-related activities that are logged:

  • Add attribute set
  • Update attribute set
  • Add custom security attribute definition
  • Update custom security attribute definition
  • Assign custom security attribute
  • Remove custom security attribute

The following screenshot shows an example of the audit log. To filter the logs for custom security attribute-related activities, select the Category filter and then select AttributeManagement.

Screenshot of audit logs with AttributeManagement category filter.

Next steps