Proteja aplicativos Java Spring Boot usando o Microsoft Entra ID

Este artigo demonstra uma aplicação Web Java Spring Boot que inicia sessão dos utilizadores no seu inquilino do Microsoft Entra ID utilizando a biblioteca de cliente Microsoft Entra ID Spring Boot Starter para Java. Ele usa o protocolo OpenID Connect.

O diagrama a seguir mostra a topologia do aplicativo:

A aplicação cliente utiliza a biblioteca de cliente Microsoft Entra ID Spring Boot Starter para Java para autenticar um utilizador e obter um token de ID a partir do Microsoft Entra ID. O token de ID prova que o usuário está autenticado com o ID do Microsoft Entra e permite que o usuário acesse rotas protegidas.

Pré-requisitos

• versão 17 do JDK. Este exemplo foi desenvolvido em um sistema com Java 17, mas pode ser compatível com outras versões.
• Maven 3
• Java Extension Pack para Visual Studio Code é recomendado para executar este exemplo no Visual Studio Code.
• Um inquilino do Microsoft Entra ID. Para obter mais informações, consulte Como obter um inquilino do Microsoft Entra ID.
• Uma conta de usuário em seu locatário do Microsoft Entra ID. Este exemplo não funciona com uma conta pessoal da Microsoft. Portanto, se iniciou sessão no portal do Azure com uma conta pessoal e não tem uma conta de utilizador no seu diretório, tem de criar uma agora.
• Visual Studio Code
• Ferramentas do Azure para Visual Studio Code

Recomendações

• Alguma familiaridade com o Spring Framework.
• Alguma familiaridade com o terminal Linux/OSX.
• jwt.ms para inspecionar os seus tokens.
• Fiddler para monitorizar a sua atividade de rede e resolver problemas.
• Siga o Blog do Microsoft Entra para ficar up-toa par dos últimos desenvolvimentos.

Configurar o exemplo

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

Clone ou faça download do repositório de exemplo

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

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 4-spring-web-app/1-Authentication/sign-in

Em alternativa, aceda ao repositório ms-identity-msal-java-samples e, em seguida, transfira-o como um ficheiro .zip e extraia-o para o seu disco rígido.

Registre os aplicativos 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 inquilino do Microsoft Entra ID no qual pretende criar as suas aplicações

Para escolher o seu inquilino, siga os passos seguintes:

1. Inicie sessão no portal do Azure.

2. Se a sua conta estiver presente em mais do que um tenant do Microsoft Entra ID, selecione o seu perfil no canto do portal do Azure e, em seguida, selecione Alternar diretório para mudar a sua sessão para o tenant do Microsoft Entra ID pretendido.

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

Para registrar o aplicativo, use as seguintes etapas:

1. Aceda ao Azure portal e selecione Microsoft Entra ID.

2. Selecione Registos de aplicações no painel de navegação, depois selecione Nova matrícula.

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

   • Na secção Name, introduza um nome significativo para a aplicação, para apresentar aos utilizadores da aplicação - por exemplo, java-spring-webapp-auth.
   • Em Tipos de conta suportados, selecione Apenas um locatário - TENANT_NAME (TENANT_NAME varia consoante o locatário).
   • Na secção URI de redirecionamento (opcional), selecione Web na caixa de combinação e introduza o seguinte URI de redirecionamento: http://localhost:8080/login/oauth2/code/.

4. Selecione Registar para criar a aplicação.

5. Na página de registo da aplicação, localize e copie o valor de ID da aplicação (cliente) para utilizar mais tarde. Você usa esse valor no(s) arquivo(s) de configuração do seu aplicativo.

6. Na página de registo da aplicação, selecione Certificados & segredos no painel de navegação para abrir a página onde pode gerar segredos e carregar certificados.

7. Na secção Segredos do cliente, selecione Novo segredo do cliente.

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

9. Selecione uma das durações disponíveis: Recomendado: 180 dias (6 meses),90 dias (3 meses),365 dias (12 meses),545 dias (18 meses) ou 730 dias (24 meses).

10. Selecione Adicionar. O valor gerado é exibido.

11. Copie e salve o valor gerado para uso em etapas posteriores. Você precisa desse valor para os arquivos de configuração do seu código. Esse valor não é exibido novamente e você não pode recuperá-lo por nenhum outro meio. Portanto, certifique-se de salvá-lo do portal do Azure antes de navegar para qualquer outra tela ou painel.

Configure a aplicação (java-spring-webapp-auth) para utilizar o registo da sua aplicação

Use as seguintes etapas para configurar o aplicativo:

1. Abra o projeto no seu IDE.

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

3. Localize o marcador de posição Enter_Your_Tenant_ID_Here e substitua o valor existente pelo ID do inquilino do Microsoft Entra.

4. Encontre o marcador Enter_Your_Client_ID_Here e substitua o valor existente pelo ID da aplicação java-spring-webapp-auth ou clientId que copiou do portal Azure.

5. Localize o marcador de posição Enter_Your_Client_Secret_Here e substitua o valor existente pelo valor que guardou durante a criação de java-spring-webapp-auth, copiado do portal do Azure.

Executar 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

Explore o exemplo

Use as seguintes etapas para explorar o exemplo:

1. Observe o status de entrada ou saída exibido no centro da tela.
2. Selecione o botão sensível ao contexto no canto. Este botão apresenta Iniciar sessão quando executa a aplicação pela primeira vez. Em alternativa, selecione detalhes do token. Como esta página é protegida e requer autenticação, você é automaticamente redirecionado para a página de entrada.
3. Na página seguinte, siga as instruções e entre 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 com êxito do processo de início de sessão, deverá ser redirecionado para a página inicial — que mostra o estado do início de sessão — ou para a página de detalhes do token, consoante o botão que tiver desencadeado o processo de início de sessão.
6. Observe que o botão sensível ao contexto agora diz Sair e exibe seu nome de usuário.
7. Se estiver na página inicial, selecione ID Token Details para ver alguns dos atributos descodificados do token de ID.
8. Use o botão no canto para sair. A página de status reflete o novo estado.

Sobre o código

Este exemplo demonstra como utilizar a biblioteca de cliente Microsoft Entra ID Spring Boot Starter para Java para permitir que os utilizadores iniciem sessão no seu tenant do Microsoft Entra ID. O exemplo também faz uso dos iniciadores de inicialização do Spring Oauth2 Client e do Spring Web. O exemplo usa declarações do token de ID obtido do ID do Microsoft Entra para exibir os detalhes do usuário conectado.

Conteúdos

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

Alegações do token de identificação

Para extrair detalhes do token, a aplicação utiliza os objetos AuthenticationPrincipal e OidcUser do Spring Security num mapeamento de pedidos, conforme mostrado no exemplo seguinte. Consulte o Controlador de exemplo para ver todos os detalhes de como esta aplicação utiliza as declarações do 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();
}

Links de entrada e saída

Para iniciar sessão, a aplicação envia automaticamente um pedido para o ponto final de início de sessão do Microsoft Entra ID, configurado pela biblioteca cliente Microsoft Entra ID Spring Boot Starter para Java, conforme mostrado no exemplo seguinte:

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

Para terminar sessão, a aplicação faz um pedido POST para o logout endpoint, como mostrado no exemplo seguinte:

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

Elementos da interface do usuário dependentes de autenticação

O aplicativo tem alguma lógica simples nas páginas de modelo da interface do usuário para determinar o conteúdo a ser exibido com base na autenticação do usuário, conforme mostrado no exemplo a seguir usando as tags 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>

Proteja rotas com AADWebSecurityConfigurerAdapter

Por predefinição, a aplicação protege a página ID Token Details para que apenas os utilizadores com sessão iniciada possam aceder-lhe. A aplicação configura estas rotas através da propriedade app.protect.authenticated do ficheiro application.yml. Para configurar os requisitos específicos da sua aplicação, aplique o método AadWebApplicationHttpSecurityConfigurer#aadWebApplication à instância HttpSecurity. Por exemplo, consulte a classe SecurityConfig desta aplicação, mostrada no código seguinte:

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig  {
    
    @Value("${app.protect.authenticated}")
    private String[] allowedOrigins;
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // @formatter:off
        http.apply(AadWebApplicationHttpSecurityConfigurer.aadWebApplication())
            .and()
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(allowedOrigins).authenticated()
                .anyRequest().permitAll()
                );
        // @formatter:on
        return http.build();
    }

    @Bean
    @RequestScope
    public ServletUriComponentsBuilder urlBuilder() {
        return ServletUriComponentsBuilder.fromCurrentRequest();
    }    
}

Mais informações

• Plataforma de identidade da Microsoft (Microsoft Entra ID para desenvolvedores)
• Visão geral da Biblioteca de Autenticação da Microsoft (MSAL)
• Início rápido: Registar uma aplicação na plataforma de identidade da Microsoft
• Guia de início rápido: Configurar uma aplicação cliente para aceder a APIs Web
• Compreender as experiências de consentimento de aplicações no Microsoft Entra ID
• Compreender o consentimento do utilizador e do administrador
• Objetos de aplicação e de entidade de serviço no Microsoft Entra ID
• Nuvens Nacionais
• Exemplos de código MSAL
• Biblioteca cliente Microsoft Entra ID Spring Boot Starter para Java
• Biblioteca de autenticação da Microsoft para Java (MSAL4J)
• MSAL4J Wiki
• tokens de ID
• Tokens de acesso na plataforma de identidade da Microsoft

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