Compartilhar via

Habilitar a entrada para aplicativos Java WebSphere por meio do Microsoft Entra ID

  • Artigo

Este exemplo apresenta um aplicativo Java WebSphere que faz a conexão de usuários com o locatário do Microsoft Entra ID usando a MSAL (Biblioteca de Autenticação da Microsoft) 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 com os usuários no 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 quiser trabalhar apenas com contas em seu 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 quiser trabalhar com contas em qualquer diretório organizacional, ou seja, no modo multilocatário. Você deve modificar este exemplo para trabalhar com uma conta pessoal da Microsoft. Se você ainda 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 pessoal da Microsoft, por exemplo, Xbox, Hotmail, Live e assim por diante, se você quiser trabalhar com contas pessoais da Microsoft.

Recomendações

Configurar o exemplo

As seções a seguir mostram como configurar o aplicativo de exemplo.

Clone ou baixe o repositório de exemplo.

Para clonar o exemplo, abra uma janela do 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

Como alternativa, navegue até o repositório ms-identity-msal-java-samples, 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. Esta seção mostra como registrar o aplicativo.

Primeiro, registre o aplicativo no portal do Azure seguindo as instruções no Início Rápido: Registar um aplicativo com a plataforma de identidade da Microsoft.

Em seguida, siga as etapas a seguir para concluir o registro:

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

  2. Selecione Novo registro.

  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 relevante para exibição aos usuários do aplicativo: por exemplo, java-servlet-webapp-authentication.

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

      • Selecione Contas somente neste diretório organizacional se você estiver criando um aplicativo para ser usado apenas por usuários do seu locatário, ou seja, um aplicativo 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 Microsoft pessoais para o mais amplo conjunto de clientes, ou seja, um aplicativo multilocatário que também oferece suporte a contas pessoais da Microsoft.
      • Selecione Contas Microsoft pessoais para uso somente por usuários de contas Microsoft pessoais, por exemplo, contas do Hotmail, Live, Skype e Xbox.

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

  4. Selecione Registrar para criar o aplicativo.

  5. Na página de registro do aplicativo, localize e copie o valor do ID do aplicativo (cliente) para uso posterior. Use esse valor no(s) arquivo(s) de configuração do aplicativo.

  6. Na página de registo do aplicativo, selecione Segredos de certificados & no painel de navegação para abrir a página para gerar segredos e carregar certificados.

  7. Na seção Segredos do Cliente, escolha Novo Segredo do Cliente.

  8. Insira 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 nas etapas posteriores. Esse valor é necessário para os arquivos de configuração do código. Esse valor não é exibido novamente e você não pode recuperá-lo por outros meios. Portanto, salve-o no portal do Azure antes de navegar para qualquer outra tela ou painel.

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. Abrir o projeto no 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 Contas somente 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 Microsoft pessoal.

  4. Localize a cadeia de caracteres {enter-your-client-id-here} e substitua o valor existente pelo ID do aplicativo ou clientId do aplicativo java-servlet-webapp-authentication 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 java-servlet-webapp-authentication, no portal do Azure.

Compilar o exemplo

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

mvn clean package

Esse comando gera um arquivo .war que pode ser executado em vários servidores de aplicativos.

Execute o exemplo

Estas instruções pressupõem que você instalou o WebSphere e configurou um servidor. Você pode usar as diretrizes em Implantar o cluster do servidor de aplicativos WebSphere (tradicional) em máquinas virtuais do Azure para obter uma configuração básica do servidor.

Antes de implantar no WebSphere, use as etapas a seguir para alterar algumas configurações no próprio exemplo e, depois, compilar ou recompilar o pacote:

  1. Navegue até o arquivo authentication.properties do aplicativo e altere o valor de app.homePage para a URL do servidor e o número da porta que você planeja 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 recompilar o aplicativo:

    mvn clean package

  3. Depois que o código terminar de ser compilado, 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, em que você a define no portal do Azure como o valor do URI de redirecionamento na guia Autenticaçã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 procurar 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.

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

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

  7. Selecione Salvar.

Use as etapas a seguir para implantar o exemplo usando o Console de soluções integradas do WebSphere:

  1. Na guia Aplicativos , selecione Novo Aplicativo e , Novo aplicativo empresarial.

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

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

  4. Selecione Concluir.

  5. Depois que o aplicativo terminar de instalar, acesse a seção Aplicativos empresariais do WebSphere da guia Aplicativos .

  6. Selecione o arquivo .war que instalou na lista de aplicativos e selecione Iniciar para implantar.

  7. Depois que ele terminar de implantar, 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 conectado ou desconectado exibido no centro da tela.
  2. Selecione o botão contextual 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 conecte-se 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 contextual 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 desconectar.
  8. Depois de sair, selecione Detalhes do token de ID para observar que a aplicação exibe um erro 401: unauthorized 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 conectar usuários ao seu locatário do Microsoft Entra ID. Se quiser usar o MSAL4J em seus próprios aplicativos, é necessário adicioná-lo aos seus projetos usando o Maven.

Se você quiser reproduzir o comportamento deste exemplo, poderá 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 pode ser usado em uma grande variedade de aplicativos. Você também pode copiar o restante do exemplo, mas as outras classes e arquivos foram criados especificamente para atender ao objetivo deste exemplo.

Contents

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

Arquivo/pasta Descrição
src/main/java/com/microsoft/azuresamples/msal4j/authwebapp/ Esse diretório contém as classes que definem a lógica comercial de back-end do aplicativo.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ Esse diretório contém as classes usadas para os pontos de extremidade de conexão e desconexão.
____Servlet.java Todos os pontos de extremidade disponíveis são definidos em classes .java que terminam 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 Configuração do Microsoft Entra ID e do programa.
src/main/webapp/ Esse diretório contém a IU: modelos JSP
CHANGELOG.md Lista de alterações no exemplo.
CONTRIBUTING.md Diretrizes para contribuir com o exemplo.
LICENÇA A licença para o exemplo.

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 a instanciação:

  • A ID do cliente do aplicativo.
  • O segredo do cliente, o qual é um requisito para Aplicativos cliente confidenciais.
  • A Autoridade do Microsoft Entra ID, que inclui seu 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 para o ponto de extremidade /authorize para o locatário do Microsoft Entra ID. A instância da MSAL4J ConfidentialClientApplication é utilizada para construir uma URL de solicitação de autorização. O aplicativo redireciona o navegador para essa URL, que é onde o usuário se conecta.

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

    • REDIRECT_URI: onde o Microsoft Entra ID redireciona o navegador, juntamente com o código de autenticação, após coletar as credenciais do usuário. Ele deve corresponder ao URI de redirecionamento no registo do aplicativo Microsoft Entra ID no portal do Azure.

    • SCOPES: Escopos os escopos são permissões solicitadas pelo aplicativo. Normalmente, os três escopos openid profile offline_access são suficientes para receber uma resposta de token de ID.

      Você pode encontrar uma lista completa dos 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 entrar for bem-sucedida, o navegador do usuário será redirecionado para o ponto de extremidade de redirecionamento do aplicativo. Uma solicitação válida ao ponto de extremidade conterá 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 uma ID e/ou token de acesso.
    • authCode: o código de autorização 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 for aprovada, os resultados serão colocados em context, uma instância de IdentityContextData, e salvos na sessão. Em seguida, o aplicativo pode criar uma instância IdentityContextData dele com base na sessão por meio de uma instância de IdentityContextAdapterServlet sempre que precisar acessá-lo, conforme mostra o 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());

Proteger 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

Escopos informam ao Microsoft Entra ID 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 para o usuário no momento da entrada. Se o usuário consentir 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. Esses três escopos são solicitados pelo MSAL e fornecidos pelo Microsoft Entra ID por padrão.

Mais informações

Próxima etapa

Implantar aplicativos Java WebSphere no WebSphere tradicional em máquinas virtuais do Azure