Habilite os aplicativos Java Spring Boot para entrar em usuários e acessar o Microsoft Graph

Este artigo demonstra um aplicativo Web Java Spring Boot que entra em usuários e obtém um token de acesso para chamar o Microsoft Graph. Ele usa a biblioteca de cliente Microsoft Entra ID Spring Boot Starter para Java para autenticação, autorização e aquisição de token. Ele usa o SDK do Microsoft Graph para Java para obter dados do Graph.

O diagrama a seguir mostra a topologia do aplicativo:

O aplicativo usa a biblioteca de cliente Microsoft Entra ID Spring Boot Starter para Java para obter um token de acesso para o Microsoft Graph a partir do Microsoft Entra ID. O token de acesso prova que o usuário está autorizado a acessar o ponto de extremidade da API do Microsoft Graph, conforme definido no escopo.

Pré-requisitos

• JDK versão 15. Este exemplo foi desenvolvido em um sistema com Java 15, 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 tem uma conta de usuário em seu diretório, precisa criar uma agora.
• Visual Studio Code
• Ferramentas do Azure para Visual Studio Code

Recomendações

• Alguma familiaridade com o Quadro da primavera.
• Alguma familiaridade com o terminal Linux/OSX.
• jwt.ms para inspecionar seus tokens.
• Fiddler para monitorizar a sua atividade de rede e resolução de problemas.
• Siga o Blog do Microsoft Entra ID para ficar atualizado com os ú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/2-Authorization-I/call-graph

Como alternativa, navegue até o repositório ms-identity-msal-java-samples , faça o download como um arquivo .zip e extraia-o para o 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 locatário do Microsoft Entra ID onde você deseja criar seus aplicativos

Para escolher seu locatário, use as seguintes etapas:

1. Inicie sessão 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 Alternar diretório para alterar sua sessão para o locatário desejado do Microsoft Entra ID.

Registrar o aplicativo (java-spring-webapp-call-graph)

Para registrar o aplicativo, use as seguintes etapas:

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

2. Selecione Registos de Aplicações no painel de navegação e, em seguida, selecione Novo registo.

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 significativo para exibição aos usuários do aplicativo - por exemplo, java-spring-webapp-call-graph.
   • Em Tipos de conta suportados, selecione Contas somente neste diretório organizacional.
   • Na seção Redirecionar URI (opcional), selecione Web na caixa de combinação e digite o seguinte URI de redirecionamento: http://localhost:8080/login/oauth2/code/.

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

5. Na página de registro do aplicativo, localize e copie o valor da ID do aplicativo (cliente) para usar 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 seçã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: 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 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.

12. Na página de registro do aplicativo, selecione o painel de permissões da API no painel de navegação para abrir a página de acesso às APIs de que seu aplicativo precisa.

13. Selecione Adicionar permissões e verifique se a guia APIs da Microsoft está selecionada.

14. Na seção APIs da Microsoft comumente usadas, selecione Microsoft Graph.

15. Na seção Permissões delegadas, selecione User.Read na lista. Use a caixa de pesquisa, se necessário.

16. Selecione Adicionar permissões.

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

Use as seguintes etapas para configurar o aplicativo:

1. Abra 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 pelo 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 do java-spring-webapp-call-graph 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-call-graph 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

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. Este botão lê Iniciar sessão quando executa a aplicação pela primeira vez. Como alternativa, selecione detalhes do token ou gráfico de chamadas. 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 bem-sucedida do fluxo de entrada, você deve ser redirecionado para a página inicial - que mostra o status de entrada - ou uma das outras páginas, dependendo de qual botão acionou seu fluxo de login.
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. Selecione Call Graph para fazer uma chamada para o ponto de extremidade /me do Microsoft Graph e veja uma seleção dos detalhes do usuário obtidos.
9. 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 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 e obter um token de acesso para chamar o Microsoft Graph. O exemplo também faz uso dos iniciadores de inicialização do Spring Oauth2 Client e do Spring Web.

Conteúdos

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

Declarações de token de ID

Para extrair detalhes do token, o aplicativo usa o AuthenticationPrincipal objeto e OidcUser o objeto do Spring Security em um mapeamento de solicitação, conforme mostrado no exemplo a seguir. Consulte o Controlador de exemplo para obter os detalhes completos de como este aplicativo usa as 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 ao 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 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 padrão, o aplicativo protege as páginas Detalhes do token de ID e Gráfico de chamadas para que apenas usuários conectados possam acessá-las. O aplicativo configura essas rotas a partir da app.protect.authenticated propriedade 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, /call_graph)
      .antMatchers("/**").permitAll();                  // allow all other routes.
    }
}

Gráfico de chamadas

Quando o usuário navega para /call_grapho , o aplicativo cria uma instância do GraphServiceClient usando um Oauth2AuthorizedClient ou graphAuthorizedClient que o iniciador de inicialização do Microsoft Entra ID preparou. O aplicativo pede para chamar GraphServiceClient o /me ponto de extremidade e exibe detalhes para o usuário conectado atual. GraphServiceClient é do SDK do Microsoft Graph para Java, v3.

O Oauth2AuthorizedClient deve ser preparado com os escopos corretos. Consulte o arquivo application.yml e a seção Escopos a seguir. O Oauth2AuthorizedClient é usado para exibir o token de acesso e colocá-lo no Authorization cabeçalho das GraphServiceClient solicitações, conforme mostrado no exemplo a seguir:

//see SampleController.java
@GetMapping(path = "/call_graph")
public String callGraph(@RegisteredOAuth2AuthorizedClient("graph") OAuth2AuthorizedClient graphAuthorizedClient) {
  // See the Utilities.graphUserProperties() method for the full example of the following operation:
  GraphServiceClient graphServiceClient = Utilities.getGraphServiceClient(graphAuthorizedClient);
  User user = graphServiceClient.me().buildRequest().get();
  return user.displayName;
}

O exemplo a seguir do arquivo application.yml mostra os escopos solicitados:

# see application.yml file
authorization-clients:
  graph:
    # Specifies the Microsoft Graph scopes that your app needs access to:
    scopes: https://graph.microsoft.com/User.Read

Âmbitos

Os escopos informam ao ID do Microsoft Entra o nível de acesso que o aplicativo está solicitando. Para obter os escopos do Microsoft Graph solicitados por este aplicativo, consulte application.yml.

Por padrão, o aplicativo define o valor dos escopos como https://graph.microsoft.com/User.Read. O User.Read escopo é acessar as informações do usuário conectado atual a partir do ponto de extremidade /me. As solicitações válidas para o ponto de extremidade /me devem conter o User.Read escopo.

Quando um usuário entra, o Microsoft Entra ID apresenta uma caixa de diálogo de consentimento ao usuário com base nos escopos solicitados pelo aplicativo. Se o usuário consentir com um ou mais escopos e obtiver um token, os escopos consentidos serão codificados no token de acesso resultante.

Neste aplicativo, aparece graphAuthorizedClient o token de acesso que prova quais os escopos que o usuário consentiu. O aplicativo usa esse token para criar uma instância que lida com solicitações do GraphServiceClient Graph.

Usando GraphServiceClient.me().buildRequest().get()o , uma solicitação é criada e feita para https://graph.microsoft.com/v1.0/me. O token de acesso é colocado no Authorization cabeçalho da solicitação.

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: Registar uma aplicação na plataforma de identidade da Microsoft
• Guia de início rápido: configurar um aplicativo cliente para acessar APIs da Web
• Noções básicas sobre experiências de consentimento de aplicativo do Microsoft Entra ID
• Compreender o consentimento do utilizador e do administrador
• Objetos de aplicação e de principal de serviço no Microsoft Entra ID
• Nuvens Nacionais
• Exemplos de código MSAL
• Biblioteca de cliente do Azure Ative Directory 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 em outros cenários, consulte Cenários de autenticação para o Microsoft Entra ID.