Custom security attributes in Microsoft Entra ID are business-specific attributes (key-value pairs) that you can define and assign to Microsoft Entra objects. These attributes can be used to store information, categorize objects, or enforce fine-grained access control over specific Azure resources through Azure attribute-based access control (Azure ABAC).
Custom security attributes are supported for users and service principals only. This article provides examples of how to assign, update, list, or remove different types of custom security attributes for users and applications using Microsoft Graph.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>
{
{
"Engineering" , new
{
OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
ProjectDate = "2022-10-01",
}
},
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => [
'@odata.type' => '#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
'projectDate' => '2022-10-01',
],
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();
Example 2: Assign a custom security attribute with a string value to a service principal
The following example shows how to use the Update servicePrincipal API to assign a custom security attribute with a string value to a service principal.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ServicePrincipal
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>
{
{
"Engineering" , new
{
OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
ProjectDate = "2022-10-01",
}
},
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ServicePrincipal();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => [
'@odata.type' => '#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
'projectDate' => '2022-10-01',
],
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->patch($requestBody)->wait();
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>
{
{
"Engineering" , new
{
OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
ProjectOdataType = "#Collection(String)",
Project = new List<string>
{
"Baker",
"Cascade",
},
}
},
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => [
'@odata.type' => '#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
'project@odata.type' => '#Collection(String)',
'project' => [
'Baker', 'Cascade', ],
],
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>
{
{
"Engineering" , new
{
OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
NumVendorsOdataType = "#Int32",
NumVendors = 4,
}
},
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => [
'@odata.type' => '#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
'numVendors@odata.type' => '#Int32',
'numVendors' => 4,
],
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>
{
{
"Engineering" , new
{
OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
CostCenterOdataType = "#Collection(Int32)",
CostCenter = new List<Number>
{
1001,
1003,
},
}
},
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => [
'@odata.type' => '#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
'costCenter@odata.type' => '#Collection(Int32)',
'costCenter' => [
1001,1003],
],
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>
{
{
"Engineering" , new
{
OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
Certification = true,
}
},
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => [
'@odata.type' => '#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
'certification' => true,
],
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>
{
{
"Engineering" , new
{
OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
NumVendorsOdataType = "#Int32",
NumVendors = 8,
}
},
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => [
'@odata.type' => '#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
'numVendors@odata.type' => '#Int32',
'numVendors' => 8,
],
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>
{
{
"Engineering" , new
{
OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
Certification = false,
}
},
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => [
'@odata.type' => '#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
'certification' => false,
],
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();
GET https://graph.microsoft.com/v1.0/users/{id}?$select=customSecurityAttributes
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "customSecurityAttributes" };
});
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new UserItemRequestBuilderGetRequestConfiguration();
$queryParameters = UserItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["customSecurityAttributes"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->byUserId('user-id')->get($requestConfiguration)->wait();
# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY
graph_client = GraphServiceClient(credentials, scopes)
query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters(
select = ["customSecurityAttributes"],
)
request_configuration = UserItemRequestBuilder.UserItemRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.by_user_id('user-id').get(request_configuration = request_configuration)
Example 2: List all users with a custom security attribute assignment that equals a value
The following example shows how to use the List users API to list all users with a custom security attribute assignment that equals a value. The example retrieves users with a custom security attribute named AppCountry with a value that equals Canada. The filter value is case sensitive. You must add ConsistencyLevel=eventual in the request or the header. You must also include $count=true to ensure the request is routed correctly.
GET https://graph.microsoft.com/v1.0/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry eq 'Canada'
ConsistencyLevel: eventual
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.QueryParameters.Select = new string []{ "id","displayName","customSecurityAttributes" };
requestConfiguration.QueryParameters.Filter = "customSecurityAttributes/Marketing/AppCountry eq 'Canada'";
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "customSecurityAttributes/Marketing/AppCountry eq 'Canada'" --count "true" --select "id,displayName,customSecurityAttributes" --consistency-level "eventual"
Example 3: List all users with a custom security attribute assignment that starts with a value
The following example shows how to use the List users API to list all users with a custom security attribute assignment that starts with a value. The example retrieves users with a custom security attribute named EmployeeId with a value that starts with GS. The filter value is case sensitive. You must add ConsistencyLevel=eventual in the request or the header. You must also include $count=true to ensure the request is routed correctly.
GET https://graph.microsoft.com/v1.0/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=startsWith(customSecurityAttributes/Marketing/EmployeeId,'GS')
ConsistencyLevel: eventual
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.QueryParameters.Select = new string []{ "id","displayName","customSecurityAttributes" };
requestConfiguration.QueryParameters.Filter = "startsWith(customSecurityAttributes/Marketing/EmployeeId,'GS')";
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "startsWith(customSecurityAttributes/Marketing/EmployeeId,'GS')" --count "true" --select "id,displayName,customSecurityAttributes" --consistency-level "eventual"
Example 4: List all users with a custom security attribute assignment that does not equal a value
The following example shows how to use the List users API to list all users with a custom security attribute assignment that does not equal a value. The example retrieves users with a custom security attribute named AppCountry with a value that does not equal Canada. The filter value is case sensitive. You must add ConsistencyLevel=eventual in the request or the header. You must also include $count=true to ensure the request is routed correctly.
GET https://graph.microsoft.com/v1.0/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry ne 'Canada'
ConsistencyLevel: eventual
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.QueryParameters.Select = new string []{ "id","displayName","customSecurityAttributes" };
requestConfiguration.QueryParameters.Filter = "customSecurityAttributes/Marketing/AppCountry ne 'Canada'";
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "customSecurityAttributes/Marketing/AppCountry ne 'Canada'" --count "true" --select "id,displayName,customSecurityAttributes" --consistency-level "eventual"
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$headers = [
'ConsistencyLevel' => 'eventual',
];
$requestConfiguration->headers = $headers;
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->count = true;
$queryParameters->select = ["id","displayName","customSecurityAttributes"];
$queryParameters->filter = "customSecurityAttributes/Marketing/AppCountry ne 'Canada'";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration)->wait();
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>
{
{
"Engineering" , new
{
OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
ProjectDate = null,
}
},
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => [
'@odata.type' => '#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
'projectDate' => null,
],
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
CustomSecurityAttributes = new CustomSecurityAttributeValue
{
AdditionalData = new Dictionary<string, object>
{
{
"Engineering" , new
{
OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
Project = new List<object>
{
},
}
},
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
'Engineering' => [
'@odata.type' => '#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
'project' => [],
],
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();