Referência do provedor de declarações personalizado

Artigo
04/04/2024

Neste artigo de referência, você pode saber mais sobre o esquema da API REST e a estrutura de política de mapeamento de declarações para eventos do provedor de declarações personalizado.

Evento de início de emissão de token

O evento de emissão de token do provedor de declarações personalizado permite que você enriqueça ou personalize os tokens de aplicativo com informações de sistemas externos. Essas informações não podem ser armazenadas como parte do perfil do usuário no diretório do Microsoft Entra.

Visão geral do componente

Para configurar e integrar uma extensão personalizada ao seu aplicativo, é necessário que diversos componentes sejam conectados. O diagrama a seguir mostra uma exibição de alto nível das relações e pontos de configuração criados para implementar uma extensão personalizada.

Você precisa ter um ponto de extremidade de REST API disponível publicamente. Nesse diagrama, está sendo representado pela Função do Azure. A API REST gera e retorna declarações personalizadas para a extensão personalizada. Ele está associado a um registro de aplicativo do Microsoft Entra.
Você precisa configurar uma extensão personalizada no Microsoft Entra que esteja configurada para se conectar à sua API.
Você precisa de um aplicativo que receba os tokens personalizados. Por exemplo, https://jwt.ms, um aplicativo web pertencente à Microsoft que mostra o conteúdo decodificado de um token.
O aplicativo, como o exemplo https://jwt.ms, precisa estar registrado no Microsoft Entra ID usando o registro do aplicativo.
Você precisa criar uma associação entre o seu aplicativo e sua extensão personalizada.
Opcionalmente, você pode proteger a Função do Azure com um provedor de autenticação. Neste artigo, usamos seu Microsoft Entra.

API REST

O ponto de extremidade da sua API REST é responsável por interagir com os serviços downstream. Por exemplo, bancos de dados, outras APIs REST, diretórios do LDAP ou quaisquer outros repositórios que contenham os atributos que você gostaria de adicionar à configuração do token.

A API REST retorna uma resposta HTTP para o Microsoft Entra ID que contém os atributos. Os atributos retornados por sua API REST não são adicionados a um token automaticamente. Em vez disso, a política de mapeamento de declarações de um aplicativo deve ser configurada para que qualquer atributo seja incluído no token. No Microsoft Entra, uma política de mapeamento de declarações modifica as declarações emitidas em tokens emitidos para aplicativos específicos.

Esquema da API REST

Para desenvolver sua própria API REST para o evento de início de emissão de token, use o contrato de dados da API REST a seguir. O esquema descreve o contrato para criar o manipulador de solicitações e respostas.

Sua extensão personalizada no Microsoft Entra ID faz uma chamada HTTP para a sua API REST com um conteúdo JSON. O conteúdo JSON contém dados de perfil do usuário, atributos de contexto de autenticação e informações sobre o aplicativo no qual o usuário deseja entrar. O valor id no JSON a seguir é um aplicativo da Microsoft que representa o serviço de eventos de autenticação do Microsoft Entra. Os atributos JSON podem ser usados por sua API para executar uma lógica adicional. A solicitação para a sua API tem o seguinte formato:

POST https://your-api.com/endpoint

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/<Your tenant GUID>/applications/<Your Test Application App Id>",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "<Your tenant GUID>",
        "authenticationEventListenerId": "<GUID>",
        "customAuthenticationExtensionId": "<Your custom extension ID>",
        "authenticationContext": {
            "correlationId": "<GUID>",
            "client": {
                "ip": "30.51.176.110",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2016-03-01T15:23:40Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "90847c2a-e29d-4d2f-9f54-c5b4d3f26471", // Client ID representing the Microsoft Entra authentication events service
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

O formato de resposta da API REST que o Azure espera tem o seguinte formato, no qual as declarações DateOfBirth e CustomRoles são retornadas para o Azure:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "DateOfBirth": "01/01/2000",
                    "CustomRoles": [
                        "Writer",
                        "Editor"
                    ]
                }
            }
        ]
    }
}

Quando um usuário B2B da organização Fabrikam se autentica na organização da Contoso, o conteúdo da solicitação enviado à API REST tem o elemento user no seguinte formato:

"user": {
    "companyName": "Fabrikam",
    "createdDateTime": "2022-07-15T00:00:00Z",
    "displayName": "John Wright",
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "mail": "johnwright@fabrikam.com",
    "preferredDataLocation": "EUR",
    "userPrincipalName": "johnwright_fabrikam.com#EXT#@contoso.onmicrosoft.com",
    "userType": "Guest"
}

Tipos de dados com suporte

A tabela a seguir mostra os tipos de dados compatíveis com provedores de declarações personalizados para o evento de início de emissão de token:

Tipo de dados	Com suporte
Cadeia de caracteres	verdadeiro
Matriz de cadeia de caracteres	Verdadeiro
Boolean	Falso
JSON	Falso

Limitações de tamanho de reivindicação

O tamanho máximo da declaração que um provedor de declarações pode retornar é limitado a 3KB. Essa é a soma de todos os pares de chave e valor retornados pela API REST.

Política de mapeamento de declarações

No Microsoft Entra, uma política de mapeamento de declarações modifica as declarações emitidas em tokens emitidos para aplicativos específicos. A política inclui declarações do seu provedor de declarações personalizado e a respectiva emissão no token.

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "true",
        "ClaimsSchema": [{
            "Source": "CustomClaimsProvider",
            "ID": "dateOfBirth",
            "JwtClaimType": "birthdate"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "customRoles",
            "JwtClaimType": "my_roles"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "correlationId",
            "JwtClaimType": "correlation_Id"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "apiVersion",
            "JwtClaimType": "apiVersion"
        },
        {
            "Value": "tokenaug_V2",
            "JwtClaimType": "policy_version"
        }]
    }
}

O elemento ClaimsSchema contém a lista de declarações a serem mapeadas com os seguintes atributos:

Origem descreve a origem do atributo, o CustomClaimsProvider. Observe que o último elemento contém um valor fixo com a versão da política, para fins de teste. Portanto, o atributo source é omitido.
ID é o nome das declarações que são retornadas pela Função do Azure que você criou.

Importante

O valor da ID do atributo diferencia maiúsculas de minúsculas. Certifique-se de digitar o nome da declaração exatamente como foi retornado pela Função do Azure.
JwtClaimType é um nome de declaração opcional no token emitido para o aplicativo OpenID Connect. Permite que você forneça um nome diferente que retorna no token JWT. Por exemplo, se a resposta da API tiver um valor de ID de dateOfBirth, poderá ser emitida como birthdate no token.

Após ter criado sua política de mapeamento de declarações, a próxima etapa é carregá-la no seu locatário do Microsoft Entra. Use a seguinte API de claimsMappingPolicy do Graph no seu locatário.

Importante

O elemento de definição deve ser uma matriz com um único valor de cadeia de caracteres. A cadeia de caracteres deve ser a versão encadeada e escapada da sua política de mapeamento de declarações. Você pode usar ferramentas como a https://jsontostring.com/ para encadear sua política de mapeamento de declarações.

Compartilhar via