Assign, update, list, or remove custom security attributes using the Microsoft Graph API (preview)
Article
21 minutes to read
Important
The custom security attributes feature is 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.
This article provides examples of how to assign, update, or remove different types of custom security attributes for users and applications (service principals). Custom security attributes can be assigned or updated only through a PATCH operation in an Update user or Update servicePrincipal request.
Permissions
To manage custom security attributes, the calling principal must be assigned the following Azure AD role. By default, Global Administrator and other administrator roles do not have permissions to read, define, or assign custom security attributes.
Permissions to read, assign, update, or remove attributes for an application is granted by CustomSecAttributeAssignment.ReadWrite.All. Permissions to read the resource object, such as users, is granted separately using resource object permissions, such as User.Read.All.
Assign custom security attributes
Example 1: Assign a custom security attribute with a string value to a user
The following example shows how to assign a custom security attribute with a string value to a user.
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>()
{
{"Engineering", "{\"@odata.type\":\"#Microsoft.DirectoryServices.CustomSecurityAttributeValue\",\"ProjectDate\":\"2022-10-01\"}"}
}
}
};
await graphClient.Users["{user-id}"]
.Request()
.UpdateAsync(user);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => $customSecurityAttributes = new Engineering();
$ customSecurityAttributes->set@odatatype('#Microsoft.DirectoryServices.CustomSecurityAttributeValue');
$ customSecurityAttributes->setProjectDate('2022-10-01');
$customSecurityAttributes->setEngineering($engineering);
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$requestResult = $graphServiceClient->usersById('user-id')->patch($requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new ServicePrincipal();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => $customSecurityAttributes = new Engineering();
$ customSecurityAttributes->set@odatatype('#Microsoft.DirectoryServices.CustomSecurityAttributeValue');
$ customSecurityAttributes->setProjectDate('2022-10-01');
$customSecurityAttributes->setEngineering($engineering);
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$requestResult = $graphServiceClient->servicePrincipalsById('servicePrincipal-id')->patch($requestBody);
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>()
{
{"Engineering", "{\"@odata.type\":\"#Microsoft.DirectoryServices.CustomSecurityAttributeValue\",\"Project@odata.type\":\"#Collection(String)\",\"Project\":[\"Baker\",\"Cascade\"]}"}
}
}
};
await graphClient.Users["{user-id}"]
.Request()
.UpdateAsync(user);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => $customSecurityAttributes = new Engineering();
$ customSecurityAttributes->set@odatatype('#Microsoft.DirectoryServices.CustomSecurityAttributeValue');
$ customSecurityAttributes->setProject@odatatype('#Collection(String)');
$customSecurityAttributes->setProject(['Baker', 'Cascade', ]);
$customSecurityAttributes->setEngineering($engineering);
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$requestResult = $graphServiceClient->usersById('user-id')->patch($requestBody);
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>()
{
{"Engineering", "{\"@odata.type\":\"#Microsoft.DirectoryServices.CustomSecurityAttributeValue\",\"NumVendors@odata.type\":\"#Int32\",\"NumVendors\":4}"}
}
}
};
await graphClient.Users["{user-id}"]
.Request()
.UpdateAsync(user);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => $customSecurityAttributes = new Engineering();
$ customSecurityAttributes->set@odatatype('#Microsoft.DirectoryServices.CustomSecurityAttributeValue');
$ customSecurityAttributes->setNumVendors@odatatype('#Int32');
$customSecurityAttributes->setNumVendors(4);
$customSecurityAttributes->setEngineering($engineering);
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$requestResult = $graphServiceClient->usersById('user-id')->patch($requestBody);
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>()
{
{"Engineering", "{\"@odata.type\":\"#Microsoft.DirectoryServices.CustomSecurityAttributeValue\",\"CostCenter@odata.type\":\"#Collection(Int32)\",\"CostCenter\":[1001,1003]}"}
}
}
};
await graphClient.Users["{user-id}"]
.Request()
.UpdateAsync(user);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => $customSecurityAttributes = new Engineering();
$ customSecurityAttributes->set@odatatype('#Microsoft.DirectoryServices.CustomSecurityAttributeValue');
$ customSecurityAttributes->setCostCenter@odatatype('#Collection(Int32)');
$customSecurityAttributes->setCostCenter([1001,1003,]);
$customSecurityAttributes->setEngineering($engineering);
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$requestResult = $graphServiceClient->usersById('user-id')->patch($requestBody);
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>()
{
{"Engineering", "{\"@odata.type\":\"#Microsoft.DirectoryServices.CustomSecurityAttributeValue\",\"Certification\":true}"}
}
}
};
await graphClient.Users["{user-id}"]
.Request()
.UpdateAsync(user);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => $customSecurityAttributes = new Engineering();
$ customSecurityAttributes->set@odatatype('#Microsoft.DirectoryServices.CustomSecurityAttributeValue');
$customSecurityAttributes->setCertification(true);
$customSecurityAttributes->setEngineering($engineering);
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$requestResult = $graphServiceClient->usersById('user-id')->patch($requestBody);
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>()
{
{"Engineering", "{\"@odata.type\":\"#Microsoft.DirectoryServices.CustomSecurityAttributeValue\",\"NumVendors@odata.type\":\"#Int32\",\"NumVendors\":8}"}
}
}
};
await graphClient.Users["{user-id}"]
.Request()
.UpdateAsync(user);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => $customSecurityAttributes = new Engineering();
$ customSecurityAttributes->set@odatatype('#Microsoft.DirectoryServices.CustomSecurityAttributeValue');
$ customSecurityAttributes->setNumVendors@odatatype('#Int32');
$customSecurityAttributes->setNumVendors(8);
$customSecurityAttributes->setEngineering($engineering);
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$requestResult = $graphServiceClient->usersById('user-id')->patch($requestBody);
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>()
{
{"Engineering", "{\"@odata.type\":\"#Microsoft.DirectoryServices.CustomSecurityAttributeValue\",\"Certification\":false}"}
}
}
};
await graphClient.Users["{user-id}"]
.Request()
.UpdateAsync(user);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => $customSecurityAttributes = new Engineering();
$ customSecurityAttributes->set@odatatype('#Microsoft.DirectoryServices.CustomSecurityAttributeValue');
$customSecurityAttributes->setCertification(false);
$customSecurityAttributes->setEngineering($engineering);
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$requestResult = $graphServiceClient->usersById('user-id')->patch($requestBody);
Example 1: Get the custom security attributes assigned to a user
The following example shows how to list a custom security attribute assignment assigned to the user. The custom security attribute is a multi-string value with the following settings:
GET https://graph.microsoft.com/beta/users/{id}?$select=customSecurityAttributes
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = await graphClient.Users["{user-id}"]
.Request()
.Select("customSecurityAttributes")
.GetAsync();
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new UserRequestBuilderGetRequestConfiguration();
$queryParameters = new UserRequestBuilderGetQueryParameters();
$queryParameters->select = ["customSecurityAttributes"];
$requestConfiguration->queryParameters = $queryParameters;
$requestResult = $graphServiceClient->usersById('user-id')->get($requestConfiguration);
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>()
{
{"Engineering", "{\"@odata.type\":\"#Microsoft.DirectoryServices.CustomSecurityAttributeValue\",\"ProjectDate\":null}"}
}
}
};
await graphClient.Users["{user-id}"]
.Request()
.UpdateAsync(user);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => $customSecurityAttributes = new Engineering();
$ customSecurityAttributes->set@odatatype('#Microsoft.DirectoryServices.CustomSecurityAttributeValue');
$customSecurityAttributes->setProjectDate(null);
$customSecurityAttributes->setEngineering($engineering);
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$requestResult = $graphServiceClient->usersById('user-id')->patch($requestBody);
GraphServiceClient graphClient = new GraphServiceClient( authProvider );
var user = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>()
{
{"Engineering", "{\"@odata.type\":\"#Microsoft.DirectoryServices.CustomSecurityAttributeValue\",\"Project\":[]}"}
}
}
};
await graphClient.Users["{user-id}"]
.Request()
.UpdateAsync(user);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => $customSecurityAttributes = new Engineering();
$ customSecurityAttributes->set@odatatype('#Microsoft.DirectoryServices.CustomSecurityAttributeValue');
$customSecurityAttributes->setProject([]);
$customSecurityAttributes->setEngineering($engineering);
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$requestResult = $graphServiceClient->usersById('user-id')->patch($requestBody);