Share via

Habilitar a entrada para aplicativos Java Tomcat usando o Microsoft Entra ID

  • Artigo

Este artigo demonstra um aplicativo Java Tomcat que conecta usuários ao locatário do Microsoft Entra ID usando a Microsoft Authentication Library (MSAL) para Java.

O diagrama a seguir mostra a topologia do aplicativo:

Diagrama que mostra a topologia do aplicativo.

O aplicativo cliente usa o MSAL para Java (MSAL4J) para conectar usuários ao seu próprio locatário do Microsoft Entra ID e obter um token de ID 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 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 no diretório organizacional - ou seja, no modo de locatário único. Se você não tiver criado uma conta de usuário em seu locatário do Microsoft Entra ID, deverá fazê-lo antes de continuar. 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, modo multilocatário. Você deve modificar este exemplo para trabalhar com uma conta pessoal da Microsoft. Se você ainda não criou uma conta de usuário em seu locatário do Microsoft Entra ID, deverá fazê-lo antes de continuar. 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 você quiser trabalhar com contas pessoais da Microsoft.

Recomendações

  • Alguma familiaridade com os Servlets Java / Jacarta.
  • 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-servlet-webapp-authentication.git
cd 1-Authentication/sign-in

Como alternativa, navegue até o repositório ms-identity-java-servlet-webapp-authentication 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 de arquivo no Windows, clone ou extraia o repositório em um diretório próximo à raiz do disco rígido.

Registrar o aplicativo 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 para usar seu registro de 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/authentication.properties .

  3. Encontre 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 pelo java-servlet-webapp-authentication 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 criação do aplicativo, no portal do java-servlet-webapp-authentication Azure.

Compilar 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

Esse comando gera um arquivo .war que você pode executar em uma variedade de servidores de aplicativos.

Execute o exemplo

As seções a seguir mostram como implantar o exemplo no Serviço de Aplicativo do Azure.

Pré-requisitos

Configurar o plug-in do Maven

Quando você implanta no Serviço de Aplicativo do Azure, a implantação usa automaticamente suas credenciais do Azure da CLI do Azure. Se a CLI do Azure não estiver instalada localmente, o plugin Maven será autenticado com o OAuth ou com as credenciais do dispositivo. Para obter mais informações, confira autenticação com plug-ins do Maven.

Use as seguintes etapas para configurar o plug-in:

  1. Execute o comando a seguir para configurar a implantação. Este comando ajuda você a configurar o sistema operacional do Serviço de Aplicativo do Azure, a versão Java e a versão do Tomcat.

    mvn com.microsoft.azure:azure-webapp-maven-plugin:2.12.0:config

  2. Para Criar nova configuração de execução, pressione Y e pressione Enter.

  3. Em Definir valor para SO, pressione 1 para Windows ou 2 para Linux e pressione Enter.

  4. Em Define value for javaVersion, pressione 2 para Java 11 e pressione Enter.

  5. Em Define value for webContainer, pressione 4 para Tomcat 9.0 e pressione Enter.

  6. Em Define value for pricingTier, pressione Enter para selecionar a camada P1v2 padrão.

  7. Em Confirmar, pressione Y e pressione Enter.

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

Please confirm webapp properties
AppName : msal4j-servlet-auth-1707209552268
ResourceGroup : msal4j-servlet-auth-1707209552268-rg
Region : centralus
PricingTier : P1v2
OS : Linux
Java Version: Java 11
Web server stack: Tomcat 9.0
Deploy to slot : false
Confirm (Y/N) [Y]: [INFO] Saving configuration to pom.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  37.112 s
[INFO] Finished at: 2024-02-06T08:53:02Z
[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 no Serviço de Aplicativo do Azure.

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

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

Você pode modificar as configurações do Serviço de Aplicativo diretamente em seu 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 seu aplicativo.
appName true O nome do seu aplicativo.
region false A região na qual hospedar seu aplicativo. O valor padrão é centralus. Para regiões válidas, consulte Regiões com suporte.
pricingTier false A camada de preços do seu aplicativo. O valor padrão é P1v2 para uma carga de trabalho de produção. O valor mínimo recomendado para desenvolvimento e teste Java é B2. Para obter mais informações, consulte Preços do Serviço de Aplicativo.
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 obter configurações específicas do Serviço de Aplicativo do Azure, consulte Aplicativo do Azure: Detalhes de Configuração.

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

Preparar o aplicativo para implantação

Quando você implanta seu aplicativo no Serviço de Aplicativo, sua URL de redirecionamento muda para a URL de redirecionamento da instância do aplicativo implantado. Use as seguintes etapas para alterar essas configurações no arquivo de propriedades:

  1. Navegue até o arquivo authentication.properties do aplicativo e altere o valor do nome de domínio do app.homePage aplicativo implantado, conforme mostrado no exemplo a seguir. Por exemplo, se você escolheu example-domain o nome do aplicativo na etapa anterior, agora deve usar https://example-domain.azurewebsites.net para o app.homePage valor. Certifique-se de que você também alterou o protocolo de http para https.

    # 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://<your-app-name>.azurewebsites.net

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

    mvn clean package

Importante

Nesse mesmo arquivo authentication.properties, você tem uma configuração para o .aad.secret Não é uma boa prática implantar esse valor no Serviço de Aplicativo. Também não é uma boa prática deixar esse valor em seu código e potencialmente enviá-lo para seu repositório git. Para remover esse valor secreto do seu código, você pode encontrar orientações mais detalhadas na seção Implantar no Serviço de Aplicativo - Remover segredo . Esta orientação adiciona etapas extras para enviar o valor secreto para o Cofre de Chaves e para usar as Referências do Cofre de Chaves.

Atualizar o registro do aplicativo Microsoft Entra ID

Como o URI de redirecionamento muda para seu aplicativo implantado para o Serviço de Aplicativo do Azure, 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 /auth/redirect - por exemplo, https://<your-app-name>.azurewebsites.net/auth/redirect.

  7. Selecione Salvar.

Implantar o aplicativo

Agora você está pronto para implantar seu aplicativo no Serviço de Aplicativo do Azure. Use o comando a seguir para verificar se você está conectado ao seu ambiente do Azure para executar a implantação:

az login

Com toda a configuração pronta em seu arquivo pom.xml , agora você pode usar o seguinte comando para implantar seu aplicativo Java no Azure:

mvn package azure-webapp:deploy

Após a conclusão da implantação, seu aplicativo estará pronto em http://<your-app-name>.azurewebsites.net/. Abra a URL com seu navegador da Web local, onde você deve ver a página inicial do msal4j-servlet-auth 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.
  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. 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. Use o botão no canto para sair.
  8. Depois de sair, selecione Detalhes do Token de ID para observar se o aplicativo exibe um 401: unauthorized erro em vez das declarações de token de ID quando o usuário não está autorizado.

Observações sobre o código

Este exemplo mostra como usar o MSAL para Java (MSAL4J) para entrar usuários em seu locatário do Microsoft Entra ID. Se você quiser usar o MSAL4J em seus próprios aplicativos, deverá adicioná-lo aos seus projetos usando o Maven.

Se desejar replicar o comportamento deste exemplo, você poderá copiar o arquivo pom.xml e o conteúdo das pastas auxiliares 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 atender ao objetivo desse exemplo.

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.
src/main/java/com/microsoft/azuresamples/msal4j/authwebapp/ Esse diretório contém as classes que definem a lógica de negócios de back-end do aplicativo.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ Esse diretório contém as classes usadas para pontos de extremidade de entrada e saída.
____Servlet.java Todos os pontos de extremidade disponíveis são definidos em classes .java terminadas em ____Servlet.java..
src/main/java/com/microsoft/azuresamples/msal4j/helpers/ Classes auxiliares para autenticação.
AuthenticationFilter.java Redireciona solicitações não autenticadas para pontos de extremidade protegidos para uma página 401.
src/main/resources/authentication.properties ID do Microsoft Entra e configuração do programa.
src/main/webapp/ Este diretório contém os modelos UI - JSP
CHANGELOG.md Lista de alterações à amostra.
CONTRIBUTING.md Orientações para contribuição à amostra.
LICENÇA A licença para a amostra.

ConfidentialClientApplication

Uma ConfidentialClientApplication instância é criada no arquivo AuthHelper.java , conforme mostrado no exemplo a seguir. Esse 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 cliente confidenciais.
  • A Autoridade de ID do Microsoft Entra, que inclui sua ID de locatário do Microsoft Entra ID.

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

Orientação 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 ao /authorize ponto de extremidade para seu locatário do Microsoft Entra ID. A instância MSAL4J ConfidentialClientApplication é usada para construir uma URL de solicitação de autorização. O aplicativo redireciona o navegador para essa URL, que é onde o usuário faz login.

    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 criar um AuthorizationRequestUrl.

    • REDIRECT_URI: Onde o Microsoft Entra ID redireciona o navegador - junto 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.

      Você pode encontrar uma lista completa de escopos solicitados pelo aplicativo no arquivo authentication.properties . Você pode adicionar mais escopos, como User.Read.

  2. O usuário recebe um prompt de entrada do Microsoft Entra ID. 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 esse 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 um 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-sucedido, 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 o IdentityContextData da sessão por meio de uma instância de IdentityContextAdapterServlet sempre que precisar acessá-lo, 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 claim(s)
app.protect.authenticated=/token_details

Escopos

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

Com base nos escopos solicitados, a ID do Microsoft Entra 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 obter os escopos solicitados pelo aplicativo, consulte authentication.properties. Esses três escopos são solicitados pela MSAL e fornecidos pelo Microsoft Entra ID por padrão.

Mais informações