Habilitar aplicativos Java WebSphere para entrar em usuários e acessar o Microsoft Graph

Este artigo demonstra um aplicativo Java WebSphere que entra em usuários e obtém um token de acesso para chamar o Microsoft Graph. Ele usa a Microsoft Authentication Library (MSAL) para Java.

O diagrama a seguir mostra a topologia do aplicativo:

O aplicativo cliente usa o MSAL for Java (MSAL4J) para entrar em um usuário e obter um token de acesso para o Microsoft Graph 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

• Java 8 ou superior
• Maven 3
• 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 próprio locatário do Microsoft Entra ID se você quiser trabalhar apenas com contas em seu diretório organizacional - ou seja, no modo de locatário único. Se ainda não criou uma conta de utilizador no seu inquilino, deve fazê-lo antes de prosseguir. Para obter mais informações, consulte Como criar, convidar e excluir usuários.
• Uma conta de usuário no locatário do Microsoft Entra ID de qualquer organização se você quiser trabalhar com contas em qualquer diretório organizacional - ou seja, no modo multilocatário. Este exemplo deve ser modificado para funcionar com uma conta pessoal da Microsoft. Se ainda não criou uma conta de utilizador no seu inquilino, deve fazê-lo antes de prosseguir. Para obter mais informações, consulte Como criar, convidar e excluir usuários.
• Uma conta Microsoft pessoal - por exemplo, Xbox, Hotmail, Live e assim por diante - se pretender trabalhar com contas Microsoft pessoais.

• WebSphere
• Visual Studio Code
• Ferramentas do Azure para Visual Studio Code

Recomendações

• Alguma familiaridade com os servlets Java / Jacarta.
• 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 3-java-servlet-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.

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 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-servlet-webapp-call-graph)

Primeiro, registre um novo aplicativo no portal do Azure seguindo as instruções em Guia de início rápido: registrar um aplicativo com a plataforma de identidade da Microsoft.

Em seguida, use as seguintes etapas para concluir o registro:

1. Navegue até a página Registros de aplicativos da plataforma de identidade da Microsoft para desenvolvedores.

2. 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-servlet-webapp-call-graph.

   • Em Tipos de conta suportados, selecione uma das seguintes opções:

     • Selecione Contas neste diretório organizacional somente se estiver criando um aplicativo para uso somente por usuários em seu locatário - ou seja, um aplicativo de locatário único.
     • Selecione Contas em qualquer diretório organizacional se quiser que os usuários em qualquer locatário do Microsoft Entra ID possam usar seu aplicativo - ou seja, um aplicativo multilocatário .
     • Selecione Contas em qualquer diretório organizacional e contas pessoais da Microsoft para o maior conjunto de clientes, ou seja, um aplicativo multilocatário que também ofereça suporte a contas pessoais da Microsoft.

   • Selecione Contas pessoais da Microsoft para uso somente por usuários de contas pessoais da Microsoft - por exemplo, contas do Hotmail, Live, Skype e Xbox.

   • Na seção URI de redirecionamento, selecione Web na caixa de combinação e digite o seguinte URI de redirecionamento: http://localhost:8080/msal4j-servlet-graph/auth/redirect.

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. Selecione Guardar para guardar as alterações.

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

8. Na seção Segredos do cliente, selecione Novo segredo do cliente.

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

10. Selecione uma das durações disponíveis: Em 1 ano, Em 2 anos ou Nunca expira.

11. Selecione Adicionar. O valor gerado é exibido.

12. 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.

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

14. Selecione Adicionar permissões.

15. Verifique se a guia APIs da Microsoft está selecionada.

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

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

18. Selecione Adicionar permissões.

Configure o aplicativo (java-servlet-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/authentication.properties .

3. Localize a cadeia de caracteres {enter-your-tenant-id-here}. Substitua o valor existente por um dos seguintes valores:

   • Sua ID de locatário do Microsoft Entra ID se você registrou seu aplicativo com a opção Somente Contas neste diretório organizacional.
   • A palavra organizations se você registrou seu aplicativo com a opção Contas em qualquer diretório organizacional.
   • A palavra common se você registrou seu aplicativo com a opção Contas em qualquer diretório organizacional e contas pessoais da Microsoft.
   • A palavra consumers se você registrou seu aplicativo com a opção Contas pessoais da Microsoft .

4. Localize a cadeia de caracteres {enter-your-client-id-here} e substitua o valor existente pela ID do aplicativo ou clientId do java-servlet-webapp-call-graph aplicativo copiado do portal do Azure.

5. Localize a cadeia de caracteres {enter-your-client-secret-here} e substitua o valor existente pelo valor que você salvou durante a java-servlet-webapp-call-graph criação do aplicativo, no portal do Azure.

Criar o exemplo

Para criar o exemplo usando o Maven, navegue até o diretório que contém o arquivo pom.xml para o exemplo e execute o seguinte comando:

mvn clean package

Este comando gera um arquivo .war que você pode executar em vários servidores de aplicativos.

Executar o exemplo

Estas instruções pressupõem que você instalou o WebSphere e configurou um servidor. É possível usar a orientação em Implementar o WebSphere Application Server (tradicional) Cluster em Máquinas Virtuais do Azure para uma configuração básica do servidor.

Antes de implantar no WebSphere, use as seguintes etapas para fazer algumas alterações de configuração no próprio exemplo e, em seguida, compilar ou reconstruir o pacote:

1. Navegue até o arquivo authentication.properties do seu aplicativo e altere o valor de para a URL do servidor e o número da app.homePage porta que você está planejando usar, conforme mostrado no exemplo a seguir:

   # app.homePage is by default set to dev server address and app context path on the server
   # for apps deployed to azure, use https://your-sub-domain.azurewebsites.net
   app.homePage=https://<server-url>:<port-number>/msal4j-servlet-auth/
   

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

   mvn clean package
   

3. Depois que o código terminar de construir, copie o arquivo .war para o sistema de arquivos do servidor de destino.

Você também precisa fazer a mesma alteração no registro do aplicativo do Azure, onde você o define no portal do Azure como o valor de URI de redirecionamento na guia Autenticação.

1. Navegue até a página Registros de aplicativos da plataforma de identidade da Microsoft para desenvolvedores.

2. Use a caixa de pesquisa para pesquisar o registro do seu aplicativo - por exemplo, java-servlet-webapp-authentication.

3. Abra o registro do aplicativo selecionando seu nome.

4. Selecione Autenticação a partir do menu.

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

6. Preencha o URI do seu aplicativo, anexando /auth/redirect - por exemplo, https://<server-url>:<port-number>/auth/redirect.

7. Selecione Guardar.

Use as seguintes etapas para implantar o exemplo usando o Console de Soluções Integradas do WebSphere:

1. Na guia Aplicativos, selecione Novo Aplicativo e, em seguida, Novo Aplicativo Empresarial.

2. Escolha o arquivo .war que você criou e, em seguida, selecione Avançar até chegar à etapa Mapear raízes de contexto para instalação de módulos da Web. As outras configurações padrão devem ser boas.

3. Para a raiz de contexto, defina-a com o mesmo valor que após o número da porta no 'URI de redirecionamento' definido na configuração de exemplo/registro do aplicativo do Azure. Ou seja, se o URI de redirecionamento for http://<server-url>:9080/msal4j-servlet-auth/, então a raiz de contexto deve ser msal4j-servlet-auth.

4. Selecione Concluir.

5. Depois que o aplicativo concluir a instalação, vá para a seção WebSphere enterprise applications da guia Aplicativos .

6. Selecione o arquivo .war que você instalou na lista de aplicativos e, em seguida, selecione Iniciar para implantar.

7. Depois que a implantação terminar, navegue até http://<server-url>:9080/{whatever you set as the context root} e você poderá ver o 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. Este botão lê Iniciar sessão quando executa a aplicação pela primeira vez.
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. Observe que o botão sensível ao contexto agora diz Sair e exibe seu nome de usuário.
6. Selecione Detalhes do token de ID para ver algumas das declarações decodificadas do token de ID.
7. 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.
8. Use o botão no canto para sair.

Sobre o código

Este exemplo usa o MSAL for Java (MSAL4J) para entrar um usuário e obter um token para a API do Microsoft Graph. Ele usa o SDK do Microsoft Graph para Java para obter dados do Graph. Você deve adicionar essas bibliotecas aos seus projetos usando o Maven.

Se quiser replicar o comportamento deste exemplo, você pode copiar o arquivo pom.xml e o conteúdo das pastas helpers e authservlets na pasta src/main/java/com/microsoft/azuresamples/msal4j . Você também precisa do arquivo authentication.properties . Essas classes e arquivos contêm código genérico que você pode usar em uma ampla variedade de aplicativos. Você também pode copiar o restante do exemplo, mas as outras classes e arquivos são criados especificamente para abordar o objetivo deste exemplo.

Conteúdos

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

ConfidentialClientApplication

Uma ConfidentialClientApplication instância é criada no arquivo AuthHelper.java , conforme mostrado no exemplo a seguir. Este objeto ajuda a criar a URL de autorização do Microsoft Entra ID e também ajuda a trocar o token de autenticação por um token de acesso.

// getConfidentialClientInstance method
IClientSecret secret = ClientCredentialFactory.createFromSecret(SECRET);
confClientInstance = ConfidentialClientApplication
                     .builder(CLIENT_ID, secret)
                     .authority(AUTHORITY)
                     .build();

Os seguintes parâmetros são usados para instanciação:

• A ID do cliente do aplicativo.
• O segredo do cliente, que é um requisito para Aplicativos Clientes Confidenciais.
• A Autoridade de ID do Microsoft Entra, que inclui sua ID de locatário do Microsoft Entra.

Neste exemplo, esses valores são lidos do arquivo authentication.properties usando um leitor de propriedades no arquivo Config.java .

Passo a passo

As etapas a seguir fornecem um passo a passo da funcionalidade do aplicativo:

1. A primeira etapa do processo de entrada é enviar uma solicitação para o ponto de extremidade para seu /authorize locatário do Microsoft Entra ID. A instância MSAL4J ConfidentialClientApplication é usada para construir uma URL de solicitação de autorização. A aplicação redireciona o navegador para este URL, que é onde o utilizador inicia sessão.

   final ConfidentialClientApplication client = getConfidentialClientInstance();
   AuthorizationRequestUrlParameters parameters = AuthorizationRequestUrlParameters.builder(Config.REDIRECT_URI, Collections.singleton(Config.SCOPES))
           .responseMode(ResponseMode.QUERY).prompt(Prompt.SELECT_ACCOUNT).state(state).nonce(nonce).build();
   
   final String authorizeUrl = client.getAuthorizationRequestUrl(parameters).toString();
   contextAdapter.redirectUser(authorizeUrl);
   

   A lista a seguir descreve os recursos desse código:

   • AuthorizationRequestUrlParameters: Parâmetros que devem ser definidos para construir um AuthorizationRequestUrlarquivo .
   • REDIRECT_URI: Onde o Microsoft Entra ID redireciona o navegador - juntamente com o código de autenticação - depois de coletar as credenciais do usuário. Ele deve corresponder ao URI de redirecionamento no registro do aplicativo Microsoft Entra ID no portal do Azure
   • SCOPES: Escopos são permissões solicitadas pelo aplicativo.
     • Normalmente, os três escopos são suficientes para receber uma resposta de token de openid profile offline_access ID.
     • A lista completa de escopos solicitados pelo aplicativo pode ser encontrada no arquivo authentication.properties . Você pode adicionar mais escopos, como User.Read.

2. O usuário recebe um prompt de entrada pela ID do Microsoft Entra. Se a tentativa de entrada for bem-sucedida, o navegador do usuário será redirecionado para o ponto de extremidade de redirecionamento do aplicativo. Uma solicitação válida para este ponto de extremidade contém um código de autorização.

3. Em seguida, a ConfidentialClientApplication instância troca esse código de autorização por um token de ID e token de acesso do Microsoft Entra ID.

   // First, validate the state, then parse any error codes in response, then extract the authCode. Then:
   // build the auth code params:
   final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
           .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES)).build();
   
   // Get a client instance and leverage it to acquire the token:
   final ConfidentialClientApplication client = AuthHelper.getConfidentialClientInstance();
   final IAuthenticationResult result = client.acquireToken(authParams).get();
   

   A lista a seguir descreve os recursos desse código:

   • AuthorizationCodeParameters: Parâmetros que devem ser definidos para trocar o Código de Autorização por um ID e/ou token de acesso.
   • authCode: O código de autorização que foi recebido no ponto de extremidade de redirecionamento.
   • REDIRECT_URI: O URI de redirecionamento usado na etapa anterior deve ser passado novamente.
   • SCOPES: Os escopos usados na etapa anterior devem ser passados novamente.

4. Se acquireToken for bem-sucedida, as declarações de token serão extraídas. Se a verificação nonce passar, os resultados serão colocados em context - uma instância de IdentityContextData - e salvos na sessão. O aplicativo pode então instanciar a IdentityContextData partir da sessão por meio de uma instância de sempre que precisar acessá-la IdentityContextAdapterServlet , conforme mostrado no código a seguir:

   // parse IdToken claims from the IAuthenticationResult:
   // (the next step - validateNonce - requires parsed claims)
   context.setIdTokenClaims(result.idToken());
   
   // if nonce is invalid, stop immediately! this could be a token replay!
   // if validation fails, throws exception and cancels auth:
   validateNonce(context);
   
   // set user to authenticated:
   context.setAuthResult(result, client.tokenCache().serialize());
   

Proteja as rotas

Para obter informações sobre como o aplicativo de exemplo filtra o acesso a rotas, consulte AuthenticationFilter.java. No arquivo authentication.properties, a app.protect.authenticated propriedade contém as rotas separadas por vírgulas que somente usuários autenticados podem acessar, conforme mostrado no exemplo a seguir:

# for example, /token_details requires any user to be signed in and does not require special roles or groups claim(s)
app.protect.authenticated=/token_details, /call_graph

Gráfico de chamadas

Quando o usuário navega para /call_graph, o aplicativo cria uma instância do IGraphServiceClient - a partir do Java Graph SDK - passando o token de acesso do usuário conectado. O cliente Graph coloca o Authorization token de acesso nos cabeçalhos de suas solicitações. Em seguida, o aplicativo solicita que o cliente do Graph chame o /me ponto de extremidade para produzir detalhes para o usuário conectado no momento.

Se você já tiver um token de acesso válido para o Graph Service com o User.Read escopo, precisará apenas do seguinte código para obter acesso ao ponto de /me extremidade:

//CallGraphServlet.java
User user = GraphHelper.getGraphClient(contextAdapter).me().buildRequest().get();

Âmbitos

Os escopos informam ao ID do Microsoft Entra o nível de acesso que o aplicativo está solicitando.

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

Para os escopos solicitados pelo aplicativo, consulte authentication.properties. Por padrão, o aplicativo define o valor dos escopos como User.Read. Este escopo específico da API do Microsoft Graph é para acessar as informações do usuário conectado atual. O ponto de extremidade do gráfico para acessar essas informações é https://graph.microsoft.com/v1.0/me. Quaisquer solicitações válidas feitas a este ponto de extremidade devem conter um access_token que contenha o escopo User.Read no Authorization cabeçalho.

Mais informações

• Biblioteca de Autenticação da Microsoft (MSAL) para Java
• Plataforma de identidade da Microsoft (Microsoft Entra ID para desenvolvedores)
• Início Rápido: Registar uma aplicação na plataforma de identidade da Microsoft
• Noções básicas sobre experiências de consentimento de aplicativo do Microsoft Entra ID
• Compreender o consentimento do utilizador e do administrador
• Exemplos de código MSAL

Próximo passo

Implementar aplicativos Java WebSphere no WebSphere Tradicional em Máquinas Virtuais do Azure