Configurar declarações de grupo e funções de aplicativo em tokens

Esse artigo ajuda você a configurar seus aplicativos com definições de funções de aplicativo e atribuir grupos de segurança a funções de aplicativo para que você possa melhorar a flexibilidade e o controle enquanto aumenta a segurança do aplicativo com menos privilégios.

O Microsoft Entra ID oferece suporte ao envio de grupos de segurança, funções de diretório do Microsoft Entra e grupos de distribuição atribuídos a um usuário como declarações em um token. É possível usar essa abordagem para direcionar a autorização em aplicativos. No entanto, o Microsoft Entra ID limita o suporte de grupo num token pelo tamanho do token. Quando o usuário é membro de muitos grupos, não há grupos no token.

Nesse artigo, você aprende uma abordagem alternativa para obter informações do usuário em tokens usando o suporte do grupo Microsoft Entra. Em vez disso, você configura seus aplicativos com definições de funções de aplicativo e atribui grupos a funções de aplicativo. Essa prática recomendada para desenvolvedores de Zero Trust melhora a flexibilidade e o controle enquanto aumenta a segurança do aplicativo com menos privilégios.

É possível configurar declarações de grupo em tokens que podem ser usados em seus aplicativos para autorização. Lembre-se de que as informações do grupo no token são atuais somente quando você recebe o token. As declarações de grupo suportam dois padrões principais:

• Grupos identificados pelo atributo de OID (identificador de objeto) do Microsoft Entra.
• Grupos identificados pelo atributo sAMAccountName ou GroupSID para usuários e grupos sincronizados do Active Directory.

A associação ao grupo pode orientar as decisões de autorização. Por exemplo, o exemplo a seguir mostra algumas declarações em um token. É possível adicionar declarações de grupo e funções a tokens de ID ou de acesso.

"aud": "e18c04b1-4868-4b93-93d1-8d71f17ab99b", 
"iss": "https://login.microsoftonline.com/833ced3d-cb2e-41de-92f1-29e2af035ddc/v2.0", 
"iat": 1669657224, "nbf": 1669657224, "exp": 1669661124, 
"groups": [ 
   "0760b6cf-170e-4a14-91b3-4b78e0739963", 
   "3b2b0c93-acd8-4208-8eba-7a48db1cd4c0" 
 ],
"oid": "cb7eda1b-d09a-40ae-b8bb-37836ebc6abd",
"sub": "3OBtLXUC2ZrN_ADLNjW9X4o0lcd61py7lgHw3Skh77s",
"tid": "833ced3d-cb2e-41ce-92f1-29e2af035ddc", 
"ver": "2.0", 
"wids": [ 
   "cf1c38e5-3621-4004-a7cb-879624dced7c", 
   "b79fbf4d-3ef9-4689-8143-76b194e85509" 
 ]

A matriz de declarações groups compreende os IDs dos grupos dos quais esse usuário é membro. A matriz wids compreende os IDs das funções atribuídas do Microsoft Entra a esse usuário. Aqui, cf1c38e5-3621-4004-a7cb-879624dced7c mostra que as funções atribuídas a esse usuário incluem Desenvolvedor de Aplicativos e membro padrão, como 3b2b0c93-acd8-4208-8eba-7a48db1cd4c0 indica.

Seu aplicativo pode tomar decisões de autorização com base na presença ou ausência dessas declarações e seus valores. Consulte Funções integradas do Microsoft Entra para obter uma lista de valores para a declaração wids.

Para adicionar as revindicações groups e wids aos seus tokens, selecione Todos os grupos, como mostra o exemplo a seguir da tela Registros de aplicativos | Configuração de token | Reivindicações opcionais | Editar reivindicação de grupos.

Excesso de idade do grupo

Ao solicitar todos os grupos no token, conforme mostrado no exemplo acima, você não pode confiar que o token tenha a declaração groups nele. Existem limites de tamanho para tokens e declarações groups para que estes não fiquem muito grandes. Quando o usuário é membro de muitos grupos, seu aplicativo precisa obter a associação do usuário ao grupo do Microsoft Graph. Os limites para grupos em uma declaração groups são:

• 200 grupos para tokens da web JSON (JWT).
• 150 grupos para tokens SAML (Security Assertion Markup Language).
• Seis grupos ao utilizar o fluxo implícito (por exemplo, utilizando ASP.NET núcleo que obtém tokens de ID por meio da parte de fluxo implícito de um fluxo híbrido).
  • O fluxo implícito não é mais recomendado para aplicativos Web de página única.
  • O fluxo implícito pode ser usado em aplicativos Web apenas para o token de ID, nunca o token de acesso, em um fluxo híbrido OAuth2.

Se você estiver usando OpenID Connect ou OAuth2, poderá ter até 200 grupos no seu token. Se você estiver utilizando SAML, poderá ter apenas 150 grupos porque os tokens SAML são maiores que os tokens OAuth2 e OpenID Connect. Se você estiver utilizando o fluxo implícito, o limite será seis porque essas respostas aparecem na URL. Em todos esses casos, em vez de ter uma declaração groups, você verá uma indicação (conhecida como excesso de grupo) que informa que o usuário é membro de muitos grupos para caber no seu token.

No exemplo de token a seguir, para uma conexão OpenID ou OAuth2, token web JSON (JWT), não há uma groups declaração se o usuário for membro de muitos grupos. Em vez disso, há uma declaração _claim_names que contém um membro groups da matriz.

No exemplo de token acima, você vê que a declaração groups deve ser mapeada para src1. Em teoria, você procuraria a declaração _claim_sources e encontraria o membro src1. A partir daí, você encontraria a consulta Gráfico que utilizaria para obter a associação ao grupo. No entanto, há um problema com o que você vê na consulta Graph de exemplo. Ele vai para o Azure AD Graph (que a Microsoft está substituindo), portanto, não o use.

A indicação implícita de excesso de fluxo é feita com uma declaração hasgroups em vez da declaração groups.

Para garantir a autorização adequada usando membros de grupo, faça com que seu aplicativo verifique a declaração groups. Se presente, utilize essa declaração para determinar a associação de grupo do usuário. Se não houver uma declaração groups, verifique a existência de uma declaração hasgroups ou de uma declaração _claim_names com um membro groups da matriz. Se qualquer uma dessas declarações estiver presente, o usuário será membro de muitos grupos para o token. Nesse caso, seu aplicativo deve utilizar o Microsoft Graph para determinar a associação de grupo para o usuário. Consulte Listar associações de um usuário (diretas e transitivas) para encontrar todos os grupos, diretos e transitivos, dos quais o usuário é membro.

Se seu aplicativo exigir informações de associação de grupo em tempo real, utilize o Microsoft Graph para determinar a associação ao grupo. Lembre-se de que as informações contidas no token que você recebe estão atualizadas apenas no momento em que você adquire o token.

Consulte o exemplo a seguir da tela Registros de aplicativo | Configuração de token | Declarações opcionais | Editar grupos. Uma forma de evitar uma declaração de excedente de grupo é selecionar Grupos atribuídos ao aplicativo na tela Editar solicitação de grupos em vez de Todos os grupos.

Quando você seleciona Grupos atribuídos ao aplicativo, um grupo será incluído na declaração groups se as seguintes condições forem verdadeiras:

• o grupo é atribuído ao aplicativo corporativo
• o usuário é membro direto do grupo

Na ocasião da publicação deste artigo, a opção Grupos atribuídos ao aplicativo não oferece suporte à associação indireta. A atribuição de grupo requer pelo menos uma licença de nível P1. Um locatário gratuito não pode atribuir grupos a um aplicativo.

Grupos e funções de aplicativos

Outra maneira de evitar o problema de excesso de grupo é que o aplicativo defina funções de aplicativo que permitam usuários e grupos como tipos de membros. Como mostra o exemplo a seguir da tela Registros de aplicativos | Funções de aplicativo | Criar função de aplicativo, selecione Usuários/grupos para Tipos de membros permitidos.

Depois de criar a função de aplicativo no registro do aplicativo, os profissionais de TI podem atribuir usuários e grupos à função. Seu aplicativo recebe uma declaração roles em seu token (token de ID para aplicativo, token de acesso para APIs) com todas as funções atribuídas ao usuário conectado, conforme mostrado no exemplo de token a seguir.

"aud": "acaf6ce9-81f0-462a-a93d-a314070738d3",
"iss": "https://login.microsoftonline.com/833ced3d-cb2e-41de-92f1-29e2af035ddc/v2.0",
"iat": 1670826509, "nbf": 1670826509, "exp": 1670830409,
"name": "Kyle Marsh",
"oid": "cb7eda1b-d09a-419e-b8bb-37836ebc6abd",
"preferred_username": "kylemar@idfordevs.dev",
"roles": [
 "Approver",
 "Reviewer" 
],
"sub": "dx-4lf-0loB3c3uVrULnZ2VTLuRRWYff0q7-QlIfYU4",
"tid": "833ced3d-cb3e-41de-92f1-29e2af035ddc",

Lembre-se de fazer com que seu aplicativo lide com as seguintes condições:

• ausência da declaração roles
• o usuário não tem atribuição de função
• vários valores na declaração roles quando o usuário tem mais de uma atribuição de função

Ao criar funções de aplicativo que permitem usuários e grupos como membros, sempre defina uma função de usuário de linha de base sem funções de autorização elevadas. Quando uma configuração de Aplicativo Empresarial requer atribuição, somente os usuários com atribuição direta a um aplicativo ou associação a um grupo atribuído ao aplicativo podem usar o aplicativo.

Se o seu aplicativo tiver funções de aplicativo definidas que permitam usuários e grupos como membros, quando um usuário ou grupo for atribuído ao aplicativo, uma das funções de aplicativo definidas deverá fazer parte da atribuição do usuário ou do grupo ao aplicativo. Se o seu aplicativo tiver definido apenas funções elevadas (como admin) para o aplicativo, todos os usuários e grupos receberão a função de administrador. Quando você define uma função base (como user), os usuários e grupos atribuídos ao aplicativo podem receber a função de usuário base.

Além de evitar declarações de excedente de grupo, outra vantagem de usar funções é não precisar mapear entre uma ID ou nome de grupo e o que isso significa em seu aplicativo. Por exemplo, seu código pode procurar a declaração de função de administrador em vez de iterar por meio de grupos nas declarações groups e decidir quais IDs de grupo devem ter permissão para a funcionalidade de administrador.

Verifique e use funções em seu código

Quando você define funções de aplicativo para seu aplicativo, é sua responsabilidade implementar a lógica de autorização para essas funções. Consulte Implementar controle de acesso baseado em função em aplicativos para saber como você pode implementar a lógica de autorização no seus aplicativos.

Próximas etapas

• Personalizar tokens descreve as informações que você pode receber nos tokens do Microsoft Entra. Ele explica como personalizar tokens para melhorar a flexibilidade e o controle e, ao mesmo tempo, aumentar a segurança de confiança zero do aplicativo com menos privilégios.
• O artigo Configurar declarações de grupo para aplicativos usando o Microsoft Entra ID mostra como o Microsoft Entra ID pode fornecer informações de associação de grupo de um usuário em tokens para uso em aplicativos.
• O artigo Práticas recomendadas de segurança para propriedades de aplicativos descreve o URI de redirecionamento, tokens de acesso (usados para fluxos implícitos), certificados e segredos, URI de ID do aplicativo e propriedade de aplicativos.
• Escopos, permissões e consentimento da plataforma de identidade da Microsoft explica os conceitos fundamentais de acesso e autorização para ajudar você a criar aplicativos mais seguros e confiáveis.
• Utilize as práticas recomendadas de desenvolvimento de gerenciamento de identidades e acesso com Confiança Zero no seu ciclo de vida de desenvolvimento de aplicativos para criar aplicativos seguros.