Personalizar tokens

Este artigo ajuda você a criar segurança em aplicativos com tokens de ID, tokens de acesso e tokens de segurança da plataforma de identidade da Microsoft. Ele descreve as informações que você pode receber em tokens Microsoft Entra e como personalizá-los. É o quinto de uma série de artigos sobre como os desenvolvedores de software independentes (ISVs) podem criar e otimizar seus aplicativos para o Microsoft Entra ID. Nesta série, você pode aprender mais sobre esses tópicos:

• O Microsoft Entra ID para desenvolvedores independentes de software descreve como usar esse serviço de gerenciamento de identidade e acesso baseado em nuvem para permitir que os funcionários acessem recursos com seu aplicativo.
• Estabelecer aplicativos no ecossistema Microsoft Entra ID descreve como usar o Centro de administração Microsoft Entra ou a API (Interface de Programação de Aplicativos) do Microsoft Graph para registrar aplicativos em um locatário Microsoft Entra ID.
• Autenticar aplicativos e usuários descreve como os aplicativos usam o Microsoft Entra ID para autenticar usuários e aplicativos.
• Autorizar aplicativos, recursos e cargas de trabalho discute a autorização quando humanos individuais interagem e direcionam um aplicativo. Nesse cenário, as APIs atuam para um usuário e quando os aplicativos ou serviços funcionam de forma independente.

A principal operação para aplicativos que se conectam ao Microsoft Entra ID é solicitar e processar tokens. Como desenvolvedor, você pode personalizar o token que o Microsoft Entra ID envia para seu aplicativo ou API de permissão delegada. Não é possível personalizar tokens de carga de trabalho.

Se seu aplicativo implementar OpenID Connect (OIDC) e solicitar tokens de ID, você poderá personalizar o token de ID para seu aplicativo. Se você implementar uma API, poderá personalizar os tokens de acesso que os aplicativos que chamam sua API recebem. Não é possível que um aplicativo personalize os tokens de acesso recebidos que autorizam um aplicativo a acessar uma API.

O principal método de personalização de token para ISVs é adicionar declarações opcionais aos tokens no registro do aplicativo. A referência de declarações opcionais lista as declarações opcionais disponíveis.

Para aplicativos multilocatários, as declarações opcionais estão disponíveis para todos os locatários. Você pode configurar seus tokens de acesso à API para incluir a onprem_sid declaração opcional para incluir a declaração de identidade de segurança local do usuário. Embora você possa configurar uma declaração opcional, seu aplicativo sempre deverá lidar com quando o token não incluir a declaração opcional que você configurou. Por exemplo, o usuário pode ser um usuário somente do Microsoft Entra ID que não possui um identificador de segurança local. Nesse caso, o Microsoft Entra ID não inclui a declaração opcional no token. O Microsoft Entra ID não retorna uma declaração com um valor vazio ("").

A reivindicação de grupos é uma reivindicação opcional que requer tratamento especial. Um aplicativo ou API pode incluir grupos de segurança e grupos aninhados de usuários no token ou incluir os grupos de segurança e grupos aninhados com listas de distribuição com a reivindicação de grupos. Os aplicativos podem incluir funções de diretório de um usuário no token com a declaração wids (funções para todo o locatário). Incluir todos os grupos e/ou listas de distribuição de usuários pode resultar na ausência de grupos ou listas de distribuição no token.

O tamanho do token limita o total de entradas na reivindicação de grupos a 200 para aplicativos OAuth 2.0, 150 para aplicativos SAML e seis para aplicativos que usam concessão implícita como parte de um fluxo híbrido. Quando há muitos grupos, o token tem uma reivindicação de excesso de grupo. Se o seu token contiver uma declaração de excesso de grupo, volte a ligar para o Microsoft Graphpara obter os grupos do utilizador. Como você não tem como saber quando o usuário é membro de muitos grupos, sempre inclua a capacidade de chamar o Microsoft Graph para obter as associações de grupo do usuário no seu aplicativo. Recomendamos usar o Microsoft Graph em vez de usar a declaração de grupos devido aos requisitos de código do Microsoft Graph.

Para evitar o excesso de grupo, configure a declaração de grupos para incluir apenas grupos aos quais um aplicativo tenha atribuição. Com essa abordagem, a declaração groups inclui apenas grupos atribuídos a um aplicativo ou API quando o usuário é membro do grupo (sem suporte para grupos aninhados). O usuário deve ser um membro direto do grupo ao qual um aplicativo está atribuído.

Outra forma de evitar o excesso de grupo é usar funções em vez de grupos. Você pode configurar funções para sua aplicação ou API que recebe em seu token. Os administradores de TI podem atribuir grupos às funções que você define em um locatário Microsoft Entra ID com licenciamento P1 ou superior. Após a atribuição, seu token inclui uma declaração de funções com o aplicativo das funções atribuídas ao usuário ou funções com base na associação ao grupo do usuário.

Avalie as vantagens e desvantagens do uso de grupos ou funções. Para ISVs, recomendamos o uso de funções em vez de grupos.

Próximas etapas

• Microsoft Entra ID para desenvolvedores de software independentes descreve como usar esse serviço de gerenciamento de identidade e acesso baseado em nuvem para permitir que funcionários acessem recursos com seu aplicativo.
• Estabelecer aplicativos no ecossistema do Microsoft Entra ID descreve como usar o Centro de administração do Microsoft Entra ou a API do Microsoft Graph para registrar aplicativos em um locatário do Microsoft Entra ID.
• Autenticar aplicativos e usuários descreve como os aplicativos usam o Microsoft Entra ID para autenticar usuários e aplicativos.
• Autorizar aplicativos, recursos e cargas de trabalho discute autorização quando um indivíduo interage e dirige um aplicativo, quando APIs agem em nome de um usuário e quando aplicativos ou serviços funcionam de forma independente.