Personalize declarações emitidas em tokens para um aplicativo específico em um locatário usando o PowerShell e a Política de Mapeamento de Declarações

  • Artigo

Uma declaração são informações que um provedor de identidade declara sobre um usuário dentro do token que emite para esse usuário. A personalização de declarações é usada por administradores de locatários para personalizar as declarações emitidas em tokens para um aplicativo específico em seu locatário. Você pode usar as políticas de mapeamento de declarações para:

  • selecione quais declarações são incluídas nos tokens.
  • crie tipos de declaração que ainda não existem.
  • escolha ou alterar a fonte dos dados emitidos em declarações específicas.

A personalização de declarações é compatível com a configuração das políticas de mapeamento de declarações para os protocolos SAML, OAuth e OpenID Connect.

Observação

A Política de Mapeamento de Declarações substitui a política de Declarações Personalizadas e a personalização de declarações oferecida por meio do centro de administração do Microsoft Entra. Personalizar declarações para um aplicativo usando a Política de Mapeamento de Declarações significa que os tokens emitidos para esse aplicativo ignorarão a configuração na Política de Declarações Personalizadas ou a configuração na folha personalização de declarações no centro de administração do Microsoft Entra.

Pré-requisitos

Introdução

Nos exemplos a seguir, você cria, atualiza, vincula e exclui políticas de entidades de serviço. Políticas de mapeamento de declarações podem ser atribuídas somente a objetos de entidade de serviço.

Ao criar uma política de mapeamento de declarações, você também pode emitir uma declaração de um atributo de extensão de diretório em tokens. Use ExtensionID para o atributo de extensão em vez de ID no elemento ClaimsSchema. Para saber mais sobre os atributos de extensão, confira Usar atributos de extensão de diretório.

Observação

O SDK do Microsoft Graph PowerShell é necessário para configurar políticas de mapeamento de declarações.

Abra um terminal e execute o comando a seguir para entrar em sua conta de administrador do Microsoft Entra. Execute esse comando sempre que você iniciar uma nova sessão.

Import-Module Microsoft.Graph.Identity.SignIns

Connect-MgGraph -Scopes "Policy.ReadWrite.ApplicationConfiguration", "Policy.Read.All"

Agora, você pode criar uma política de mapeamento de declarações e atribuir a uma entidade de serviço. Consulte os seguintes exemplos para cenários comuns:

Depois de criar uma política de mapeamento de declarações, configure seu aplicativo para reconhecer que os tokens conterão declarações personalizadas. Para obter mais informações, leia as considerações de segurança.

Omitir as declarações básicas de tokens

Neste exemplo, você cria uma política que remove o conjunto de declarações básicas de tokens emitidos para entidades de serviço vinculadas.

  1. Crie uma política de mapeamento de declarações. Essa política, vinculada a entidades de serviço específicas, remove o conjunto de declarações básicas do token.

  2. Usando o terminal que você abriu, execute o seguinte comando para criar a política:

    New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"false"}}') -DisplayName "OmitBasicClaims"

  3. Para ver a nova política e obter a ObjectId da política, execute o comando a seguir:

    Get-MgPolicyClaimMappingPolicy

Definition                    DeletedDateTime Description DisplayName      Id
----------                    --------------- ----------- -----------      --
{"ClaimsMappingPolicy":{..}}                              OmitBasicClaims  36d1aa10-f9ac...

Inclui o EmployeeID e TenantCountry como declarações no token

Neste exemplo, você cria uma política que adiciona a EmployeeID e TenantCountry a tokens emitidos para entidades de serviço vinculadas. EmployeeID é emitido como o tipo de declaração de nome em tokens SAML e JWTs. TenantCountry é emitido como o tipo de declaração de país/região em tokens SAML e JWTs. Neste exemplo, continuamos incluindo o conjunto de declarações básicas nos tokens.

  1. Crie uma política de mapeamento de declarações. Essa política, vinculada a entidades de serviço específicas, adiciona as declarações de EmployeeID e TenantCountry em tokens.

  2. Para criar a política, execute o seguinte comando em seu terminal:

    New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema": [{"Source":"user","ID":"employeeid","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/employeeid","JwtClaimType":"employeeid"},{"Source":"company","ID":"tenantcountry","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country","JwtClaimType":"country"}]}}') -DisplayName "ExtraClaimsExample"

  3. Para ver a nova política e obter a ObjectId da política, execute o comando a seguir:

    Get-MgPolicyClaimMappingPolicy

Usar uma transformação de declarações em tokens

Neste exemplo, você cria uma política que emite uma declaração personalizada "JoinedData" para JWTs emitidos para entidades de serviço vinculadas. Essa declaração contém um valor criado unindo os dados armazenados no atributo extensionattribute1 no objeto do usuário com "-ext". Neste exemplo, excluímos o conjunto de declarações básicas nos tokens.

  1. Crie uma política de mapeamento de declarações. Essa política, vinculada a entidades de serviço específicas, emite uma declaração personalizada JoinedData para tokens.

  2. Para criar a política, execute o seguinte comando:

    New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema":[{"Source":"user","ID":"extensionattribute1"},{"Source":"transformation","ID":"DataJoin","TransformationId":"JoinTheData","JwtClaimType":"JoinedData"}],"ClaimsTransformations":[{"ID":"JoinTheData","TransformationMethod":"Join","InputClaims":[{"ClaimTypeReferenceId":"extensionattribute1","TransformationClaimType":"string1"}], "InputParameters": [{"ID":"string2","Value":"ext"},{"ID":"separator","Value":"-"}],"OutputClaims":[{"ClaimTypeReferenceId":"DataJoin","TransformationClaimType":"outputClaim"}]}]}}') -DisplayName "TransformClaimsExample"

  3. Para ver a nova política e obter a ObjectId da política, execute o comando a seguir:

    Get-MgPolicyClaimMappingPolicy

Atribuir a política de mapeamento de declarações à entidade de serviço

Para atribuir a política à entidade de serviço, você precisará da ObjectId da sua política de mapeamento de declarações e da objectId da entidade de serviço à qual a política deve ser atribuída.

  1. Para ver todas as entidades de serviço de sua organização, você pode consultar a API do Microsoft Graph ou verificar no Microsoft Graph Explorer.

  2. Para ver todas as políticas de mapeamento de declarações em seu locatário e obter a política ObjectId, execute o seguinte comando:

    Get-MgPolicyClaimMappingPolicy

  3. Quando você tiver a ObjectId de sua política de mapeamento de declarações e da entidade de serviço, execute o seguinte comando:

    New-MgServicePrincipalClaimMappingPolicyByRef -ServicePrincipalId <servicePrincipalId> -BodyParameter @{"@odata.id" = "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/<claimsMappingPolicyId>"}

Conteúdo relacionado