Partilhar via

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

  • 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. A personalização de declarações suporta a configuração de declarações para aplicativos que usam os protocolos SAML, OAuth e OpenID Connect. Você pode usar a personalização 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.

Neste guia de instruções, abordamos alguns cenários comuns que podem ajudá-lo a entender como usar a política de Declarações Personalizadas.

Pré-requisitos

  • Um locatário do Microsoft Entra.
  • Um aplicativo corporativo configurado no centro de administração do Microsoft Entra.
  • Para usuários do PowerShell, baixe o SDK mais recente do Microsoft Graph PowerShell. Este passo é opcional.

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

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

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

Abra o Microsoft Graph Explorer em seu navegador entre no Microsoft Graph Explorer como pelo menos um Administrador de Aplicativos, escolha um dos seguintes cenários.

Depois de 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 Considerações de segurança.

Omitir as declarações básicas dos tokens

Neste exemplo, você cria uma política de declarações personalizada que remove o conjunto de declarações básicas dos tokens emitidos para a entidade de serviço vinculada.

  1. No Microsoft Graph Explorer, identifique o aplicativo que você deseja configurar a política de declarações personalizada para usar a API da entidade de serviço.

  2. Crie a política de Declarações Personalizadas executando a seguinte API. 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 do Pedido:

    {
    "includeBasicClaimSet": false
}

  3. Para ver a 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": []
}

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

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

  1. No Microsoft Graph Explorer, identifique o aplicativo que você deseja configurar a política de declarações personalizada para usar a API da entidade de serviço.

  2. Crie a política de Declarações Personalizadas executando a seguinte API. 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 do Pedido:

    {
    "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

Neste exemplo, você atualiza uma política para emitir 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. No Microsoft Graph Explorer, identifique o aplicativo que você deseja configurar a política de declarações personalizada para usar a API da entidade de serviço.

  2. Crie a política de declarações personalizada executando a seguinte API. Esta política emite uma reivindicação JoinedData personalizada para tokens.

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

    Corpo do Pedido:

    {
    "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"
                                 }
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

    Nota

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

  3. Para ver sua nova política e obtê-la ObjectId, 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": [...]
}

Conteúdos relacionados