Ativar o início de sessão para aplicações Java Tomcat com o MSAL4J e o Azure Active Directory B2C

Este artigo demonstra uma aplicação Java Tomcat que autentica utilizadores no Azure Active Directory B2C (Azure AD B2C) utilizando a Biblioteca de Autenticação da Microsoft para Java (MSAL4J).

Nota

Desde 1 de maio de 2025, o Azure Active Directory B2C já não está disponível para compra para novos clientes. Os clientes existentes podem continuar a usar o Azure AD B2C, com suporte fornecido pelo menos até maio de 2030. Para novos projetos de gestão de identidade e acesso de clientes (CIAM), utilize o ID externo Microsoft Entra em vez disso.

O diagrama a seguir mostra a topologia do aplicativo:

Diagrama que mostra a topologia da aplicação.

A aplicação utiliza o MSAL4J para iniciar sessão dos utilizadores e obter um token de ID do Azure AD B2C. O token ID prova que o utilizador está autenticado contra um inquilino B2C do Azure AD.

Pré-requisitos

• JDK versão 8 ou posterior
• Maven 3
• Um inquilino do Azure AD B2C. Para obter mais informações, consulte Tutorial: Criar um inquilino do Azure Active Directory B2C
• Uma conta de usuário em seu locatário do Azure AD B2C.

• Tomcat 9
• 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-b2c

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.

Importante

Para evitar limitações de comprimento de caminho de arquivo no Windows, clone ou extraia o repositório em um diretório perto da raiz do seu disco rígido.

Registe a aplicação de exemplo no seu inquilino do Azure AD B2C

A amostra vem com um aplicativo pré-registrado para fins de teste. Se você quiser usar seu próprio locatário e aplicativo do Azure AD B2C, siga as etapas nas seções a seguir para registrar e configurar o aplicativo no portal do Azure. Caso contrário, continue com os passos para Executar o exemplo.

Escolha o locatário do Azure AD B2C onde você deseja criar seus aplicativos

Para escolher o seu inquilino, siga os seguintes passos:

1. Inicie sessão no portal do Azure.

2. Se a sua conta estiver presente em mais do que um inquilino do Azure AD B2C, selecione o seu perfil no canto do portal do Azure e, em seguida, selecione Switch directory para mudar a sessão para o inquilino pretendido do Azure AD B2C.

Criar fluxos de usuário e políticas personalizadas

Para criar fluxos de utilizador comuns, como registo, início de sessão, edição do perfil e reposição da palavra-passe, consulte Tutorial: Criar fluxos de utilizador no Azure Active Directory B2C.

Também deve considerar criar políticas personalizadas no Azure Active Directory B2C; no entanto, isso está fora do âmbito deste tutorial.

Adicionar provedores de identidade externos

Consulte Tutorial: Adicionar fornecedores de identidade às suas aplicações no Azure Active Directory B2C.

Registrar o aplicativo (ms-identity-b2c-java-servlet-webapp-authentication)

Para registrar o aplicativo, use as seguintes etapas:

1. Navegue até ao Azure portal e selecione Azure AD B2C.

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 secção Name, introduza um nome significativo para a aplicação, para apresentar aos utilizadores da aplicação - por exemplo, .
   • Em Tipos de conta suportados, selecione Contas em qualquer diretório organizacional e contas pessoais da Microsoft (por exemplo, Skype, Xbox, Outlook.com).
   • Na secção URI de Redirecionamento (opcional), 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. 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 secção Segredos de cliente, selecione Novo segredo de cliente.

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

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

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.

Configure o aplicativo (ms-identity-b2c-java-servlet-webapp-authentication) para usar o registro do aplicativo

Use as seguintes etapas para configurar o aplicativo:

Nota

Nos passos seguintes, corresponde a ou .

1. Abra o projeto no seu IDE.

2. Abra o ficheiro ./src/main/resources/authentication.properties.

3. Encontre a propriedade e substitua o valor existente pelo ID da aplicação ou da aplicação no portal do Azure.

4. Encontre a propriedade e substitua o valor existente pelo valor que guardou durante a criação da aplicação no portal do Azure.

5. Encontre a propriedade e substitua o clientId da aplicação existente pelo valor que colocou em no passo 1 desta secção.

6. Localize a propriedade e substitua a primeira instância de pelo nome do inquilino do Azure AD B2C no qual criou a aplicação no portal do Azure.

7. Encontre a propriedade e substitua a segunda ocorrência de pelo nome do inquilino do Azure AD B2C em que criou a aplicação no portal do Azure.

8. Localize a propriedade e substitua-a pelo nome da política de fluxo de utilizador de inscrição/início de sessão que criou no tenant do Azure AD B2C em que criou a aplicação no portal do Azure.

9. Localize a propriedade e substitua-a pelo nome da política de fluxo de utilizador de reposição da palavra-passe que criou no inquilino do Azure AD B2C no qual criou a aplicação no portal do Azure.

10. Encontre a propriedade e substitua-a pelo nome da política de fluxo de utilizador de edição de perfil que criou no inquilino do Azure AD B2C em que criou a 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

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

Pré-requisitos

• Plug-in do Maven para aplicações do Serviço de Aplicações do Azure

  Se o Maven não for sua ferramenta de desenvolvimento preferida, consulte os seguintes tutoriais semelhantes que usam outras ferramentas:

  • IntelliJ IDEA
  • Eclipse
  • Visual Studio Code

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 plug-in do Maven será autenticado com OAuth ou entrada no dispositivo. Para mais informações, consulte autenticação com plug-ins Maven.

Use as seguintes etapas para configurar o plug-in:

1. Execute o seguinte comando 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.13.0:config
   

2. Para Criar nova configuração de execução, prima Y e, em seguida, prima Enter.

3. Para Definir valor para o SO, prima 1 para Windows, ou 2 para Linux e, em seguida, prima Enter.

4. Em Define value for javaVersion, prima 2 para Java 11, depois prima Enter.

5. Para Definir valor para webContainer, prima 4 para Tomcat 9.0, e depois prima Enter.

6. Para Definir valor para pricingTier, prima Enter para selecionar o escalão P1v2 predefinido.

7. Para Confirmar, prima Y e, em seguida, prima 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 as suas escolhas, o plug-in adiciona o elemento do plug-in e as definições necessárias ao ficheiro pom.xml do seu projeto para configurar a sua aplicação para ser executada no Serviço de Aplicações 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>

Pode modificar as definições do App Service diretamente no seu pom.xml. Algumas configurações comuns estão listadas na tabela a seguir:

Propriedade	Necessário	Descrição
subscriptionId	false	O ID da subscrição.
resourceGroup	verdadeiro	O grupo de recursos do Azure para seu aplicativo.
appName	verdadeiro	O nome do seu aplicativo.
region	false	A região na qual hospedar seu aplicativo. O valor predefinido é . Para conhecer as regiões válidas, consulte Regiões suportadas.
pricingTier	false	O nível de preços do seu aplicativo. O valor predefinido é para uma carga de trabalho de produção. O valor mínimo recomendado para desenvolvimento e testes em Java é . Para obter mais informações, consulte Preços do App Service.
runtime	false	A configuração do ambiente de tempo de execução. Para obter mais informações, consulte Detalhes de configuração.
deployment	false	A configuração de implantação. Para obter mais informações, consulte Detalhes de configuração.

Para obter a lista completa de configurações, consulte a documentação de referência do plugin. Todos os plug-ins do Azure Maven compartilham um conjunto comum de configurações. Para estas configurações, consulte Configurações comuns. Para configurações específicas do Serviço de Aplicações do Azure, consulte Azure app: Configuration Details.

Certifique-se de guardar os valores de e para utilizar mais tarde.

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 implantada. Use as seguintes etapas para alterar essas configurações no arquivo de propriedades:

1. Navegue até ao ficheiro authentication.properties da sua aplicação e altere o valor de para o nome de domínio da sua aplicação implementada, conforme mostrado no exemplo seguinte. Por exemplo, se escolheu como nome da aplicação no passo anterior, tem agora de usar para o valor . Certifique-se de que também alterou o protocolo de para .

   # 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 reconstruir seu aplicativo:

   mvn clean package
   

Importante

Neste mesmo ficheiro authentication.properties, tem uma definição para o seu . 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 o repositório git. Para remover este valor secreto do seu código, pode encontrar orientações mais detalhadas na secção Implementar no App Service - Remover segredo. Estas orientações adicionam passos extra para enviar o valor do segredo para o Key Vault e para utilizar as Referências do Key Vault.

Atualizar o registo da aplicação Microsoft Entra ID

Como o URI de redirecionamento muda para a sua aplicação implementada no Serviço de Aplicações do Azure, também precisa de alterar o URI de redirecionamento no registo da aplicação no Microsoft Entra ID. Use as seguintes etapas para fazer essa alteração:

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

2. Utilize a caixa de pesquisa para procurar o registo da sua aplicação - por exemplo, .

3. Abra o registro do aplicativo selecionando seu nome.

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

5. Na secção WebURIs de redirecionamento, selecione Adicionar URI.

6. Preencha o URI da sua aplicação, acrescentando — por exemplo, .

7. Selecione Guardar.

Implementar a aplicação

Agora você está pronto para implantar seu aplicativo no Serviço de Aplicativo do Azure. Use o seguinte comando para garantir que você esteja 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

Quando a implementação estiver concluída, a sua aplicação estará disponível em . Abra o URL com o navegador web local, onde deverá ver a página inicial da aplicação .

Para executar o exemplo no Tomcat, use as seguintes etapas:

1. Na instalação do Tomcat, verifique se há uma entrada no tomcat/conf/server.xml para o endereço no qual você deseja hospedar seu aplicativo.

   Por predefinição, os exemplos apenas pressupõem uma ligação a , conforme definido no valor no ficheiro authentication.properties.

2. Copie o arquivo .war gerado com o Maven para o diretório /webapps/ na instalação do Tomcat e inicie o servidor Tomcat.

3. Depois que o Tomcat iniciar, abra seu navegador e navegue até qualquer URL que você definiu na etapa 1 e você deverá ser capaz de acessar o aplicativo.

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 inicie sessão com uma conta do fornecedor de identidade escolhido.
4. Observe que o botão sensível ao contexto agora diz Sair e exibe seu nome de usuário.
5. Selecione Detalhes do token de ID para ver alguns dos claims descodificados do token de ID.
6. Você também tem a opção de editar seu perfil. Selecione o link para editar detalhes como seu nome para exibição, local de residência e profissão.
7. Use o botão no canto para sair.
8. Depois de terminar sessão, navegue para o seguinte URL da página de detalhes do token: . Aqui, pode observar como a aplicação apresenta o erro em vez das declarações do token de ID.

Sobre o código

Este exemplo demonstra como utilizar o MSAL4J para iniciar sessão dos utilizadores no seu inquilino do Azure AD B2C.

Conteúdos

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

Ficheiro/pasta	Descrição
AuthHelper.java	Funções auxiliares para autenticação.
Config.java	É executado na inicialização e configura o leitor de propriedades e o registrador.
authentication.properties	Microsoft Entra ID e configuração do programa.
AuthenticationFilter.java	Redireciona solicitações não autenticadas para recursos protegidos para uma página 401.
MsalAuthSession	Instanciado com um . Armazena todos os atributos de sessão relacionados ao MSAL no atributo session.
*Servlet.java	Todos os endpoints disponíveis são definidos em classes Java com nomes terminados em Servlet..
CHANGELOG.md	Lista de alterações à amostra.
CONTRIBUTING.md	Orientações para contribuir para a amostra.
LICENÇA	A licença para a amostra.

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 Azure AD B2C e também ajuda a trocar o token de autenticação por um token de acesso.

IClientSecret secret = ClientCredentialFactory.createFromSecret(SECRET);
confClientInstance = ConfidentialClientApplication
                     .builder(CLIENT_ID, secret)
                     .b2cAuthority(AUTHORITY + policy)
                     .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 Azure AD B2C concatenada com o elemento adequado para registo, início de sessão, edição de perfil ou reposição da palavra-passe.

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 do seu inquilino do Azure Active Directory B2C. A instância de MSAL4J é usada para construir um URL de pedido de autorização, e a aplicação redireciona o navegador para esse URL, conforme mostrado no exemplo seguinte:

   final ConfidentialClientApplication client = getConfidentialClientInstance(policy);
   final AuthorizationRequestUrlParameters parameters = AuthorizationRequestUrlParameters
       .builder(REDIRECT_URI, Collections.singleton(SCOPES)).responseMode(ResponseMode.QUERY)
       .prompt(Prompt.SELECT_ACCOUNT).state(state).nonce(nonce).build();
   
   final String redirectUrl = client.getAuthorizationRequestUrl(parameters).toString();
   Config.logger.log(Level.INFO, "Redirecting user to {0}", redirectUrl);
   resp.setStatus(302);
   resp.sendRedirect(redirectUrl);
   

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

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

   • : Onde o Azure AD B2C redireciona o navegador — juntamente com o código de autorização — depois de recolher as credenciais do utilizador.

   • : Escopos são permissões solicitadas pela aplicação.

     Normalmente, os três âmbitos seriam suficientes para receber uma resposta com um token de ID. No entanto, o MSAL4J requer que todas as respostas do Azure AD B2C também contenham um token de acesso.

     Para que o Azure AD B2C dispense um token de acesso, bem como um token de ID, a solicitação deve incluir um escopo de recurso adicional. Como esse aplicativo não requer um escopo de recurso externo, ele adiciona sua própria ID de cliente como um quarto escopo para receber um token de acesso.

     Pode encontrar uma lista completa dos âmbitos solicitados pela aplicação no ficheiro authentication.properties.

   • : O Azure AD B2C pode devolver a resposta como parâmetros de um formulário num pedido HTTP POST ou como parâmetros de cadeia de consulta num pedido HTTP GET.

   • : o Azure AD B2C deve pedir ao utilizador para selecionar a conta com a qual pretende autenticar-se.

   • : Uma variável única definida pela aplicação na sessão em cada pedido de token e destruída após a receção do callback de redirecionamento correspondente do Azure AD B2C. A variável de estado garante que os pedidos do Azure AD B2C para o provêm efetivamente de pedidos de autorização do Azure AD B2C com origem nesta aplicação e nesta sessão, evitando assim ataques de CSRF. Isto é feito no ficheiro AADRedirectServlet.java.

   • : Uma variável exclusiva definida pela aplicação na sessão a cada pedido de token e eliminada após a receção do token correspondente. Este nonce é incluído nos tokens resultantes emitidos pelo Azure AD B2C, garantindo assim que não ocorra qualquer ataque de repetição de tokens.

2. O usuário recebe um prompt de entrada do Azure Ative Directory B2C. 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 esse código de autorização por um token de identificação e um token de acesso do Azure Active Directory B2C, conforme mostrado no exemplo seguinte:

   final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
                       .builder(authCode, new URI(REDIRECT_URI))
                       .scopes(Collections.singleton(SCOPES)).build();
   
   final ConfidentialClientApplication client = AuthHelper
           .getConfidentialClientInstance(policy);
   final Future<IAuthenticationResult> future = client.acquireToken(authParams);
   final IAuthenticationResult result = future.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 do token são extraídas e a declaração `nonce` é validada face ao nonce armazenado na sessão, conforme mostrado no exemplo seguinte:

   parseJWTClaimsSetAndStoreResultInSession(msalAuth, result, serializedTokenCache);
   validateNonce(msalAuth)
   processSuccessfulAuthentication(msalAuth);
   

5. Se o nonce for validado com êxito, o estado de autenticação é armazenado numa sessão no lado do servidor, recorrendo aos métodos expostos pela classe , conforme mostrado no exemplo seguinte:

   msalAuth.setAuthenticated(true);
   msalAuth.setUsername(msalAuth.getIdTokenClaims().get("name"));
   

Mais informações

• O que é o Azure Active Directory B2C?
• Tipos de aplicações que podem ser utilizados no Azure Active Directory B2C
• Recomendações e melhores práticas para o Azure Active Directory B2C
• Sessão do Azure AD B2C
• Biblioteca de Autenticação da Microsoft (MSAL) para Java

Para obter mais informações sobre o funcionamento dos protocolos OAuth 2.0 neste cenário e noutros cenários, consulte Cenários de autenticação do Microsoft Entra ID.