Habilitar o login para aplicativos Java JBoss EAP usando o Microsoft Entra ID

Este artigo demonstra uma aplicação Java JBoss EAP que permite que os utilizadores iniciem sessão no seu tenant do Microsoft Entra ID utilizando a Biblioteca de Autenticação da Microsoft (MSAL) para Java.

O diagrama a seguir mostra a topologia do aplicativo:

Diagrama que mostra a topologia da aplicação.

A aplicação cliente utiliza o MSAL para Java (MSAL4J) para iniciar sessão dos utilizadores no respetivo inquilino do Microsoft Entra ID e obter um token de identificação do Microsoft Entra ID. O token de ID prova que um usuário está autenticado com esse locatário. O aplicativo protege suas rotas de acordo com o status de autenticação do usuário.

Pré-requisitos

• JDK versão 8 ou posterior
• Maven 3
• 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 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 tenant do Microsoft Entra ID, deve fazê-lo antes de prosseguir. Para obter mais informações, consulte Como criar, convidar e eliminar utilizadores.
• 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. Tem de modificar este exemplo para trabalhar com uma conta Microsoft pessoal. Se ainda não criou uma conta de utilizador no seu tenant do Microsoft Entra ID, deve fazê-lo antes de prosseguir. Para obter mais informações, consulte Como criar, convidar e eliminar utilizadores.
• Uma conta Microsoft pessoal - por exemplo, Xbox, Hotmail, Live e assim por diante - se pretender trabalhar com contas Microsoft pessoais.

• JBoss EAP
• Visual Studio Code
• Ferramentas do Azure para Visual Studio Code

Recomendações

• Alguma familiaridade com os Servlets Java / Jakarta.
• Alguma familiaridade com o terminal Linux/OSX.
• jwt.ms para inspecionar os seus tokens.
• Fiddler para monitorizar a atividade da sua rede e diagnosticar 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 3-java-servlet-web-app/1-Authentication/sign-in

Em alternativa, navegue até ao repositório ms-identity-msal-java-samples, transfira-o como ficheiro .zip e extraia-o para o seu disco rígido.

Registrar o aplicativo de exemplo com seu locatário do Microsoft Entra ID

Há um projeto neste exemplo. Esta seção mostra como registrar o aplicativo.

Primeiro, registe a aplicação no portal do Azure seguindo as instruções em Início Rápido: Registar uma aplicação com a plataforma de identidade da Microsoft.

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

1. Aceda à página Registos de aplicações da plataforma de identidade da Microsoft para programadores.

2. Selecione Novo registo.

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 descritivo para a aplicação, para ser apresentado aos utilizadores da aplicação - por exemplo, .

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

     • Selecione Contas apenas neste diretório organizacional se estiver a criar uma aplicação para ser utilizada apenas por utilizadores no seu inquilino - isto é, uma aplicação de um único inquilino.
     • Selecione Contas em qualquer diretório organizacional se quiser que os utilizadores em qualquer inquilino do Microsoft Entra ID possam utilizar a sua aplicação - isto é, uma aplicação multitenant.
     • Selecione Contas em qualquer diretório organizacional e contas pessoais da Microsoft para o conjunto mais alargado de clientes, ou seja, uma aplicação multitenant que também suporta 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 secção URI de redirecionamento, selecione Web na caixa de combinação e introduza o seguinte URI de redirecionamento: .

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 registro do aplicativo, selecione Certificados & segredos no painel de navegação para abrir a página para gerar segredos e carregar certificados.

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

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

9. Selecione uma expiração para o segredo ou especifique um tempo de vida personalizado. Os segredos dos clientes têm uma duração máxima de 24 meses, e a Microsoft recomenda uma expiração inferior a 12 meses. Para aplicações de produção, prefira um certificado ou uma credencial federada de identidade em vez de um segredo do cliente.

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.

Configurar a aplicação 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/authentication.properties.

3. Encontre a cadeia de caracteres . Substitua o valor existente por um dos seguintes valores:

   • O seu ID do tenant do Microsoft Entra ID, se registou a sua aplicação com a opção Contas apenas neste diretório organizacional.
   • A palavra se tiver registado a sua aplicação com a opção Contas em qualquer diretório da organização.
   • A palavra se tiver registado a sua aplicação com a opção Contas em qualquer diretório organizacional e contas pessoais Microsoft.
   • A palavra se registou a sua aplicação com a opção Contas pessoais Microsoft.

4. Encontre a cadeia e substitua o valor existente pelo ID da aplicação ou da aplicação , copiados do portal do Azure.

5. Localize a cadeia de caracteres e substitua o valor existente pelo valor que guardou durante a criação da aplicação , 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

Please confirm webapp properties
AppName : msal4j-servlet-auth-1707220080695
ResourceGroup : msal4j-servlet-auth-1707220080695-rg
Region : centralus
PricingTier : P1v3
OS : Linux
Java Version: Java 11
Web server stack: JBosseap 7
Deploy to slot : false
Confirm (Y/N) [Y]:
[INFO] Saving configuration to pom.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  26.196 s
[INFO] Finished at: 2024-02-06T11:48:16Z
[INFO] ------------------------------------------------------------------------

<build>
    <plugins>
        <plugin>
            <groupId>com.microsoft.azure</groupId>
            <artifactId>>azure-webapp-maven-plugin</artifactId>
            <version>x.xx.x</version>
            <configuration>
                <schemaVersion>v2</schemaVersion>
                <resourceGroup>your-resourcegroup-name</resourceGroup>
                <appName>your-app-name</appName>
            ...
            </configuration>
        </plugin>
    </plugins>
</build>

az login

mvn package azure-webapp:deploy

Ver 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.
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 descodificadas do token de ID.
7. Use o botão no canto para sair.
8. Depois de terminar sessão, selecione ID Token Details para verificar que a aplicação apresenta o erro em vez das declarações do token de ID quando o utilizador não está autorizado.

Sobre o código

Este exemplo mostra como utilizar o MSAL for Java (MSAL4J) para iniciar sessão dos utilizadores no seu inquilino do Microsoft Entra ID. Se você quiser usar o MSAL4J em seus próprios aplicativos, você deve adicioná-lo 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 . Também precisa do ficheiro 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

É criada uma instância de no ficheiro AuthHelper.java, conforme mostrado no exemplo seguinte. 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 aplicações cliente confidenciais.
• A autoridade do Microsoft Entra ID, que inclui o seu ID do inquilino do Microsoft Entra ID.

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

Guia passo a passo

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

1. O primeiro passo do processo de início de sessão é enviar um pedido para o ponto final no seu inquilino do Microsoft Entra ID. A instância da MSAL4J é usada para construir um URL de pedido 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:

   • : Parâmetros que têm de ser definidos para construir um AuthorizationRequestUrl.

   • : Local para onde o Microsoft Entra ID redireciona o navegador — juntamente com o código de autenticação — após recolher as credenciais do utilizador. Ele deve corresponder ao URI de redirecionamento no registo da aplicação Microsoft Entra ID no Azure portal.

   • : Scopes são as permissões solicitadas pela aplicação. Normalmente, os três âmbitos são suficientes para receber uma resposta de token de ID.

     Pode encontrar uma lista completa dos âmbitos solicitados pela aplicação no ficheiro authentication.properties. Você pode adicionar mais escopos, como .

2. Ao utilizador é apresentado um pedido de início de sessão pelo Microsoft Entra ID. Se a tentativa de início de sessão for bem-sucedida, o navegador do utilizador é redirecionado para o ponto final de redirecionamento da aplicação. Um pedido válido para este ponto final contém um código de autorização.

3. A instância troca então este código de autorização por um token de ID e um token de acesso junto 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:

   • : Parâmetros que devem ser configurados para trocar o Código de Autorização por um ID e/ou um token de acesso.
   • : O código de autorização recebido na extremidade de redirecionamento.
   • : O URI de redirecionamento utilizado no passo anterior deve ser fornecido novamente.
   • : Os escopos utilizados no passo anterior devem ser passados novamente.

4. Se for bem-sucedida, as declarações associadas ao token são extraídas. Se a verificação do nonce for bem-sucedida, os resultados são colocados em - uma instância de - e guardados na sessão. A aplicação pode então instanciar o a partir da sessão, por meio de uma instância de , sempre que precisar de aceder ao mesmo, conforme mostrado no código seguinte:

   // 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 ficheiro authentication.properties, a propriedade contém as rotas separadas por vírgulas a que só os utilizadores autenticados podem aceder, conforme mostrado no exemplo seguinte:

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

Âmbitos

Escopos indicam ao Microsoft Entra ID o nível de acesso que a aplicação está a pedir.

Com base nos escopos solicitados, o Microsoft Entra ID apresenta uma caixa de diálogo de consentimento ao usuário ao entrar. Se o utilizador der o seu consentimento a um ou mais âmbitos e obtiver um token, os âmbitos aos quais foi dado consentimento ficam codificados no .

Para os escopos solicitados pela aplicação, consulte authentication.properties. Esses três escopos são solicitados pela MSAL e fornecidos pelo ID do Microsoft Entra por padrão.

Mais informações

• Biblioteca de Autenticação da Microsoft (MSAL) para Java
• Documentação de referência do MSAL 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
• Compreender as experiências de consentimento da aplicação no Microsoft Entra ID
• Compreender o consentimento do utilizador e do administrador
• Exemplos de código MSAL