Proteger aplicativos Java Spring Boot usando grupos e declarações de grupo

Este artigo apresenta um aplicativo Web Java Spring Boot que usa a biblioteca de clientes Microsoft Entra ID Spring Boot Starter para Java para autenticação, autorização e aquisição de token. O aplicativo usa o protocolo OpenID Connect para conectar usuários e restringe o acesso a páginas com base na associação ao grupo de segurança do Microsoft Entra ID.

O diagrama a seguir mostra a topologia do aplicativo:

O aplicativo cliente usa a biblioteca de clientes do Microsoft Entra ID Spring Boot Starter para Java para conectar usuários em um locatário do Microsoft Entra ID e obter um token de ID do Microsoft Entra ID.

O token de ID contém a declaração de grupos. O aplicativo carrega declarações na lista do Spring GrantedAuthorities para o usuário conectado. Esses valores determinam quais páginas o usuário está autorizado a acessar.

Para assistir a um vídeo que aborda esse cenário, consulte Implementar autorização nos seus aplicativos usando funções de aplicativo, grupos de segurança, escopos e funções de diretório.

Pré-requisitos

• Versão 15 do JDK: Este exemplo foi desenvolvido em um sistema com Java 15, mas pode ser compatível com outras versões.
• Maven 3
• O Pacote de extensão Java para Visual Studio Code é recomendado para executar este exemplo no Visual Studio Code.
• Um locatário do Microsoft Entra ID. Para obter mais informações, confira Início Rápido: Configurar um locatário.
• Uma conta de usuário no seu locatário do Microsoft Entra ID. Este exemplo não funciona com uma conta pessoal da Microsoft. Portanto, se você tiver conectado no portal do Azure com uma conta pessoal e não tiver uma conta de usuário em seu diretório, será necessário criar uma agora.
• Dois grupos de segurança, chamados AdminGroup e UserGroup, contendo o usuário ou usuários que você quer conectar e testar este exemplo. Como alternativa, você pode adicionar o usuário a dois grupos de segurança existentes em seu locatário. Se você optar por usar grupos existentes, modifique a configuração de exemplo para usar o nome e a ID do objeto dos grupos de segurança existentes.
• Visual Studio Code
• Ferramentas do Azure para o Visual Studio Code

Recomendações

• Alguma familiaridade com o Spring Framework.
• Alguma familiaridade com o terminal Linux/OSX.
• jwt.ms para inspecionar seus tokens.
• Fiddler para monitorar sua atividade de rede e solução de problemas.
• Siga o Blog do Microsoft Entra ID para se atualizar com os desenvolvimentos mais recentes.

Configurar o exemplo

As seções a seguir mostram como configurar o aplicativo de exemplo.

Clone ou baixe o repositório de exemplo.

Para clonar o exemplo, abra uma janela do Bash e use o seguinte comando:

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 4-spring-web-app/3-Authorization-II/groups

Como alternativa, navegue até o repositório ms-identity-msal-java-samples, baixe-o como um arquivo .zip e extraia-o para o disco rígido.

Importante

Para evitar limitações de comprimento de caminho de arquivo no Windows, clone ou extraia o repositório em um diretório próximo à raiz do disco rígido.

Registrar o aplicativo de exemplo com seu locatário do Microsoft Entra ID

Há um projeto neste exemplo. As seções a seguir mostram como registrar o aplicativo usando o portal do Azure.

Escolha o locatário do Microsoft Entra ID no qual você deseja criar seus aplicativos

Siga as etapas a seguir para escolher o locatário:

1. Entre no portal do Azure.

2. Se sua conta estiver presente em mais de um locatário do Microsoft Entra ID, selecione seu perfil no canto do portal do Azure e selecione Mudar diretório para alterar sua sessão para o locatário desejado do Microsoft Entra ID.

Registrar o aplicativo (java-spring-webapp-groups)

Para registrar o aplicativo, use estas etapas:

1. Navegue até o portal do Azure e selecione Microsoft Entra ID.

2. Selecione Registros de aplicativo no painel de navegação e selecione Novo registro.

3. Na página Registrar um aplicativo que aparece, insira as seguintes informações de registro do aplicativo:

   • Na seção Nome, insira um nome de aplicativo relevante para exibição aos usuários do aplicativo: por exemplo, java-spring-webapp-groups.
   • Em Tipos de contas com suporte, selecione Contas somente neste diretório organizacional.
   • Na seção URI de redirecionamento (opcional), selecione Web na caixa de combinação e insira o seguinte URI de redirecionamento: http://localhost:8080/login/oauth2/code/.

4. Selecione Registrar para criar o aplicativo.

5. Na página de registro do aplicativo, localize e copie o valor do ID do aplicativo (cliente) para uso posterior. Use esse valor no(s) arquivo(s) de configuração do aplicativo.

6. Na página de registo do aplicativo, selecione Segredos de certificados & no painel de navegação para abrir a página em que possa gerar segredos e carregar certificados.

7. Na seção Segredos do Cliente, escolha Novo Segredo do Cliente.

8. Insira uma descrição, por exemplo, segredo do aplicativo.

9. Selecione uma das durações disponíveis: 6 meses, 12 meses ou Personalizar.

10. Selecione Adicionar. O valor gerado é exibido.

11. Copie e salve o valor gerado para uso nas etapas posteriores. Esse valor é necessário para os arquivos de configuração do código. Esse valor não é exibido novamente e você não pode recuperá-lo por outros meios. Portanto, salve-o no portal do Azure antes de navegar para qualquer outra tela ou painel.

12. Na página de registro do aplicativo, selecione Permissões de API no painel de navegação para abrir a página em que é possível adicionar acesso às APIs de que o aplicativo precisa.

13. Selecione Adicionar permissão.

14. Verifique se a guia APIs da Microsoft está selecionada.

15. Na seção APIs da Microsoft frequentemente utilizadas, selecione Microsoft Graph.

16. Na seção Permissões delegadas, selecione GroupMember.Read.All da lista. Use a caixa de pesquisa, se necessário. Essa permissão é necessária para obter associações de grupo por meio do Graph se o cenário de excedente ocorrer.

17. Selecione o botão para conceder o consentimento do administrador para GroupMember.Read.All.

18. Escolha Adicionar permissões.

Criar grupos de segurança

Use as etapas a seguir para criar grupos de segurança:

1. Navegue até o portal do Azure e selecione Microsoft Entra ID.

2. Selecione Grupos no painel de navegação.

3. No painel Grupos, selecione Novo Grupo e forneça as seguintes informações:

   • Em Tipo de grupo, selecione Segurança.
   • Em Nome do grupo, insira AdminGroup.
   • Em Descrição do grupo, insira Grupo de Segurança do Administrador.
   • Adicione Proprietários de Grupo e Membros do grupo que você deseja usar e testar neste exemplo.
   • Selecione Criar.

4. No painel Grupos, selecione Novo Grupo e forneça as seguintes informações:

   • Em Tipo de grupo, selecione Segurança.
   • Para Nome do grupo, insira UserGroup.
   • Em Descrição do grupo, insira Grupo de segurança do usuário.
   • Adicione Proprietários de Grupo e Membros do grupo que você deseja usar e testar neste exemplo.
   • Selecione Criar.

Para obter mais informações, veja Gerenciar grupos do Microsoft Entra e associação a grupos.

Configurar grupos de segurança

Você tem as seguintes opções para configurar melhor o aplicativo para receber a declaração de grupos:

• Receba todos os grupos aos quais o usuário conectado está atribuído em um locatário do Microsoft Entra ID, incluindo grupos aninhados. Para obter mais informações, consulte a seção Configurar o aplicativo para receber todos os grupos aos quais o usuário conectado está atribuído, inclusive os grupos aninhados.

• Receber os valores de reivindicação de grupos de um conjunto filtrado de grupos com os quais o aplicativo está programado para trabalhar. Para obter mais informações, consulte a seção Configurar o aplicativo para receber os valores de reivindicação de grupos de um conjunto filtrado de grupos aos quais um usuário pode ser atribuído. Essa opção não está disponível na edição gratuita do Microsoft Entra ID.

Observação

Para obter o grupo local samAccountName ou On Premises Group Security Identifier em vez da ID do grupo, consulte a seção Pré-requisitos para usar atributos de grupo sincronizados do Active Directory em Configurar declarações de grupo para aplicativos usando o Microsoft Entra ID.

Configurar o aplicativo para receber todos os grupos aos quais o usuário conectado está atribuído, incluindo grupos aninhados

Siga as etapas a seguir para configurar o aplicativo:

1. Na página de registro do aplicativo, selecione Configuração de Token no painel de navegação para abrir a página em que você pode configurar os tokens fornecidos por declarações emitidos para o seu aplicativo.

2. Selecione Adicionar declaração de grupos para abrir a tela Editar declaração de grupos.

3. Selecione Grupos de segurança OU Todos os grupos (inclui listas de distribuição, mas não grupos atribuídos ao aplicativo). Escolher ambas nega o efeito da opção Grupos de segurança.

4. Na seção ID, selecione ID do Grupo. Essa seleção faz com que o Microsoft Entra ID envie a ID de objeto dos grupos aos quais o usuário está atribuído na declaração de grupos do token de ID que seu aplicativo recebe depois de conectar um usuário.

Configurar o aplicativo para receber os valores de declaração de grupos de um conjunto filtrado de grupos aos quais um usuário pode ser atribuído

Essa opção é útil quando os seguintes casos são verdadeiros:

• Seu aplicativo está interessado em um conjunto selecionado de grupos aos quais um usuário conectado pode ser atribuído.
• Seu aplicativo não está interessado em todos os grupos de segurança aos quais esse usuário está atribuído no locatário.

Essa opção ajuda o aplicativo a evitar o problema excedente.

Observação

Esse recurso não está disponível na edição gratuita do Microsoft Entra ID.

As atribuições de grupos aninhados não estão disponíveis ao usar essa opção.

Para habilitar essa opção em seu aplicativo, siga as etapas a seguir:

1. Na página de registro do aplicativo, selecione Configuração de Token no painel de navegação para abrir a página em que você pode configurar os tokens fornecidos por declarações emitidos para o seu aplicativo.

2. Selecione Adicionar declaração de grupos para abrir a tela Editar declaração de grupos.

3. Selecione Grupos atribuídos ao aplicativo e não selecione nenhuma outra opção. Se você escolher mais opções, como Grupos de segurança ou Todos os grupos (inclui listas de distribuição, mas não grupos atribuídos ao aplicativo), essas opções negarão o efeito da opção Grupos atribuídos ao aplicativo.

4. Na seção ID, selecione ID do Grupo. Essa seleção faz com que o Microsoft Entra ID envie a ID de objeto dos grupos aos quais o usuário está atribuído na declaração de grupos do token de ID que seu aplicativo recebe depois de conectar um usuário.

5. Se você estiver expondo uma API Web usando a opção Expor uma API, também poderá escolher a opção ID de Grupo na seção Acesso. Essa seleção faz com que o Microsoft Entra ID envie a ID de objeto dos grupos aos quais o usuário está atribuído na declaração de grupos do token de acesso emitido para os aplicativos cliente da API.

6. Na página de registro do aplicativo, selecione Visão geral no painel de navegação para abrir a tela de visão geral do aplicativo.

7. Selecione o hiperlink com o nome do aplicativo em Aplicativo gerenciado no diretório local. Esse título de campo pode estar truncado, por exemplo, Aplicativo gerenciado em .... Ao selecionar esse link, você navega até a página Visão geral do aplicativo empresarial associada à entidade de serviço do aplicativo no locatário em que você o criou. Você pode navegar de volta para a página de registro do aplicativo usando o botão Voltar do seu navegador.

8. Selecione Usuários e grupos no painel de navegação para abrir a página na qual você pode atribuir usuários e grupos ao seu aplicativo.

9. Selecione Adicionar usuário.

10. Selecione Usuário e grupos na tela resultante.

11. Escolher os grupos que deseja atribuir a este aplicativo.

12. Selecione Selecionar para concluir a seleção dos grupos.

13. Selecione Atribuir para concluir o processo de atribuição em grupo.

    Seu aplicativo agora recebe esses grupos selecionados na declaração de grupos quando um usuário que se conecta ao aplicativo é membro de um ou mais desses grupos atribuídos.

14. Selecione Propriedades no painel de navegação para abrir a página que lista as propriedades básicas do seu aplicativo. Defina a marca Atribuição de usuário necessária? como Sim.

Importante

Quando você define Atribuição de usuário necessária? como Sim, o Microsoft Entra ID verifica se somente os usuários atribuídos ao seu aplicativo no painel Usuários e grupos podem entrar no seu aplicativo. É possível atribuir usuários diretamente ou por meio da atribuição de grupos de segurança aos quais eles pertencem.

---

Configurar o exemplo de código para usar o registro do aplicativo e os grupos de segurança (java-spring-webapp-groups)

Use as seguintes etapas para configurar o aplicativo:

Observação

Nas etapas a seguir, ClientID é o mesmo que Application ID ou AppId.

1. Abrir o projeto no seu IDE.

2. Abra o arquivo src\main\resources\application.yml .

3. Localize o espaço reservado Enter_Your_Tenant_ID_Here e substitua o valor existente pela ID de locatário do Microsoft Entra.

4. Localize o espaço reservado Enter_Your_Client_ID_Here e substitua o valor existente pelo ID do aplicativo ou clientId do aplicativo java-spring-webapp-groups copiado do portal do Azure.

5. Localize o espaço reservado Enter_Your_Client_Secret_Here e substitua o valor existente pelo valor que você salvou durante a criação do java-spring-webapp-groups copiado do portal do Azure.

6. Localize o espaço reservado Enter_Your_Admin_Group_ID_Here e substitua o valor existente pelo objectId valor do seu valor do seu AdminGroup.

7. Localize o espaço reservado Enter_Your_User_Group_ID_Here e substitua o valor existente pelo valor do objectId valor do seu AdminGroup.

8. Abra o arquivo src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootwebapp/SampleController.java.

9. Localize o espaço reservado Enter_Your_Admin_Group_ID_Here e substitua o valor existente pelo objectId valor do seu valor do seu AdminGroup.

10. Localize o espaço reservado Enter_Your_User_Group_ID_Here e substitua o valor existente pelo valor do objectId valor do seu AdminGroup.

Execute o exemplo

Implantar nos Aplicativos de Contêiner do Azure

As seções a seguir mostram como implantar o exemplo no Aplicativos de Contêiner do Azure.

Pré-requisitos

• Uma conta do Azure. Crie uma conta gratuita se ainda não tiver a sua. Você precisa da permissão de Colaborador ou Proprietário na assinatura do Azure para continuar. Para obter mais informações, confira Atribuir funções do Azure usando o portal do Azure.
• O CLI do Azure.
• A extensão, versão 0.3.47 ou superior da CLI dos Aplicativos de Contêiner do Azure. Para instalar a versão mais recente, use o comando az extension add --name containerapp --upgrade --allow-preview.
• O Java Development Kit, versão 17 ou superior.
• Maven.

Preparar o projeto Spring

Use as etapas a seguir para preparar o projeto:

1. Use o comando Maven a seguir para criar o projeto:

   mvn clean verify
   

2. Execute o projeto de exemplo localmente usando o seguinte comando:

   mvn spring-boot:run
   

Instalação

Para entrar no Azure usando a CLIl, execute o comando a seguir e siga os prompts para concluir o processo de autenticação.

az login

Para garantir que você esteja executando a versão mais recente da CLI, execute o comando “upgrade”.

az upgrade

Em seguida, instale ou atualize a extensão dos Aplicativos de Contêiner do Azure para a CLI.

Se você receber erros sobre parâmetros ausentes ao executar comandos az containerapp na CLI do Azure, verifique se você tem a versão mais recente da extensão dos Aplicativos de Contêiner do Azure instalada.

az extension add --name containerapp --upgrade

Observação

A partir de maio de 2024, as extensões da CLI do Azure já não permitem funcionalidades de versão prévia do recurso por padrão. Para acessar as versões prévias dos recursos dos Aplicativos de Contêiner, instale a extensão Aplicativos de Contêiner com --allow-preview true.

az extension add --name containerapp --upgrade --allow-preview true

Agora que a extensão ou módulo atual está instalado, registre os namespaces Microsoft.App e Microsoft.OperationalInsights.

Observação

Os recursos dos Aplicativos de Contêiner do Azure migraram do namespace Microsoft.Web para o namespace Microsoft.App. Consulte a migração de namespace de Microsoft.Web para Microsoft.App em março de 2022 para obter mais detalhes.

az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights

Criar o ambiente de Aplicativos de Contêiner do Azure

Agora que a configuração da CLI do Azure foi concluída, você pode definir as variáveis de ambiente que são usadas ao longo deste artigo.

Defina as variáveis a seguir no shell bash.

export RESOURCE_GROUP="ms-identity-containerapps"
export LOCATION="canadacentral"
export ENVIRONMENT="env-ms-identity-containerapps"
export API_NAME="ms-identity-api"
export JAR_FILE_PATH_AND_NAME="./target/ms-identity-spring-boot-webapp-0.0.1-SNAPSHOT.jar"

Crie um grupos de recursos.

az group create  \
    --name $RESOURCE_GROUP \
    --location $LOCATION \

Criar um ambiente com um espaço de trabalho da Análise de logs gerado automaticamente.

az containerapp env create \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION

Mostrar o domínio padrão do ambiente do aplicativo de contêiner. Anote esse domínio para usar em seções posteriores.

az containerapp env show \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --query properties.defaultDomain

Preparar o aplicativo para implantação

Ao implantar seu aplicativo nos Aplicativos de Contêiner do Azure, a URL de redirecionamento é alterada para a URL de redirecionamento da instância do aplicativo implantado nos Aplicativos de Contêiner do Azure. Use as etapas a seguir para alterar essas configurações no arquivo application.yml:

1. Navegue até o arquivo src\main\resources\application.yml do aplicativo e altere o valor de post-logout-redirect-uri para o nome de domínio do aplicativo implantado, conforme mostrado no exemplo a seguir. Substitua <API_NAME> e <default-domain-of-container-app-environment> pelos valores atuais. Por exemplo, com o domínio padrão para o ambiente do Aplicativo de Contêiner do Azure da etapa anterior e ms-identity-api para o nome do aplicativo, você usaria https://ms-identity-api.<default-domain> para o valor post-logout-redirect-uri.

   post-logout-redirect-uri: https://<API_NAME>.<default-domain-of-container-app-environment>
   

2. Depois de salvar esse arquivo, use o seguinte comando para recompilar o aplicativo:

   mvn clean package
   

Importante

O arquivo application.yml do aplicativo atualmente contém o valor do segredo do cliente no parâmetro client-secret. Não é recomendável manter esse valor nesse arquivo. Você também pode estar correndo risco se confirmar o arquivo em um repositório Git. Para obter a abordagem recomendada, consulte Gerenciar segredos nos Aplicativos de Contêiner do Azure.

Atualizar seu registro de aplicativo do Microsoft Entra ID

Como o URI de redirecionamento é alterado para o aplicativo implantado nos Aplicativos de Contêiner do Azure, você também precisa alterar o URI de redirecionamento no registro do aplicativo Microsoft Entra ID. Use as seguintes etapas para fazer essa alteração:

1. Navegue até a página de registros de aplicativo da plataforma de identidade da Microsoft para desenvolvedores.

2. Use a caixa de pesquisa para procurar o registro do aplicativo. Por exemplo, java-servlet-webapp-authentication.

3. Abra o registro do aplicativo selecionando seu nome.

4. Selecione Autenticação no menu.

5. Na seção Web - URIs de redirecionamento, selecione Adicionar URI.

6. Preencha o URI do aplicativo, anexando /login/oauth2/code/, por exemplo, https://<containerapp-name>.<default domain of container app environment>/login/oauth2/code/.

7. Selecione Salvar.

Implantar o aplicativo

Implante o pacote JAR nos Aplicativos de Contêiner do Azure.

Observação

Se necessário, você pode especificar a versão do JDK nas variáveis de ambiente de build do Java. Para obter mais informações, confira Compilar variáveis de ambiente para Java em Aplicativos de Contêiner do Azure.

Agora você pode implantar o arquivo WAR com o comando da CLI az containerapp up.

az containerapp up \
    --name $API_NAME \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION \
    --environment $ENVIRONMENT \
    --artifact <JAR_FILE_PATH_AND_NAME> \
    --ingress external \
    --target-port 8080 \
    --query properties.configuration.ingress.fqdn

Observação

A versão padrão do JDK é 17. Se você precisar alterar a versão do JDK para compatibilidade com o seu aplicativo, poderá usar o argumento --build-env-vars BP_JVM_VERSION=<YOUR_JDK_VERSION> para ajustar o número de versão.

Para obter mais variáveis de ambiente de compilação, consulte Compilar variáveis de ambiente para Java em Aplicativos de Contêiner do Azure.

Validar o aplicativo

Neste exemplo, o comando containerapp up inclui o argumento --query properties.configuration.ingress.fqdn, que retorna o FQDN (nome de domínio totalmente qualificado), também conhecido como URL do aplicativo. Use as seguintes etapas para verificar o log do aplicativo a fim de investigar qualquer problema de implantação:

1. Acesse a URL do aplicativo de saída na página Saídas da seção Implantação.

2. No painel de navegação da página Visão geral da instância de Aplicativos de Contêiner do Azure, selecione Logs para verificar os logs do aplicativo.

Executar localmente

Siga as etapas a seguir para executar o exemplo localmente:

1. Abrir uma janela do Bash ou o terminal integrado do Visual Studio Code.

2. No diretório da raiz do projeto do aplicativo, use o seguinte comando:

   mvn clean compile spring-boot:run
   

3. Abra o navegador e navegue até http://localhost:8080. Você deve ver uma tela com o texto You're signed in! e os botões com os seguintes rótulos: ID Token Details, Admins Only e Regular Users.

Explorar o exemplo

Use as seguintes etapas para explorar o exemplo:

1. Observe o status de conectado ou desconectado exibido no centro da tela.
2. Selecione o botão contextual no canto. Esse botão lê Entrar quando você executa o aplicativo pela primeira vez. Como alternativa, selecione detalhes do token , somente administradores ou usuários regulares. Como essas páginas são protegidas e exigem autenticação, você é redirecionado automaticamente para a página de entrada.
3. Na próxima página, siga as instruções e conecte-se com uma conta no locatário do Microsoft Entra ID.
4. Na tela de consentimento, observe os escopos que estão sendo solicitados.
5. Após a conclusão bem-sucedida do fluxo de entrada, você deverá ser redirecionado para a página inicial, que mostra o status de entrada ou uma das outras páginas, dependendo do botão que acionou o fluxo de entrada.
6. Observe que o botão contextual agora diz Sair e exibe seu nome de usuário.
7. Se você estiver na página inicial, selecione Detalhes do token de ID para ver algumas das declarações decodificadas do token de ID, incluindo grupos.
8. Selecione Somente administradores para visualizar o /admin_only. Somente usuários pertencentes ao grupo de segurança AdminGroup podem visualizar esta página. Caso contrário, uma mensagem de falha de autorização será exibida.
9. Selecione Usuários regulares para visualizar a página /regular_user. Somente usuários pertencentes ao grupo de segurança UserGroup podem visualizar esta página. Caso contrário, uma mensagem de falha de autorização será exibida.
10. Use o botão no canto para sair. A página de status reflete o novo estado.

Observações sobre o código

Este exemplo apresenta como usar a biblioteca de clientes do Microsoft Entra ID Spring Boot Starter para Java para conectar usuários ao seu locatário do Microsoft Entra ID. O exemplo também usa o Spring Oauth2 Client e os iniciadores da inicialização do Spring Web. O exemplo usa declarações do token de ID obtido do Microsoft Entra ID para exibir os detalhes do usuário conectado e para restringir o acesso a algumas páginas usando a declaração de grupos para autorização.

Contents

A tabela a seguir mostra o conteúdo da pasta do projeto de exemplo:

Arquivo/pasta	Descrição
pom.xml	Dependências de aplicativo.
src/main/resources/templates/	Modelos Thymeleaf para IU.
src/main/resources/application.yml	Configuração da biblioteca do aplicativo e do Microsoft Entra ID Boot Starter.
src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootwebapp/	Esse diretório contém o ponto de entrada do aplicativo principal, o controlador e as classes de configuração.
.../MsIdentitySpringBootWebappApplication.java	Classe principal.
.../SampleController.java	Controlador com mapeamentos de ponto de extremidade.
.../SecurityConfig.java	Configuração de segurança: por exemplo, quais rotas exigem autenticação.
.../Utilities.java	Classe Utilitário: por exemplo, declarações de token de ID de filtro.
CHANGELOG.md	Lista de alterações no exemplo.
CONTRIBUTING.md	Diretrizes para contribuir com o exemplo.
LICENÇA	A licença para o exemplo.

Declarações de token de ID

Para extrair detalhes do token, o aplicativo usa o objeto do Spring Security AuthenticationPrincipal e OidcUser em um mapeamento de solicitação, conforme mostra o exemplo a seguir. Consulte o Controlador de Exemplo para obter todos os detalhes de como esse aplicativo usa declarações de token de ID.

import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
//...
@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
    Map<String, Object> claims = principal.getIdToken().getClaims();
}

Processar uma declaração de grupos no token de ID

A declaração de grupos do token inclui os nomes dos grupos aos quais o usuário conectado está atribuído, conforme mostra o exemplo a seguir:

{
  ...
  "groups": [
    "xyz-id-xyz",
    "xyz-id-xyz",]
  ...
}

Uma maneira comum de acessar os nomes de grupo está documentada na seção Declarações de token de ID.

O Microsoft Entra ID Boot Starter v3.5 e superior analisa a declaração de grupos automaticamente e adiciona cada grupo ao arquivo Authorities. Essa configuração permite que os desenvolvedores usem grupos com anotações de condição de mola PrePost usando o hasAuthority método. Por exemplo, você pode localizar as seguintes condições @PreAuthorize demonstradas em SampleController.java:

@GetMapping(path = "/admin_only")
@PreAuthorize("hasAuthority('enter-admin-group-id-here')")
public String adminOnly(Model model) {
    // restrict to users who belong to AdminGroup
}
@GetMapping(path = "/regular_user")
@PreAuthorize("hasAnyAuthority('enter-user-group-id-here','enter-admin-group-id-here')")
public String regularUser(Model model) {
    // restrict to users who belong to any of UserGroup or AdminGroup
}

O código a seguir obtém uma lista completa de autoridades para um determinado usuário:

@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
   Collection<? extends GrantedAuthority> authorities = principal.getAuthorities();
}

Links de entrada e saída

Para entrar, o aplicativo faz uma solicitação ao ponto de extremidade de entrada do Microsoft Entra ID configurado automaticamente pela biblioteca cliente Spring Boot Starter do Microsoft Entra ID para Java, conforme mostra o exemplo a seguir:

<a class="btn btn-success" href="/oauth2/authorization/azure">Sign In</a>

Para desconectar, o aplicativo faz uma solicitação POST para o ponto de extremidade logout, conforme mostra o exemplo a seguir:

<form action="#" th:action="@{/logout}" method="post">
  <input class="btn btn-warning" type="submit" value="Sign Out" />
</form>

Elementos de IU dependentes de autenticação

O aplicativo tem uma lógica simples nas páginas de modelo da IU para determinar o conteúdo a ser exibido com base no fato de o usuário estar autenticado, conforme mostra o exemplo a seguir, usando as marcas Spring Security Thymeleaf:

<div sec:authorize="isAuthenticated()">
  this content only shows to authenticated users
</div>
<div sec:authorize="isAnonymous()">
  this content only shows to not-authenticated users
</div>

Proteger rotas com AADWebSecurityConfigurerAdapter

Por padrão, o aplicativo protege as páginas Detalhes do token de ID, Somente administradores e Usuários regulares para que apenas usuários conectados possam acessá-las. O aplicativo configura essas rotas usando a propriedade app.protect.authenticated do arquivo application.yml. Para configurar os requisitos específicos do seu aplicativo, você pode estender AADWebSecurityConfigurationAdapter em uma de suas classes. Para obter um exemplo, consulte a classe SecurityConfig deste aplicativo, mostrada no código a seguir:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends AADWebSecurityConfigurerAdapter{
  @Value( "${app.protect.authenticated}" )
  private String[] protectedRoutes;

    @Override
    public void configure(HttpSecurity http) throws Exception {
    // use required configuration form AADWebSecurityAdapter.configure:
    super.configure(http);
    // add custom configuration:
    http.authorizeRequests()
      .antMatchers(protectedRoutes).authenticated()     // limit these pages to authenticated users (default: /token_details, /admin_only, /regular_user)
      .antMatchers("/**").permitAll();                  // allow all other routes.
    }
}

A declaração de excesso de grupos

Para garantir que o tamanho do token não exceda os limites de tamanho do cabeçalho HTTP, a plataforma de identidade da Microsoft limita o número de IDs de objeto que inclui na declaração de grupos.

O limite de excedente é de 150 para tokens SAML, 200 para tokens JWT e 6 para aplicativos de página única. Se um usuário for um membro de mais grupos do que o limite de excedente, a plataforma de identidade da Microsoft não emitirá os IDs de grupo na declaração de grupos no token. Em vez disso, ele inclui uma declaração excedente no token que indica ao aplicativo consultar a API do Microsoft Graph para recuperar a associação de grupo do usuário.

O Microsoft Entra ID Boot Starter v3.5 e superior analisa a declaração de grupos automaticamente e adiciona cada grupo ao arquivo Authorities. O iniciador lida automaticamente com o cenário de excedente de grupos.

Observação

Recomendamos veementemente o uso do recurso de filtragem de grupos, se possível, para evitar o excedente de grupos. Para obter mais informações, consulte a seção Configurar o aplicativo para receber os valores de reivindicação de grupos de um conjunto filtrado de grupos aos quais um usuário pode ser atribuído.

Criar o cenário excedente para teste

Você pode usar o arquivo BulkCreateGroups.ps1 fornecido na pasta AppCreationScripts para criar um grande número de grupos e atribuir usuários a eles. Esse arquivo ajuda a testar cenários de excedente durante o desenvolvimento. Altere o usuário objectId fornecido no script BulkCreateGroups.ps1 .

O tratamento do excedente requer uma chamada ao Microsoft Graph para ler as associações de grupo do usuário conectado, portanto, o aplicativo precisa ter as permissões User.Read e GroupMember.Read.All para que a função getMemberGroups seja executada com sucesso.

Importante

Para o cenário excedente, verifique se você concedeu o escopo da Admin Consent API do Microsoft Graph GroupMember.Read.All para os aplicativos cliente e de serviço. Para obter mais informações, consulte as etapas de registro do aplicativo anteriormente neste artigo.

Atualizar o registro do aplicativo Microsoft Entra ID (java-spring-webapp-groups)

Use as etapas a seguir para atualizar o registro do aplicativo:

1. Navegue até o Portal do Azure.

2. No painel de navegação à esquerda, selecione Azure Active Directory e selecione Registros de aplicativo (versão prévia).

3. Na tela resultante, selecione o aplicativo java-spring-webapp-groups.

4. Na página de registro do aplicativo, selecione Autenticação no menu.

5. Na seção URIs de redirecionamento, atualize as URLs de resposta para corresponder à URL do site da implantação do Azure, por exemplo, https://java-spring-webapp-groups.azurewebsites.net/login/oauth2/code/.

Importante

Se o aplicativo estiver usando um armazenamento na memória , os Serviços de Aplicativos do Azure desativarão o site se ele estiver inativo e todos os registros que o aplicativo estava mantendo serão esvaziados. Além disso, se você aumentar a contagem de instâncias do seu site, as solicitações serão distribuídas entre as instâncias. Assim, os registros dos aplicativos não são os mesmos em cada instância.

Mais informações

• Documentação da plataforma de identidade da Microsoft
• Visão geral da Biblioteca de autenticação da Microsoft (MSAL)
• Início rápido: registrar um aplicativo na plataforma de identidade da Microsoft
• Início Rápido: Configurar um aplicativo cliente para acessar APIs Web
• Noções básicas sobre as experiências de consentimento do aplicativo Microsoft Entra ID
• Entenda o consentimento do usuário e do administrador
• Objetos de entidade de serviço e aplicativo no Azure Active Directory
• Nuvens nacionais
• Exemplos de código do MSAL

Para obter mais informações sobre como os protocolos OAuth 2.0 funcionam neste cenário e em outros cenários, consulte Cenários de autenticação para o Microsoft Entra ID.