Share via

Aplicativos Java Spring Boot seguros usando o Microsoft Entra ID

  • Artigo

Este artigo demonstra um aplicativo Web Java Spring Boot que conecta usuários em seu locatário do Microsoft Entra ID usando 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:

Diagrama que mostra a topologia do aplicativo.

O aplicativo cliente usa a biblioteca de cliente Microsoft Entra ID Spring Boot Starter para Java para entrar em um usuário e obter um token de ID do Microsoft Entra ID. O token de ID prova que o usuário está autenticado com o Microsoft Entra ID e permite que o usuário acesse rotas protegidas.

Pré-requisitos

Recomendações

  • Alguma familiaridade com o Spring Framework
  • Alguma familiaridade com o terminal Linux/OSX ou o Windows PowerShell
  • 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 manter atualizado com os desenvolvimentos mais recentes.

Configurar o exemplo

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

Clonar ou fazer 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-java-spring-tutorial.git
cd ms-identity-java-spring-tutorial
cd 1-Authentication/sign-in

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

Importante

Para evitar limitações de comprimento de caminho no Windows, recomendamos clonar em um diretório próximo à raiz da unidade.

Registrar os aplicativos de exemplo com seu locatário do Microsoft Entra ID

Há um projeto neste exemplo. Para registrar o aplicativo no portal do Azure, você pode seguir as etapas de configuração manual ou usar um script do PowerShell. O script executa as seguintes tarefas:

  • Cria os aplicativos Microsoft Entra ID e objetos relacionados, como senhas, permissões e dependências.
  • Modifica os arquivos de configuração do projeto.
  • Por padrão, configura um aplicativo que funciona apenas com contas no diretório organizacional.

Use as seguintes etapas para executar o script do PowerShell:

  1. No Windows, abra o PowerShell e navegue até a raiz do diretório clonado.

  2. Use o seguinte comando para definir a política de execução do PowerShell:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

  3. Use os seguintes comandos para executar o script de configuração:

    cd .\AppCreationScripts\
.\Configure.ps1

    Observação

    Outras maneiras de executar os scripts são descritas em Scripts de criação de aplicativos. Os scripts também fornecem um guia para registro, configuração e remoção automatizados de aplicativos, o que pode ajudar em seus cenários de CI/CD.

Configurar o aplicativo (java-spring-webapp-auth) para usar o registro do aplicativo

Use as seguintes etapas para configurar o aplicativo:

Observação

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

  1. Abra o projeto em 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 por sua ID de locatário do Microsoft Entra.

  4. Localize o espaço reservado Enter_Your_Client_ID_Here e substitua o valor existente pela ID do aplicativo ou clientId pelo java-spring-webapp-auth aplicativo 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-auth copiado do portal do Azure.

Execute o exemplo

As seções a seguir mostram como implantar o exemplo nos Aplicativos Spring do Azure.

Pré-requisitos

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 package

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

    mvn spring-boot:run

Configurar o plug-in do Maven

Execute o seguinte comando na raiz do projeto para configurar o aplicativo usando o plug-in Maven para Aplicativos Spring do Azure:

mvn com.microsoft.azure:azure-spring-apps-maven-plugin:1.19.0:config

A lista a seguir descreve as interações de comando:

  • Logon OAuth2: você precisa autorizar a entrada no Azure com base no protocolo OAuth2.
  • Selecione assinatura: selecione o número da lista de assinaturas onde você deseja criar sua instância do Azure Spring Apps, que tem como padrão a primeira assinatura da lista. Se você quiser usar o número padrão, pressione Enter.
  • Insira o nome dos Aplicativos Spring do Azure: insira o nome da instância de aplicativos Spring que você deseja criar. Se você quiser usar o nome padrão, pressione Enter.
  • Insira o nome do grupo de recursos: insira o nome do grupo de recursos no qual você deseja criar sua instância de aplicativos de primavera. Se você quiser usar o nome padrão, pressione Enter.
  • Skus: Selecione a SKU que você deseja usar para sua instância de aplicativos spring. Se você quiser usar o número padrão, pressione Enter.
  • Inserir o nome do aplicativo (demonstração): forneça um nome de aplicativo. Se você quiser usar a ID de artefato de projeto padrão, pressione Enter.
  • Tempos de execução: selecione o tempo de execução que você deseja usar para sua instância de aplicativos de primavera. Nesse caso, você deve usar o número padrão, então pressione Enter.
  • Expo o acesso público para esse aplicativo (boot-for-azure): pressione Y.
  • Confirme para salvar todas as configurações acima: pressione S. Se você pressionar n, a configuração não será salva no arquivo .pom .

O exemplo a seguir mostra a saída do processo de implantação:

Summary of properties:
Subscription id   : 12345678-1234-1234-1234-123456789101
Resource group name : rg-ms-identity-spring-boot-webapp
Azure Spring Apps name : cluster-ms-identity-spring-boot-webapp
Runtime Java version : Java 11
Region            : eastus
Sku               : Standard
App name          : ms-identity-spring-boot-webapp
Public access     : true
Instance count/max replicas : 1
CPU count         : 1
Memory size(GB)   : 2
Confirm to save all the above configurations (Y/n):
[INFO] Configurations are saved to: /home/user/ms-identity-java-spring-tutorial/1-Authentication/sign-in/pom.    xml
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:57 min
[INFO] Finished at: 2024-02-14T13:50:44Z
[INFO] ------------------------------------------------------------------------

Depois de confirmar suas escolhas, o plug-in adiciona o elemento de plug-in e as configurações necessárias ao arquivo de pom.xml do projeto para configurar seu aplicativo para ser executado nos Aplicativos Spring do Azure.

A parte relevante do arquivo pom.xml deve ser semelhante ao exemplo a seguir:

<plugin>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>azure-spring-apps-maven-plugin</artifactId>
    <version>1.19.0</version>
    <configuration>
        <subscriptionId>12345678-1234-1234-1234-123456789101</subscriptionId>
        <resourceGroup>rg-ms-identity-spring-boot-webapp</resourceGroup>
        <clusterName>cluster-ms-identity-spring-boot-webapp</clusterName>
        <region>eastus</region>
        <sku>Standard</sku>
        <appName>ms-identity-spring-boot-webapp</appName>
        <isPublic>true</isPublic>
        <deployment>
            <cpu>1</cpu>
            <memoryInGB>2</memoryInGB>
            <instanceCount>1</instanceCount>
            <runtimeVersion>Java 11</runtimeVersion>
            <resources>
                <resource>
                    <directory>${project.basedir}/target</directory>
                    <includes>
                        <include>*.jar</include>
                    </includes>
                </resource>
            </resources>
        </deployment>
    </configuration>
</plugin>

Você pode modificar as configurações dos Aplicativos Spring do Azure diretamente em seu arquivo pom.xml . Algumas configurações comuns são listadas na tabela a seguir:

Propriedade Obrigatório Descrição
subscriptionId false A ID da assinatura.
resourceGroup true O grupo de recursos do Azure para sua instância do Azure Spring Apps.
clusterName true O nome do cluster do Azure Spring Apps. Caso você esteja usando uma assinatura e um grupo de recursos que já tenham uma instância do Azure Spring Apps implantada, você também pode usar esse cluster existente para implantar.
appName true O nome do seu aplicativo no Azure Spring Apps.
region false A região na qual hospedar sua instância do Azure Spring Apps. O valor padrão é eastus. Para regiões válidas, consulte Regiões com suporte.
sku false A camada de preços para sua instância do Azure Spring Apps. O valor padrão é Basic, que é adequado apenas para ambientes de desenvolvimento e teste.
runtime false A configuração do ambiente de tempo de execução. Para mais informações, confira Informações de configuração.
deployment false Configuração de implantação. Para mais informações, confira Informações de configuração.

Para obter a lista completa de configurações, veja a documentação de referência do plug-in. Todos os plug-ins do Azure Maven compartilham um conjunto comum de configurações. Para essas configurações, consulte Configurações comuns. Para configurações específicas dos Aplicativos Spring do Azure, consulte Aplicativos Spring do Azure: Detalhes de Configuração.

Certifique-se de guardar os clusterName valores e appName para uso posterior.

Preparar o aplicativo para implantação

Quando você implanta seu aplicativo nos Aplicativos Spring do Azure, sua URL de redirecionamento muda para a URL de redirecionamento da instância do aplicativo implantado nos Aplicativos Spring do Azure. Use as seguintes etapas 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 do nome de domínio do post-logout-redirect-uri aplicativo implantado, conforme mostrado no exemplo a seguir. Por exemplo, se você escolheu cluster-ms-identity-spring-boot-webapp sua instância do Azure Spring Apps na etapa anterior e ms-identity-spring-boot-webapp o nome do seu aplicativo, agora você deve usar https://cluster-ms-identity-spring-boot-webapp-ms-identity-spring-boot-webapp.azuremicroservices.io para o post-logout-redirect-uri valor.

    post-logout-redirect-uri: https://<cluster-name>-<app-name>.azuremicroservices.io

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

    mvn clean package

Importante

O arquivo application.yml do aplicativo atualmente contém o valor do segredo do cliente no client-secret parâmetro. Não é uma boa prática manter esse valor neste arquivo. Você também pode estar correndo um risco se confirmá-lo em um repositório Git.

Como uma etapa de segurança extra, você pode armazenar esse valor no Cofre de Chaves do Azure e carregar o segredo do Cofre de Chaves para disponibilizá-lo em seu aplicativo.

Atualizar o registro do aplicativo Microsoft Entra ID

Como o URI de redirecionamento é alterado para seu aplicativo implantado no Azure Spring Apps, 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 pesquisar 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 de comando.

  5. Na seção Redirecionar URIs da Web - , selecione Adicionar URI.

  6. Preencha o URI do seu aplicativo, anexando /login/oauth2/code/ - por exemplo, https://<cluster-name>-<app-name>.azuremicroservices.io/login/oauth2/code/.

  7. Selecione Salvar.

Implantar o aplicativo

Use o seguinte comando para implantar o aplicativo:

mvn azure-spring-apps:deploy

A lista a seguir descreve a interação de comando:

  • Logon OAuth2: você precisa autorizar a entrada no Azure com base no protocolo OAuth2.

Depois que o comando for executado, você poderá pelas mensagens de log que a implantação foi bem-sucedida:

[INFO] Deployment(default) is successfully created
[INFO] Starting Spring App after deploying artifacts...
[INFO] Deployment Status: Running
[INFO]   InstanceName:demo-default-x-xxxxxxxxxx-xxxxx  Status:Running Reason:null       DiscoverStatus:UNREGISTERED
[INFO]   InstanceName:demo-default-x-xxxxxxxxx-xxxxx  Status:Terminating Reason:null       DiscoverStatus:UNREGISTERED
[INFO] Getting public url of app(demo)...
[INFO] Application url: https://<your-Azure-Spring-Apps-instance-name>-demo.azuremicroservices.io

Validar o aplicativo

Após a conclusão da implantação, acesse o aplicativo com a URL do aplicativo de saída. 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 Spring do Azure, selecione Logs para verificar os logs do aplicativo.

Explorar 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. Esse botão lê Entrar quando você executa o aplicativo pela primeira vez. Como alternativa, selecione os detalhes do token. Como essa página é protegida e requer autenticação, você será redirecionado automaticamente para a página de entrada.
  3. Na próxima página, 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 bem-sucedida do fluxo de entrada, você deve ser redirecionado para a página inicial - que mostra o status de entrada - ou para a página de detalhes do token, dependendo de qual botão acionou seu fluxo de entrada.
  6. Observe que o botão sensível ao contexto 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.
  8. 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 demonstra como usar a biblioteca de cliente Microsoft Entra ID Spring Boot Starter para Java para entrar usuários em seu locatário do Microsoft Entra ID. O exemplo também usa os iniciadores de inicialização Spring Oauth2 Client e Spring Web. O exemplo usa declarações do token de ID obtido do Microsoft Entra ID para exibir os detalhes do usuário conectado.

Contents

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

Arquivo/pasta Descrição
AppCreationScripts/ Scripts para configurar automaticamente os registros do aplicativo Microsoft Entra ID.
pom.xml Dependências do aplicativo.
src/main/recursos/modelos/ Modelos Thymeleaf para interface do usuário.
src/main/recursos/application.yml Configuração da biblioteca inicial de inicialização do aplicativo e do Microsoft Entra ID.
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 Controller com mapeamentos de endpoint.
.../SecurityConfig.java Configuração de segurança - por exemplo, quais rotas exigem autenticação.
.../Utilities.java Classe de utilitário - por exemplo, declarações de token de ID de filtro.
CHANGELOG.md Lista de alterações à amostra.
CONTRIBUTING.md Orientações para contribuição à amostra.
LICENÇA A licença para a amostra.

Declarações de token de ID

Para extrair detalhes do token, o aplicativo usa o objeto e OidcUser o Spring Security AuthenticationPrincipal em um mapeamento de solicitação, conforme mostrado no exemplo a seguir. Consulte o Controlador de Exemplo para obter detalhes completos de como este aplicativo faz uso de 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();
}

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

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

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

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

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

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

<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 a página Detalhes do Token de ID para que apenas usuários conectados possam acessá-la. O aplicativo configura essas rotas usando a app.protect.authenticatedpropriedade do arquivo application.yml . Para configurar os requisitos específicos do seu aplicativo, aplique o AadWebApplicationHttpSecurityConfigurer#aadWebApplication método à HttpSecurity instância. Para obter um exemplo, consulte a classe SecurityConfig deste aplicativo, mostrada no código a seguir:

@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

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