Proteger aplicativos Java Spring Boot usando funções e declarações de função

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 restringir o acesso a algumas rotas usando funções de aplicativo Microsoft Entra ID (funções de aplicativo) para autorização.

As funções de aplicativo, assim como os grupos de segurança, são meios populares para implementar a autorização. Usando o RBAC (controle de acesso baseado em função) com funções de aplicativo e declarações de função, você pode impor políticas de autorização com segurança com o mínimo de esforço. Outra abordagem é usar grupos Microsoft Entra ID e declarações de grupo. Os grupos Microsoft Entra ID e as funções de aplicativos não são mutuamente exclusivos. Você pode usá-los para fornecer controle de acesso refinado.

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

Para obter mais informações sobre como os protocolos funcionam neste cenário e em outros cenários, consulte Autenticação vs. autorização.

O diagrama a seguir mostra a topologia do aplicativo:

O aplicativo usa a biblioteca de clientes do Microsoft Entra ID Spring Boot Starter para Java para conectar um usuário e obter um token de ID do Microsoft Entra ID. O token de ID contém a declaração de funções. O aplicativo inspeciona o valor dessa declaração para determinar quais páginas o usuário está autorizado a acessar.

Esse tipo de autorização é implementado usando o RBAC. Com o RBAC, o administrador concede permissões a funções, não a usuários ou grupos individuais. O administrador pode então atribuir funções a diferentes usuários e grupos para controlar quem tem acesso a determinado conteúdo e funcionalidade.

Este aplicativo de exemplo define as duas funções de aplicativo a seguir:

• PrivilegedAdmin Autorizado a acessar as páginas Somente Administradores e Usuários regulares.
• RegularUser Autorizado a acessar a página de Usuários regulares.

Essas funções de aplicativo são definidas no portal do Azure, no manifesto de registro do aplicativo. Quando um usuário entra no aplicativo, o Microsoft Entra ID emite uma declaração de funções para cada função concedida individualmente ao usuário na forma de associação de função.

Você pode atribuir usuários e grupos a funções por meio do portal do Azure.

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, consulte Como obter um locatário do Microsoft Entra ID.
• 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.
• Código do Visual Studio
• 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 para ficar up-to-date 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/roles

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.

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-roles)

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-roles.
   • 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: Em 1 ano, Em 2 anos ou Nunca expira.

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.

Definir as funções de aplicativos

Use as etapas a seguir para definir as funções do aplicativo:

1. Ainda no mesmo registo do aplicativo, selecione Funções do aplicativo no painel de navegação.

2. Selecione Criar função do aplicativo e insira os seguintes valores:

   • Para Nome de exibição, insira um nome adequado, por exemplo, PrivilegedAdmin.
   • Para Tipos de membro permitidos, escolha Usuário.
   • Em Valor, insira PrivilegedAdmin.
   • Para Descrição, insira PrivilegedAdmins que podem visualizar a Página do administrador.

3. Selecione Criar função do aplicativo e insira os seguintes valores:

   • Em Nome de exibição, insira um nome adequado, por exemplo, RegularUser.
   • Para Tipos de membro permitidos, escolha Usuário.
   • Em Valor, insira RegularUser.
   • Em Descrição, insira RegularUsers que podem visualizar a Página do usuário.

4. Selecione Aplicar para salvar as alterações.

Atribuir usuários a funções de aplicativos

Siga as diretrizes aqui para adicionar usuários à função de aplicativo definida anteriormente: Atribuir usuários e grupos a funções.

Configure o aplicativo (java-spring-webapp-roles) para usar o registro do aplicativo

Use as seguintes etapas para configurar o aplicativo:

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-roles 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-roles copiado do portal do Azure.

6. Abra o arquivo src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootapplication/Sample.Controller.java.

7. Localize as referências às funções de aplicativos PrivilegedAdmin e RegularUser neste arquivo. Se necessário, altere-os para refletirem os nomes das funções de aplicativo escolhidas nas etapas anteriores.

Execute o exemplo

az login

az upgrade

az extension add --name containerapp --upgrade

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

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

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"

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

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

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

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

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 funções.
8. Selecione Somente administradores para visualizar o /admin_only. Somente usuários com função PrivilegedAdmin de aplicativo 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 com função de aplicativo RegularUser ou PrivilegedAdmin 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 funções para autorização.

Conteúdos

A tabela a seguir mostra o conteúdo da pasta do projeto de 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 funções no token de ID

A declaração de funções do token inclui os nomes das funções às quais o usuário conectado está atribuído, conforme mostrado no exemplo a seguir:

{
  ...
  "roles": [
    "PrivilegedAdmin",
    "RegularUser",]
  ...
}

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

O Microsoft Entra ID Boot Starter v3.3 e superior também analisa a declaração de funções automaticamente e adiciona cada função ao Authoritiesdo usuário conectado, prefixando cada uma com a cadeia de caracteres APPROLE_. Essa configuração permite que os desenvolvedores usem funções de aplicativo com anotações de condição de mola PrePost usando o método hasAuthority. Por exemplo, você pode localizar as seguintes condições @PreAuthorize demonstradas em SampleController.java:

@GetMapping(path = "/admin_only")
@PreAuthorize("hasAuthority('APPROLE_PrivilegedAdmin')")
public String adminOnly(Model model) {
    // restrict to users who have PrivilegedAdmin app role only
}
@GetMapping(path = "/regular_user")
@PreAuthorize("hasAnyAuthority('APPROLE_PrivilegedAdmin','APPROLE_RegularUser')")
public String regularUser(Model model) {
    // restrict to users who have any of RegularUser or PrivilegedAdmin app roles
}

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 da 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.
    }
}

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
• Biblioteca de cliente do Azure Active Directory Spring Boot Starter para Java
• Biblioteca de Autenticação da Microsoft para Java (MSAL4J)
• Wiki do MSAL4J
• Tokens de ID
• Tokens de acesso da plataforma de identidade da Microsoft

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.