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 do Microsoft Entra e como você pode personalizá-los. É o quinto de uma série de artigos sobre como desenvolvedores independentes de software (ISVs) podem criar e otimizar seus aplicativos para o Microsoft Entra ID. Nesta série, você pode saber mais sobre estes tópicos:

• Microsoft Entra ID for Independent Software Developers 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.
• Establish applications in the Microsoft Entra ID ecosystem descreve como usar o centro de administração do Microsoft Entra ou a API (Application Programming Interface) do Microsoft Graph para registar aplicações 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 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 de permissão delegada ou API. Não é possível personalizar tokens de carga de trabalho.

Se seu aplicativo implementa OpenID Connect (OIDC) e solicita tokens de ID, você pode 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 para um aplicativo personalizar os tokens de acesso que recebe 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 reivindicações opcionais lista as reivindicações opcionais disponíveis.

Para aplicativos multilocatário, as declarações opcionais estão disponíveis para todos os locatário. Você pode configurar seus tokens de acesso à API para incluir a declaração opcional onprem_sid 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 deve manipular quando o token não inclui a declaração opcional que você configurou. Por exemplo, o utilizador pode ser um utilizador apenas do Microsoft Entra ID que não tem um identificador de segurança locais. 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 é opcional e requer tratamento especial. Um aplicativo ou API pode incluir grupos de segurança dos utilizadores e grupos aninhados no token ou incluir os grupos de segurança e grupos aninhados com listas de distribuição através do atributo de grupos. Os aplicativos podem incluir funções de diretório de um usuário no token com a declaração wids (funções abrangentes de locatário). A inclusão de todos os grupos de usuários e/ou listas de distribuição pode resultar em nenhum grupo ou lista de distribuição no token.

O tamanho do token limita o total de entradas nos grupos declarados 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 grupos. Se o seu token contiver uma reivindicação de sobrerregra de grupo, recorra ao Microsoft Graph para 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 as associações de grupo do usuário em 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 excesso de grupo, configure a declaração de grupos para incluir apenas grupos aos quais um aplicativo tem atribuição. Com essa abordagem, a declaração de grupos 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 tem atribuição.

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

Avalie as compensações para o uso de grupos ou funções. Para ISVs, recomendamos o uso de funções em vez de grupos.

Próximos passos

• Microsoft Entra ID for Independent Software Developers 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 aplicações no ecossistema Microsoft Entra ID descreve como usar o centro de administração do Microsoft Entra ou a API do Microsoft Graph para registar aplicações num inquilino 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 a autorização quando um ser humano individual interage e dirige um aplicativo, quando as APIs agem em nome de um usuário e quando os aplicativos ou serviços funcionam de forma independente.