Partilhar via

Personalização de declarações usando o PowerShell e a Política de Mapeamento de Declarações

  • Artigo

Uma declaração é uma informação que um provedor de identidade declara sobre um usuário dentro do token que ele 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 políticas de mapeamento de declarações para:

  • Selecione quais declarações estão incluídas nos tokens.
  • Crie tipos de declaração que ainda não existem.
  • Escolha ou altere a fonte de dados emitidos em declarações específicas.

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

Nota

A Política de Mapeamento de Declarações substitui a política de Declarações Personalizadas e a personalização de declarações oferecida pelo 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 de personalização de declarações no centro de administração do Microsoft Entra.

Pré-requisitos

Começar agora

Nos exemplos a seguir, você cria, atualiza, vincula e exclui políticas para entidades de serviço. As políticas de mapeamento de declarações só podem ser atribuídas 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 extension em vez de ID no ClaimsSchema elemento . Para obter mais informações sobre atributos de extensão, consulte Usando atributos de extensão de diretório.

Nota

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

Abra um terminal e execute o seguinte comando para iniciar sessão na sua conta de administrador do Microsoft Entra. Execute este comando sempre que 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 atribuí-la 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 considerações de segurança.

Omitir as declarações básicas dos 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 dos tokens.

  2. Usando o terminal aberto, execute o seguinte comando para criar a política:

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

  3. Para ver sua nova política e obtê-la ObjectId, execute o seguinte comando:

    Get-MgPolicyClaimMappingPolicy

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

Incluir as EmployeeID declarações e TenantCountry como em tokens

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

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

  2. Para criar a política, execute o seguinte comando no 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 sua nova política e obtê-la ObjectId, execute o seguinte comando:

    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. Esta declaração contém um valor criado pela junção dos dados armazenados no atributo extensionattribute1 no objeto de usuário com "-ext". Neste exemplo, excluímos as declarações básicas definidas 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 JoinedData personalizada 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 sua nova política e obtê-la ObjectId, execute o seguinte comando:

    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 sua política de mapeamento de declarações e da objectId entidade de serviço à qual a política deve ser atribuída.

  1. Para ver todas as entidades de serviço da sua organização, você pode consultar a API do Microsoft Graph ou verificá-las 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 política de mapeamento de declarações e a 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údos relacionados