Assign or remove custom security attributes for an application (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.

Custom security attributes in Azure Active Directory (Azure AD) are business-specific attributes (key-value pairs) that you can define and assign to Azure AD objects. For example, you can assign custom security attribute to filter your applications or to help determine who gets access. This article describes how to assign, update, remove, or filter custom security attributes for Azure AD enterprise applications.

Prerequisites

To assign or remove custom security attributes for an application in your Azure AD tenant, you need:

Important

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

Assign custom security attributes to an application

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

  2. Make sure that you have existing custom security attributes. For more information, see Add or deactivate custom security attributes in Azure AD.

  3. Select Azure Active Directory > Enterprise applications.

  4. Find and select the application you want to add a custom security attribute to.

  5. In the Manage section, select Custom security attributes (preview).

  6. Select Add assignment.

  7. In Attribute set, select an attribute set from the list.

  8. In Attribute name, select a custom security attribute from the list.

  9. Depending on the properties of the selected custom security attribute, you can enter a single value, select a value from a predefined list, or add multiple values.

    • For freeform, single-valued custom security attributes, enter a value in the Assigned values box.
    • For predefined custom security attribute values, select a value from the Assigned values list.
    • For multi-valued custom security attributes, select Add values to open the Attribute values pane and add your values. When finished adding values, select Done.

    Screenshot showing assigning a custom security attribute to an application.

  10. When finished, select Save to assign the custom security attributes to the application.

Update custom security attribute assignment values for an application

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

  2. Select Azure Active Directory > Enterprise applications.

  3. Find and select the application that has a custom security attribute assignment value you want to update.

  4. In the Manage section, select Custom security attributes (preview).

  5. Find the custom security attribute assignment value you want to update.

    Once you have assigned a custom security attribute to an application, you can only change the value of the custom security attribute. You can't change other properties of the custom security attribute, such as attribute set or custom security attribute name.

  6. Depending on the properties of the selected custom security attribute, you can update a single value, select a value from a predefined list, or update multiple values.

  7. When finished, select Save.

Remove custom security attribute assignments from applications

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

  2. Select Azure Active Directory > Enterprise applications.

  3. Find and select the application that has the custom security attribute assignments you want to remove.

  4. In the Manage section, select Custom security attributes (preview).

  5. Add check marks next to all the custom security attribute assignments you want to remove.

  6. Select Remove assignment.

Filter applications based on custom security attributes

You can filter the list of custom security attributes assigned to applications on the All applications page.

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

  2. Select Azure Active Directory > Enterprise applications.

  3. Select Add filters to open the Pick a field pane.

    If you don't see Add filters, click the banner to enable the Enterprise applications search preview.

  4. For Filters, select Custom security attribute.

  5. Select your attribute set and attribute name.

  6. For Operator, you can select equals (==), not equals (!=), or starts with.

  7. For Value, enter or select a value.

    Screenshot showing a custom security attribute filter for applications.

  8. To apply the filter, select Apply.

PowerShell

To manage custom security attribute assignments for applications in your Azure AD organization, you can use PowerShell. The following commands can be used to manage assignments.

Get the custom security attribute assignments for an application (service principal)

Use the Get-AzureADMSServicePrincipal command to get the custom security attribute assignments for an application (service principal).

Get-AzureADMSServicePrincipal -Select CustomSecurityAttributes
Get-AzureADMSServicePrincipal -Id 7d194b0c-bf17-40ff-9f7f-4b671de8dc20  -Select "CustomSecurityAttributes, Id"

Assign a custom security attribute with a multi-string value to an application (service principal)

Use the Set-AzureADMSServicePrincipal command to assign a custom security attribute with a multi-string value to an application (service principal).

  • Attribute set: Engineering
  • Attribute: Project
  • Attribute data type: Collection of Strings
  • Attribute value: ("Baker","Cascade")
$attributes = @{
    Engineering = @{
        "@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
        "Project@odata.type" = "#Collection(String)"
        Project = @("Baker","Cascade")
    }
}
Set-AzureADMSServicePrincipal -Id 7d194b0c-bf17-40ff-9f7f-4b671de8dc20 -CustomSecurityAttributes $attributes

Update a custom security attribute with a multi-string value for an application (service principal)

Use the Set-AzureADMSServicePrincipal command to update a custom security attribute with a multi-string value for an application (service principal).

  • Attribute set: Engineering
  • Attribute: Project
  • Attribute data type: Collection of Strings
  • Attribute value: ("Alpine","Baker")
$attributesUpdate = @{
    Engineering = @{
        "@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
        "Project@odata.type" = "#Collection(String)"
        Project = @("Alpine","Baker")
    }
}
Set-AzureADMSServicePrincipal -Id 7d194b0c-bf17-40ff-9f7f-4b671de8dc20 -CustomSecurityAttributes $attributesUpdate 

Microsoft Graph API

To manage custom security attribute assignments for applications in your Azure AD organization, you can use the Microsoft Graph API. The following API calls can be made to manage assignments.

For other similar Microsoft Graph API examples for users, see Assign or remove custom security attributes for a user and Assign, update, or remove custom security attributes using the Microsoft Graph API.

Get the custom security attribute assignments for an application (service principal)

Use the Get servicePrincipal API to get the custom security attribute assignments for an application (service principal).

GET https://graph.microsoft.com/beta/servicePrincipals/{id}?$select=customSecurityAttributes

If there are no custom security attributes assigned to the application or if the calling principal does not have access, the response will look like:

{
    "customSecurityAttributes": null
}

Assign a custom security attribute with a string value to an application (service principal)

Use the Update servicePrincipal API to assign a custom security attribute with a string value to a user.

  • Attribute set: Engineering
  • Attribute: ProjectDate
  • Attribute data type: String
  • Attribute value: "2022-10-01"
PATCH https://graph.microsoft.com/beta/servicePrincipals/{id}
{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "ProjectDate":"2022-10-01"
        }
    }
}

Next steps