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

2025-04-22

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 reivindicaçã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

Um Locatário do Microsoft Entra.
Um Aplicativo Empresarial configurado no Centro de Administração do Microsoft Entra.
Para usuários do PowerShell, baixe o SDK mais recente do Microsoft Graph PowerShell. Esta etapa é opcional.

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:

Como usar a Política de Declarações Personalizadas (Versão Prévia)
Como usar a Política de Mapeamento de Declarações

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 aos objetos das 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.

Omita as declarações básicas dos tokens
Incluir o EmployeeID e o TenantCountry como declarações em tokens
Usar uma transformação de declarações em tokens

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 dos tokens

Neste exemplo, você criará 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.

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.
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
}
```

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

Neste exemplo, você criará 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.

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.

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": []
                }
            ]
        }
    ]
}

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 as entidades de serviço vinculadas. Esta afirmação contém um valor criado pela combinação dos dados armazenados no atributo extensionattribute1 do objeto do usuário com "-ext". Neste exemplo, excluímos o conjunto de declarações básicas nos tokens.

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.

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.

Para ver a nova política e obter a política ObjectId, 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": [...]
}

Saiba mais sobre as diferenças entre as políticas na Personalização de declarações usando uma política
Logins de identidade no Microsoft Graph

Compartilhar via

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

Pré-requisitos

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

Omitir as declarações básicas dos tokens

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

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

Conteúdo relacionado

Comentários

Recursos adicionais

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