Aplicativos Java Spring Boot seguros usando o Microsoft Entra ID
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:
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
- JDK versão 17. 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 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 em seu locatário do Microsoft Entra ID. Este exemplo não funciona com uma conta pessoal da Microsoft. Portanto, se você entrou 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.
- 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 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-msal-java-samples.git
cd 4-spring-web-app/1-Authentication/sign-in
Como alternativa, navegue até o repositório ms-identity-msal-java-samples e, em seguida, 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. As seções a seguir mostram como registrar o aplicativo usando o portal do Azure.
Escolha o locatário do Microsoft Entra ID onde você deseja criar seus aplicativos
Para escolher seu locatário, use as seguintes etapas:
Entre no portal do Azure.
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 Alternar diretório para alterar sua sessão para o locatário desejado do Microsoft Entra ID.
Registrar o aplicativo (java-spring-webapp-auth)
Para registrar o aplicativo, use as seguintes etapas:
Navegue até o portal do Azure e selecione ID do Microsoft Entra.
Selecione Registros de aplicativo no painel de navegação e selecione Novo registro.
Na página Registrar um aplicativo que aparece, insira as seguintes informações de registro de aplicativo:
- Na seção Nome, insira um nome de aplicativo significativo para exibição aos usuários do aplicativo - por exemplo,
java-spring-webapp-auth
. - Em Tipos de contas com suporte, selecione Contas somente neste diretório organizacional.
- Na seção Redirecionar URI (opcional), selecione Web na caixa de combinação e insira o seguinte URI de redirecionamento:
http://localhost:8080/login/oauth2/code/
.
- Na seção Nome, insira um nome de aplicativo significativo para exibição aos usuários do aplicativo - por exemplo,
Selecione Registrar para criar o aplicativo.
Na página de registro do aplicativo, localize e copie o valor de ID do aplicativo (cliente) para usar mais tarde. Use esse valor no(s) arquivo(s) de configuração do seu aplicativo.
Na página de registro do aplicativo, selecione Certificados e segredos no painel de navegação para abrir a página onde você pode gerar segredos e carregar certificados.
Na seção Segredos do Cliente, escolha Novo Segredo do Cliente.
Digite uma descrição - por exemplo, segredo do aplicativo.
Selecione uma das durações disponíveis: Em 1 ano, Em 2 anos ou Nunca expira.
Selecione Adicionar. O valor gerado é exibido.
Copie e salve o valor gerado para uso em etapas posteriores. Você precisa desse valor para os arquivos de configuração do 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.
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
.
Abra o projeto em seu IDE.
Abra o arquivo src\main\resources\application.yml .
Localize o espaço reservado
Enter_Your_Tenant_ID_Here
e substitua o valor existente por sua ID de locatário do Microsoft Entra.Localize o espaço reservado
Enter_Your_Client_ID_Here
e substitua o valor existente pela ID do aplicativo ouclientId
pelojava-spring-webapp-auth
aplicativo copiado do portal do Azure.Localize o espaço reservado
Enter_Your_Client_Secret_Here
e substitua o valor existente pelo valor que você salvou durante a criação dojava-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
Se você estiver implantando a instância do plano Enterprise do Aplicativos Spring do Azure pela primeira vez na assinatura de destino, confira a seção Requisitos do plano Enterprise no Azure Marketplace.
Plug-in do Maven para aplicativos do Azure Spring. Se o Maven não for sua ferramenta de desenvolvimento preferida, consulte os seguintes tutoriais semelhantes que usam outras ferramentas:
Preparar o projeto Spring
Use as etapas a seguir para preparar o projeto:
Use o comando Maven a seguir para criar o projeto:
mvn clean package
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-msal-java-samples/4-spring-web-app/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 :
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ê escolheucluster-ms-identity-spring-boot-webapp
sua instância do Azure Spring Apps na etapa anterior ems-identity-spring-boot-webapp
o nome do seu aplicativo, agora você deve usarhttps://cluster-ms-identity-spring-boot-webapp-ms-identity-spring-boot-webapp.azuremicroservices.io
para opost-logout-redirect-uri
valor.post-logout-redirect-uri: https://<cluster-name>-<app-name>.azuremicroservices.io
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:
Navegue até a página de registros de aplicativo da plataforma de identidade da Microsoft para desenvolvedores.
Use a caixa de pesquisa para pesquisar o registro do aplicativo - por exemplo,
java-servlet-webapp-authentication
.Abra o registro do aplicativo selecionando seu nome.
Selecione Autenticação no menu.
Na seção Redirecionar URIs da Web - , selecione Adicionar URI.
Preencha o URI do seu aplicativo, anexando
/login/oauth2/code/
- por exemplo,https://<cluster-name>-<app-name>.azuremicroservices.io/login/oauth2/code/
.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:
Acesse a URL do aplicativo de saída na página Saídas da seção Implantação .
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:
- Observe o status de entrada ou saída exibido no centro da tela.
- 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.
- Na próxima página, siga as instruções e entre com uma conta no locatário do Microsoft Entra ID.
- Na tela de consentimento, observe os escopos que estão sendo solicitados.
- 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.
- Observe que o botão sensível ao contexto agora diz Sair e exibe seu nome de usuário.
- Se você estiver na página inicial, selecione Detalhes do token de ID para ver algumas das declarações decodificadas do token de ID.
- 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 |
---|---|
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();
}
Links de entrada e saída
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.authenticated
propriedade 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
- Plataforma de identidade da Microsoft (ID do Microsoft Entra para desenvolvedores)
- 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 experiências de consentimento de aplicativo do Microsoft Entra ID
- Entenda o consentimento do usuário e do administrador
- Objetos de entidade de serviço e aplicativo no Microsoft Entra ID
- Nuvens Nacionais
- Exemplos de código MSAL
- Biblioteca de 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 da plataforma de identidade da Microsoft
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.