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:

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.

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.

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. By default, Global Administrator and other administrator roles don't 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 of custom security 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 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.

Diagram of custom security 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 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 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

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.

  1. Sign in to the Microsoft Entra admin center as a Attribute Assignment Administrator.

  2. Browse to Protection > Custom security attributes.

  3. Select the attribute set you want grant access to.

  4. Select Roles and administrators.

    Screenshot of assigning attribute roles at attribute set scope.

  5. 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.

  1. Sign in to the Microsoft Entra admin center as a Attribute Assignment Administrator.

  2. Browse to Identity > Roles & admins > Roles & admins.

    Screenshot of assigning attribute roles at tenant scope.

  3. 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. By default, a Global Administrator does not have access to these audit logs.

Screenshot of audit logs with Custom Security tab selected.

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.

Screenshot of diagnostic settings with Custom security attributes tab selected.

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.

Screenshot of audit logs that shows Directory and Custom Security tabs.

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 using the Global Administrator or Security Administrator roles 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.

Next steps