Referência do provedor de declarações personalizadas

Artigo
07/27/2024

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

Evento de início de emissão de token

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

Visão geral do componente

Para configurar e integrar uma extensão personalizada com seu aplicativo, é necessário que vários componentes estejam conectados. O diagrama a seguir mostra uma exibição de alto nível dos pontos de configuração e relacionamentos criados para implementar uma extensão personalizada.

Você deve ter um ponto de extremidade da API REST disponível publicamente. Neste diagrama, ele é 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 Microsoft Entra.
Você precisa configurar uma extensão personalizada no Microsoft Entra ID, que está configurado para se conectar à sua API.
Você precisa de um aplicativo que receba os tokens personalizados. Por exemplo, https://jwt.ms um aplicativo Web de propriedade da Microsoft que exibe o conteúdo decodificado de um token.
O aplicativo, como o deve ser registrado no Microsoft Entra ID usando o https://jwt.ms registro do aplicativo.
Você deve criar uma associação entre 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 sua ID do Microsoft Entra.

API REST

Seu endpoint da API REST é responsável pela interface com serviços downstream. Por exemplo, bancos de dados, outras APIs REST, diretórios LDAP ou quaisquer outros armazenamentos 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 contendo os atributos. Os atributos que retornam pela API REST não são adicionados automaticamente a um token. Em vez disso, a política de mapeamento de declarações de um aplicativo deve ser configurada para qualquer atributo a ser incluído no token. No Microsoft Entra ID, 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 seguinte contrato de dados da API REST. O esquema descreve o contrato para projetar o manipulador de solicitação e resposta.

Sua extensão personalizada no Microsoft Entra ID faz uma chamada HTTP para sua API REST com uma carga JSON útil. A carga JSON contém dados de perfil de usuário, atributos de contexto de autenticação e informações sobre o aplicativo que o usuário deseja entrar. O id valor 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 para executar lógica extra pela sua API. A solicitação para sua API está no 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 está no seguinte formato, onde as declarações DateOfBirth e CustomRoles são retornadas ao 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 da Fabrikam se autentica na organização da Contoso, a carga útil da solicitação enviada para a API REST tem o user elemento 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 suportados:

A tabela a seguir mostra os tipos de dados suportados pelos provedores de declarações personalizadas para o evento de início de emissão de token:

Tipo de dados	Suportado
String	True
Matriz de cadeias de carateres	True
Booleano	False
JSON	False

Limitações do tamanho da reivindicação

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

Política de mapeamento de sinistros

No Microsoft Entra ID, uma política de mapeamento de declarações modifica as declarações emitidas em tokens emitidos para aplicativos específicos. Inclui declarações do seu fornecedor de declarações personalizadas e a sua emissão para o 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 ClaimsSchema elemento contém a lista de declarações a serem mapeadas com os seguintes atributos:

Source 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. Assim, o source atributo é omitido.
ID é o nome das declarações que retorna da Função do Azure que você criou.

Importante

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

Depois de criar sua política de mapeamento de declarações, a próxima etapa é carregá-la para seu locatário do Microsoft Entra. Use a seguinte API do GraphMappingPolicy em 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 stringified e escaped da sua política de mapeamento de declarações. Você pode usar ferramentas como https://jsontostring.com/ para restringir sua política de mapeamento de declarações.

Partilhar via