Personalizar declarações com a política de mapeamento de declarações no Microsoft Graph

Você pode adicionar atributos de usuário extras aos tokens de acesso para ajudar seu aplicativo a tomar melhores decisões de autorização. Este artigo mostra como usar APIs do Microsoft Graph para criar e atribuir uma política de mapeamento de declarações, adicionar declarações personalizadas para acessar tokens e verificar a declaração personalizada no token.

Pré-requisitos

Para concluir este tutorial, você precisa:

Acesso a um cliente de API, como o Graph Explorer, conectado com uma conta do Microsoft Entra que tenha a função de Administrador de Aplicativos e conceda as seguintes permissões delegadas: Policy.Read.All, Policy.ReadWrite.ApplicationConfiguration e Application.ReadWrite.All.
Uma entidade de serviço ao cliente à qual atribuir a política de mapeamento de declarações.
Uma entidade de serviço de recurso que expõe APIs.

Criar uma política de mapeamento de declarações

Essa política adiciona a department declaração do objeto de usuário ao token.

Solicitação

POST https://graph.microsoft.com/beta/policies/claimsMappingPolicies
Content-type: application/json

{
 "definition": [
   "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"user\",\"ID\":\"department\",\"JwtClaimType\":\"department\"}]}}"
 ],
 "displayName": "ExtraClaimsTest"
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Models;

var requestBody = new ClaimsMappingPolicy
{
	Definition = new List<string>
	{
		"{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"user\",\"ID\":\"department\",\"JwtClaimType\":\"department\"}]}}",
	},
	DisplayName = "ExtraClaimsTest",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Policies.ClaimsMappingPolicies.PostAsync(requestBody);



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewClaimsMappingPolicy()
definition := []string {
	"{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"user\",\"ID\":\"department\",\"JwtClaimType\":\"department\"}]}}",
}
requestBody.SetDefinition(definition)
displayName := "ExtraClaimsTest"
requestBody.SetDisplayName(&displayName) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
claimsMappingPolicies, err := graphClient.Policies().ClaimsMappingPolicies().Post(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ClaimsMappingPolicy claimsMappingPolicy = new ClaimsMappingPolicy();
LinkedList<String> definition = new LinkedList<String>();
definition.add("{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"user\",\"ID\":\"department\",\"JwtClaimType\":\"department\"}]}}");
claimsMappingPolicy.setDefinition(definition);
claimsMappingPolicy.setDisplayName("ExtraClaimsTest");
ClaimsMappingPolicy result = graphClient.policies().claimsMappingPolicies().post(claimsMappingPolicy);


const options = {
	authProvider,
};

const client = Client.init(options);

const claimsMappingPolicy = {
 definition: [
   '{\"ClaimsMappingPolicy\':{\'Version\':1,\'IncludeBasicClaimSet\':\'true\",\"ClaimsSchema\':[{\'Source\':\'user\",\"ID\':\'department\",\"JwtClaimType\':\"department\"}]}}"
 ],
 displayName: 'ExtraClaimsTest'
};

await client.api('/policies/claimsMappingPolicies')
	.version('beta')
	.post(claimsMappingPolicy);


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\ClaimsMappingPolicy;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new ClaimsMappingPolicy();
$requestBody->setDefinition(['{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"user\",\"ID\":\"department\",\"JwtClaimType\":\"department\"}]}}', 	]);
$requestBody->setDisplayName('ExtraClaimsTest');

$result = $graphServiceClient->policies()->claimsMappingPolicies()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Beta.Identity.SignIns

$params = @{
	definition = @(
	'{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true","ClaimsSchema":[{"Source":"user","ID":"department","JwtClaimType":"department"}]}}'
)
displayName = "ExtraClaimsTest"
}

New-MgBetaPolicyClaimMappingPolicy -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.models.claims_mapping_policy import ClaimsMappingPolicy
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ClaimsMappingPolicy(
	definition = [
		"{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"user\",\"ID\":\"department\",\"JwtClaimType\":\"department\"}]}}",
	],
	display_name = "ExtraClaimsTest",
)

result = await graph_client.policies.claims_mapping_policies.post(request_body)

Resposta

Registre a ID da resposta para usar posteriormente neste artigo.

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#policies/claimsMappingPolicies/$entity",
  "id": "06d5d20d-2955-45f8-a15d-cf2f434b8116",
  "deletedDateTime": null,
  "definition": [
      "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"user\",\"ID\":\"department\",\"JwtClaimType\":\"department\"}]}}"
  ],
  "displayName": "ExtraClaimsTest",
  "isOrganizationDefault": false
}

Você também pode adicionar mais de um atributo à política. O exemplo a seguir adiciona as department declarações and companyname ao token.

{
  "definition": [
        "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"user\",\"ID\":\"department\",\"JwtClaimType\":\"department\"},{\"Source\":\"user\",\"ID\":\"companyname\",\"JwtClaimType\":\"companyname\"}]}}"
    ],
 "displayName": "ExtraClaimsTest"
}

Atribuir a política a uma entidade de serviço de recurso

A solicitação a seguir atribui a política de mapeamento de declarações a uma entidade de serviço. Uma resposta bem-sucedida retorna 204 No Content.

POST https://graph.microsoft.com/v1.0/servicePrincipals/3bdbbc1a-5e94-4c2b-895f-231d8af4beee/claimsMappingPolicies/$ref
Content-type: application/json

{
 "@odata.id": "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/06d5d20d-2955-45f8-a15d-cf2f434b8116"
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new ReferenceCreate
{
	OdataId = "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/06d5d20d-2955-45f8-a15d-cf2f434b8116",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.ServicePrincipals["{servicePrincipal-id}"].ClaimsMappingPolicies.Ref.PostAsync(requestBody);



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewReferenceCreate()
odataId := "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/06d5d20d-2955-45f8-a15d-cf2f434b8116"
requestBody.SetOdataId(&odataId) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").ClaimsMappingPolicies().Ref().Post(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.models.ReferenceCreate referenceCreate = new com.microsoft.graph.models.ReferenceCreate();
referenceCreate.setOdataId("https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/06d5d20d-2955-45f8-a15d-cf2f434b8116");
graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").claimsMappingPolicies().ref().post(referenceCreate);


const options = {
	authProvider,
};

const client = Client.init(options);

const claimsMappingPolicy = {
 '@odata.id': 'https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/06d5d20d-2955-45f8-a15d-cf2f434b8116'
};

await client.api('/servicePrincipals/3bdbbc1a-5e94-4c2b-895f-231d8af4beee/claimsMappingPolicies/$ref')
	.post(claimsMappingPolicy);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ReferenceCreate;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new ReferenceCreate();
$requestBody->setOdataId('https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/06d5d20d-2955-45f8-a15d-cf2f434b8116');

$graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->claimsMappingPolicies()->ref()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Applications

$params = @{
	"@odata.id" = "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/06d5d20d-2955-45f8-a15d-cf2f434b8116"
}

New-MgServicePrincipalClaimMappingPolicyByRef -ServicePrincipalId $servicePrincipalId -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.reference_create import ReferenceCreate
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ReferenceCreate(
	odata_id = "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/06d5d20d-2955-45f8-a15d-cf2f434b8116",
)

await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').claims_mapping_policies.ref.post(request_body)

Habilitar declarações mapeadas no objeto de aplicativo de recurso

Atualize o objeto de aplicativo para aceitar declarações mapeadas e usar o token de acesso versão 2. Uma resposta bem-sucedida retorna 204 No Content.

PATCH https://graph.microsoft.com/v1.0/applications/3dfbe85f-2d14-4660-b1a2-cb9c633ceebb
Content-type: application/json

{
  "api": {
    "acceptMappedClaims": true,
    "requestedAccessTokenVersion": 2
  }
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Application
{
	Api = new ApiApplication
	{
		AcceptMappedClaims = true,
		RequestedAccessTokenVersion = 2,
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Applications["{application-id}"].PatchAsync(requestBody);



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewApplication()
api := graphmodels.NewApiApplication()
acceptMappedClaims := true
api.SetAcceptMappedClaims(&acceptMappedClaims) 
requestedAccessTokenVersion := int32(2)
api.SetRequestedAccessTokenVersion(&requestedAccessTokenVersion) 
requestBody.SetApi(api)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
applications, err := graphClient.Applications().ByApplicationId("application-id").Patch(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Application application = new Application();
ApiApplication api = new ApiApplication();
api.setAcceptMappedClaims(true);
api.setRequestedAccessTokenVersion(2);
application.setApi(api);
Application result = graphClient.applications().byApplicationId("{application-id}").patch(application);


const options = {
	authProvider,
};

const client = Client.init(options);

const application = {
  api: {
    acceptMappedClaims: true,
    requestedAccessTokenVersion: 2
  }
};

await client.api('/applications/3dfbe85f-2d14-4660-b1a2-cb9c633ceebb')
	.update(application);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Application;
use Microsoft\Graph\Generated\Models\ApiApplication;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Application();
$api = new ApiApplication();
$api->setAcceptMappedClaims(true);
$api->setRequestedAccessTokenVersion(2);
$requestBody->setApi($api);

$result = $graphServiceClient->applications()->byApplicationId('application-id')->patch($requestBody)->wait();


Import-Module Microsoft.Graph.Applications

$params = @{
	api = @{
		acceptMappedClaims = $true
		requestedAccessTokenVersion = 2
	}
}

Update-MgApplication -ApplicationId $applicationId -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.application import Application
from msgraph.generated.models.api_application import ApiApplication
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Application(
	api = ApiApplication(
		accept_mapped_claims = True,
		requested_access_token_version = 2,
	),
)

result = await graph_client.applications.by_application_id('application-id').patch(request_body)

Testar o token de acesso

Em um cliente de API que permite que você siga a plataforma de identidade da Microsoft e o fluxo de código de autorização do OAuth 2.0, obtenha um token de acesso. No parâmetro scope , inclua um dos escopos expostos pela entidade de serviço de recurso, como openid profile email scope-defined-by-your-api onde scope-defined-by-your-api pode estar api://00001111-aaaa-2222-bbbb-3333cccc4444/test.

Use jwt.ms para decodificar o token de acesso. A department declaração deve aparecer no token.

Limpe os recursos

Para cancelar a atribuição da política de mapeamento de declarações da entidade de serviço, use a solicitação a seguir. Uma resposta bem-sucedida retorna 204 No Content.

DELETE https://graph.microsoft.com/v1.0/servicePrincipals/3bdbbc1a-5e94-4c2b-895f-231d8af4beee/claimsMappingPolicies//06d5d20d-2955-45f8-a15d-cf2f434b8116/$ref

Comentários

Esta página foi útil?

Last updated on 2026-08-24