claimsMappingPolicy resource type

Namespace: microsoft.graph

Represents the claim-mapping policies for WS-Fed, SAML, OAuth 2.0, and OpenID Connect protocols, for tokens issued to a specific application. You can use claims-mapping policies to:

  • Select which claims are included in tokens
  • Create claim types that do not already exist
  • Choose or change the source of data emitted in specific claims

For more scenario and configuration details see How to: Customize claims emitted in tokens for a specific app in a tenant.

Inherits from stsPolicy.


Method Return Type Description
Create claimsMappingPolicy claimsMappingPolicy Create a claimsMappingPolicy object.
Get claimsMappingPolicy claimsMappingPolicy Read properties and relationships of a claimsMappingPolicy object.
List claimsMappingPolicies claimsMappingPolicy Read properties and relationships of claimsMappingPolicies objects.
Update claimsMappingPolicy None Update a claimsMappingPolicy object.
Delete claimsMappingPolicy None Delete a claimsMappingPolicy object.
Directory objects
List appliesTo directoryObject collection Get the list of directoryObjects that this policy has been applied to.
Assign claimsMappingPolicy None Assign a claimsMappingPolicy to a servicePrincipal object.
List assigned claimsMappingPolicy claimsMappingPolicy collection List the claimsMappingPolicy objects that are assigned to a servicePrincipal object.
Remove claimsMappingPolicy None Remove a claimsMappingPolicy from a servicePrincipal object.


Property Type Description
id String Unique identifier for this policy. Read-only.
definition String collection A string collection containing a JSON string that defines the rules and settings for this policy. See Properties of a claims-mapping policy definition for more details about the JSON schema for this property. Required.
description String Description for this policy.
displayName String Display name for this policy. Required.
isOrganizationDefault Boolean Ignore this property. The claims-mapping policy can only be applied to service principals and can't be set globally for the organization.

Properties of a claims-mapping policy definition

The properties below form the JSON object that represents a claims-mapping policy. This JSON object must be converted to a string with quotations escaped to be inserted into the definition property. A few definition examples are shown below:

Example: definition to include the EmployeeID and TenantCountry as claims in tokens

    "definition": [
        "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\": [{\"Source\":\"user\",\"ID\":\"employeeid\",\"SamlClaimType\":\"\",\"JwtClaimType\":\"name\"},{\"Source\":\"company\",\"ID\":\"tenantcountry\",\"SamlClaimType\":\"\",\"JwtClaimType\":\"country\"}]}}"
    "displayName": "Test1234"

Example: definition that uses a claims transformation

    "definition": [
        "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\": [{\"Source\":\"user\",\"ID\":\"userprincipalname\",\"SamlClaimType\":\"\"},{\"Source\":\"user\",\"ID\":\"givenname\",\"SamlClaimType\":\"\"},{\"Source\":\"user\",\"ID\":\"displayname\",\"SamlClaimType\":\"\"},{\"Source\":\"user\",\"ID\":\"surname\",\"SamlClaimType\":\"\"},{\"Source\":\"user\",\"ID\":\"userprincipalname\",\"SamlClaimType\":\"username\"}],\"ClaimsTransformation\":[{\"ID\":\"CreateTermsOfService\",\"TransformationMethod\":\"CreateStringClaim\",\"InputParameters\": [{\"ID\":\"value\",\"DataType\":\"string\", \"Value\":\"sandbox\"}],\"OutputClaims\":[{\"ClaimTypeReferenceId\":\"TOS\",\"TransformationClaimType\":\"createdClaim\"}]}]}}"
    "displayName": "Test1234"
Property Type Description
Version Integer Set value of 1. Required.
IncludeBasicClaimSet Boolean If set to true, all claims in the basic claim set are emitted in tokens affected by the policy. If set to false, claims in the basic claim set are not in the tokens, unless they are individually added in the ClaimsSchema property of the same policy.
ClaimsSchema JSON object Defines which claims are present in the tokens affected by the policy, in addition to the basic claim set and the core claim set. For each claim schema entry defined in this property, certain information is required. Specify where the data is coming from (Value or Source/ID pair), and which claim the data is emitted as (Claim Type). For more information, see ClaimsSchema definition.
ClaimsTransformation JSON object Defines common transformations that can be applied to source data, to generate the output data for claims specified in the ClaimsSchema. For more information, see ClaimsTransformation definition.


Relationship Type Description
appliesTo directoryObject collection The directoryObject collection that this policy has been applied to. Read-only.

JSON representation

The following is a JSON representation of the resource.

  "definition": ["String"],
  "description": "String",
  "displayName": "String",
  "id": "String (identifier)",
  "isOrganizationDefault": false,