Manage access to custom security attributes in Microsoft Entra ID
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:
- Attribute Assignment Administrator
- Microsoft.Graph module when using Microsoft Graph PowerShell
Important
By default, Global Administrator and other administrator roles do not have permissions to read, define, or assign custom security attributes.
Step 1: Determine how to organize your attributes
Every custom security attribute definition 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 determine 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 depends on how you organize your attribute sets.
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.
Microsoft Entra 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 Microsoft Entra built-in roles. If necessary, someone with at least the Privileged Role Administrator role can assign these roles.
- Attribute Definition Administrator
- Attribute Assignment Administrator
- Attribute Definition Reader
- Attribute Assignment Reader
The following table provides a high-level comparison of the custom security attributes roles.
| Permission | 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.
- 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.
- The administrator assigns attributes to Microsoft Entra 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 might 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.
- 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.
- The delegated Attribute Definition Administrators (Alice and Bob) define attributes in the attribute sets they have been granted access to.
- The delegated Attribute Assignment Administrators (Chandra and Bob) assign attributes from their attribute sets to Microsoft Entra 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 |  Tenant |
|
Attribute Definition Administrator |  Attribute set |
|
Attribute Assignment Administrator | Tenant |
|
Attribute Assignment Administrator | Attribute set |
|
Attribute Definition Reader | Tenant |
|
Attribute Definition Reader | Attribute set |
|
Attribute Assignment Reader | Tenant |
|
Attribute Assignment Reader | 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
Tip
Steps in this article might vary slightly based on the portal you start from.
The following examples show how to assign a custom security attribute role to a principal at an attribute set scope named Engineering.
Sign in to the Microsoft Entra admin center as a Attribute Assignment Administrator.
Browse to Protection > Custom security attributes.
Select the attribute set you want grant access to.
Select Roles and administrators.
Add assignments for the custom security attribute roles.
Note
If you are using Microsoft Entra Privileged Identity Management (PIM), eligible role assignments at attribute set scope currently aren't supported. Permanent role assignments at attribute set scope are supported.
Assign roles at tenant scope
The following examples show how to assign a custom security attribute role to a principal at tenant scope.
Sign in to the Microsoft Entra admin center as a Attribute Assignment Administrator.
Browse to Identity > Roles & admins > Roles & admins.
Add assignments for the custom security attribute roles.
Custom security attribute audit logs
Sometimes you need information about custom security attribute changes for auditing or troubleshooting purposes. Anytime someone makes changes to definitions or assignments, the activities get logged.
Custom security attribute audit logs provide you with the history of activities related to custom security attributes, such as adding a new definition or assigning an attribute value to a user. Here are the custom security attribute-related activities that are logged:
- Add an attribute set
- Add custom security attribute definition in an attribute set
- Update an attribute set
- Update attribute values assigned to a servicePrincipal
- Update attribute values assigned to a user
- Update custom security attribute definition in an attribute set
View audit logs for attribute changes
To view the custom security attribute audit logs, sign in to the Microsoft Entra admin center, browse to Audit Logs, and select Custom Security. To view custom security attribute audit logs, you must be assigned one of the following roles. If necessary, someone with at least the Privileged Role Administrator role can assign these roles.
For information about how to get the custom security attribute audit logs using the Microsoft Graph API, see the customSecurityAttributeAudit resource type. For more information, see Microsoft Entra audit logs.
Diagnostic settings
To export custom security attribute audit logs to different destinations for additional processing, you use diagnostic settings. To create and configure diagnostic settings for custom security attributes, you must be assigned the Attribute Log Administrator role.
Tip
Microsoft recommends that you keep your custom security attribute audit logs separate from your directory audit logs so that attribute assignments are not revealed inadvertently.
The following screenshot shows the diagnostic settings for custom security attributes. For more information, see How to configure diagnostic settings.
Changes to audit logs behavior
Changes have been made to custom security attribute audit logs for general availability that might affect your daily operations. If you have been using custom security attribute audit logs during preview, here are the actions you must take to ensure your audit log operations aren't disrupted.
- Use new audit logs location
- Assign Attribute Log roles to view audit logs
- Create new diagnostic settings to export audit logs
Use new audit logs location
During the preview, custom security attribute audit logs were written to the directory audit logs endpoint. In October 2023, a new endpoint was added exclusively for custom security attribute audit logs. The following screenshot shows the directory audit logs and the new custom security attribute audit logs location. To get the custom security attribute audit logs using the Microsoft Graph API, see the customSecurityAttributeAudit resource type.
There is a transition period where custom security audit logs are written to both the directory and custom security attributes audit log endpoints. Going forward, you must use the custom security attributes audit log endpoint to find custom security attribute audit logs.
The following table lists the endpoint where you can find custom security attributes audit logs during the transition period.
| Event date | Directory endpoint | Custom security attributes endpoint |
|---|---|---|
| Oct 2023 | ✅ | ✅ |
| Feb 2024 | ✅ |
Assign Attribute Log roles to view audit logs
During the preview, custom security attribute audit logs could be viewed by those with at least the Security Administrator role in the directory audit logs. You are no longer able to use these roles to view custom security attribute audit logs using the new endpoint. To view the custom security attribute audit logs, you must be assigned either the Attribute Log Reader or Attribute Log Administrator role.
Create new diagnostic settings to export audit logs
During the preview, if you configured to export audit logs, custom security audit attribute audit logs were sent to your current diagnostic settings. To continue to receive custom security audit attribute audit logs, you must create new diagnostic settings as described in the previous Diagnostic settings section.