Compartilhar via

Personalizar declarações usando a Política de Declarações Personalizadas do Microsoft Graph (versão prévia)

  • 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. A personalização de declarações dá suporte à configuração de declarações para aplicativos usando os protocolos SAML, OAuth e OpenID Connect. Você pode usar a personalização de declarações para:

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

Neste guia de instruções, abordamos alguns cenários comuns que podem ajudar você a entender como usar a Política de Declarações Personalizadas.

Pré-requisitos

Personalização de declarações no Microsoft Entra ID

O Microsoft Entra ID dá suporte a duas maneiras de personalizar declarações usando o Microsoft Graph/PowerShell para seus aplicativos:

Nos exemplos a seguir, você vai criar, atualizar e substituir políticas para entidades de serviço. As políticas de declarações personalizadas estão sempre vinculadas a objetos de entidades de serviço. Certifique-se de que você configurou seu Aplicativo Empresarial como parte dos pré-requisitos antes de criar uma política de Declarações Personalizadas para o aplicativo/entidade de serviço.

Abra o Explorador do Microsoft Graph no navegador para fazer login como, pelo menos, um Administrador de Aplicativos, e escolha um dos cenários a seguir.

Após criar uma política de Declarações Personalizadas, você deve configurar seu aplicativo para reconhecer que os tokens contêm as declarações personalizadas. Para obter mais informações, consulte as Considerações de segurança.

Omitir as declarações básicas de tokens

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

  1. No Explorador do Microsoft Graph, identifique o aplicativo no qual você quer configurar a política de declarações personalizadas para usar a API da entidade de serviço.

  2. Crie a política de Declarações Personalizadas executando a API a seguir. Essa política, vinculada a uma entidade de serviço, omite as declarações básicas dos tokens.

    PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Corpo da solicitação:

    {
    "includeBasicClaimSet": false
}

  3. Para ver sua nova política, execute o seguinte comando

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Resposta:

    HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222.",
    "includeBasicClaimSet": false,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": []
}

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

Nesse exemplo, você cria uma personalização para as declarações que adiciona EmployeeID e TenantCountry aos tokens. Nesse exemplo, também incluímos o conjunto de declarações básicas nos tokens.

  1. No Explorador do Microsoft Graph, identifique o aplicativo no qual você quer configurar a política de declarações personalizadas para usar a API da entidade de serviço.

  2. Crie a política de Declarações Personalizadas executando a API a seguir. Essa política, vinculada a uma entidade de serviço, adiciona as declarações EmployeeID e TenantCountry aos tokens.

    PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Corpo da solicitação:

    {
    "includeBasicClaimSet": true,
    "claims": [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "employeeId",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " employeeid",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        },
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "country",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " tenantcountry",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        }
    ]
}

  3. Para ver a nova política, execute o seguinte comando:

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Resposta:

    {
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

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

Nesse exemplo, você atualiza uma política para emitir 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. No Explorador do Microsoft Graph, identifique o aplicativo no qual você quer configurar a política de declarações personalizadas para usar a API da entidade de serviço.

  2. Crie a política de declarações personalizadas executando a API a seguir. Essa política emite uma declaração de JoinedData personalizada para os tokens.

    PATCH https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Corpo da solicitação:

    {
    "includeBasicClaimSet": true,
    "claims": 
    [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "JoinedData",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": 
            [
                {
                    "condition": null,
                    "attribute": null,
                    "transformations": 
                    [
                        {
                            "@odata.type": "#microsoft.graph.joinTransformation",
                            "separator": "-",
                            "input": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type": "#microsoft.graph.sourcedAttribute",
                                    "id": "extensionattribute1",
                                    "source": "user",
                                    "isExtensionAttribute": false
                                }
                            },
                            "input2": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type":"#microsoft.graph.valueBasedAttribute",
                                    "value": "ext"
                                 }
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

    Observação

    A Política de Declarações Personalizadas é uma política fortemente tipada e cada transformação usa um valor de @odata.type diferente.

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

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Resposta:

    {
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

Conteúdo relacionado