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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
CustomSecurityAttributeValue customSecurityAttributes = new CustomSecurityAttributeValue();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
engineering = new ();
engineering.setOdataType("#Microsoft.DirectoryServices.CustomSecurityAttributeValue");
engineering.setProjectDate("2022-10-01");
additionalData.put("Engineering", engineering);
customSecurityAttributes.setAdditionalData(additionalData);
user.setCustomSecurityAttributes(customSecurityAttributes);
User result = graphClient.users().byUserId("{user-id}").patch(user);
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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipal servicePrincipal = new ServicePrincipal();
CustomSecurityAttributeValue customSecurityAttributes = new CustomSecurityAttributeValue();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
engineering = new ();
engineering.setOdataType("#Microsoft.DirectoryServices.CustomSecurityAttributeValue");
engineering.setProjectDate("2022-10-01");
additionalData.put("Engineering", engineering);
customSecurityAttributes.setAdditionalData(additionalData);
servicePrincipal.setCustomSecurityAttributes(customSecurityAttributes);
ServicePrincipal result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").patch(servicePrincipal);
// 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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
CustomSecurityAttributeValue customSecurityAttributes = new CustomSecurityAttributeValue();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
engineering = new ();
engineering.setOdataType("#Microsoft.DirectoryServices.CustomSecurityAttributeValue");
engineering.setProjectOdataType("#Collection(String)");
LinkedList<String> project = new LinkedList<String>();
project.add("Baker");
project.add("Cascade");
engineering.setProject(project);
additionalData.put("Engineering", engineering);
customSecurityAttributes.setAdditionalData(additionalData);
user.setCustomSecurityAttributes(customSecurityAttributes);
User result = graphClient.users().byUserId("{user-id}").patch(user);
// 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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
CustomSecurityAttributeValue customSecurityAttributes = new CustomSecurityAttributeValue();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
engineering = new ();
engineering.setOdataType("#Microsoft.DirectoryServices.CustomSecurityAttributeValue");
engineering.setNumVendorsOdataType("#Int32");
engineering.setNumVendors(4);
additionalData.put("Engineering", engineering);
customSecurityAttributes.setAdditionalData(additionalData);
user.setCustomSecurityAttributes(customSecurityAttributes);
User result = graphClient.users().byUserId("{user-id}").patch(user);
// 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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
CustomSecurityAttributeValue customSecurityAttributes = new CustomSecurityAttributeValue();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
engineering = new ();
engineering.setOdataType("#Microsoft.DirectoryServices.CustomSecurityAttributeValue");
engineering.setCostCenterOdataType("#Collection(Int32)");
LinkedList<Number> costCenter = new LinkedList<Number>();
costCenter.add(1001);
costCenter.add(1003);
engineering.setCostCenter(costCenter);
additionalData.put("Engineering", engineering);
customSecurityAttributes.setAdditionalData(additionalData);
user.setCustomSecurityAttributes(customSecurityAttributes);
User result = graphClient.users().byUserId("{user-id}").patch(user);
// 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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
CustomSecurityAttributeValue customSecurityAttributes = new CustomSecurityAttributeValue();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
engineering = new ();
engineering.setOdataType("#Microsoft.DirectoryServices.CustomSecurityAttributeValue");
engineering.setCertification(true);
additionalData.put("Engineering", engineering);
customSecurityAttributes.setAdditionalData(additionalData);
user.setCustomSecurityAttributes(customSecurityAttributes);
User result = graphClient.users().byUserId("{user-id}").patch(user);
// 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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
CustomSecurityAttributeValue customSecurityAttributes = new CustomSecurityAttributeValue();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
engineering = new ();
engineering.setOdataType("#Microsoft.DirectoryServices.CustomSecurityAttributeValue");
engineering.setNumVendorsOdataType("#Int32");
engineering.setNumVendors(8);
additionalData.put("Engineering", engineering);
customSecurityAttributes.setAdditionalData(additionalData);
user.setCustomSecurityAttributes(customSecurityAttributes);
User result = graphClient.users().byUserId("{user-id}").patch(user);
// 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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
CustomSecurityAttributeValue customSecurityAttributes = new CustomSecurityAttributeValue();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
engineering = new ();
engineering.setOdataType("#Microsoft.DirectoryServices.CustomSecurityAttributeValue");
engineering.setCertification(false);
additionalData.put("Engineering", engineering);
customSecurityAttributes.setAdditionalData(additionalData);
user.setCustomSecurityAttributes(customSecurityAttributes);
User result = graphClient.users().byUserId("{user-id}").patch(user);
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" };
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User result = graphClient.users().byUserId("{user-id}").get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"customSecurityAttributes"};
});
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"
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(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");
});
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"
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(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");
});
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"
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(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");
});
// 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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
CustomSecurityAttributeValue customSecurityAttributes = new CustomSecurityAttributeValue();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
engineering = new ();
engineering.setOdataType("#Microsoft.DirectoryServices.CustomSecurityAttributeValue");
engineering.setProjectDate(null);
additionalData.put("Engineering", engineering);
customSecurityAttributes.setAdditionalData(additionalData);
user.setCustomSecurityAttributes(customSecurityAttributes);
User result = graphClient.users().byUserId("{user-id}").patch(user);
// 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);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
CustomSecurityAttributeValue customSecurityAttributes = new CustomSecurityAttributeValue();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
engineering = new ();
engineering.setOdataType("#Microsoft.DirectoryServices.CustomSecurityAttributeValue");
LinkedList<Object> project = new LinkedList<Object>();
engineering.setProject(project);
additionalData.put("Engineering", engineering);
customSecurityAttributes.setAdditionalData(additionalData);
user.setCustomSecurityAttributes(customSecurityAttributes);
User result = graphClient.users().byUserId("{user-id}").patch(user);
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.