Início Rápido: adquirir um token e chamar o Microsoft Graph de um aplicativo daemon Javan

Artigo
10/25/2023

Neste guia de início rápido, você baixará e executará um exemplo de código que demonstra como um aplicativo Java pode obter um token de acesso usando a identidade do aplicativo para chamar a API do Microsoft Graph e exibir uma lista de usuários no diretório. O exemplo de código demonstra como um trabalho autônomo ou um serviço Windows pode ser executado com uma identidade de aplicativo, em vez de uma identidade do usuário.

Diagram showing how the sample app generated by this quickstart works.

Pré-requisitos

Para executar este exemplo, você precisa de:

JDK (Java Development Kit) 8 ou posterior
Maven

Registrar e baixar o aplicativo de início rápido

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

Etapa 1: Registrar o aplicativo

Para registrar seu aplicativo e adicionar as informações de registro do aplicativo à solução manualmente, siga estas etapas:

Faça login no Centro de administração do Microsoft Entra como pelo menos um Desenvolvedor de aplicativos.
Se você tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o locatário no qual deseja registrar o aplicativo no menu Diretórios + assinaturas.
Navegue até Identidade>Inscrições>Registros de inscrições.
Selecione Novo registro.
Insira um Nome para seu aplicativo, por exemplo, Daemon-console. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.
Selecione Registrar.
Em Gerenciar, selecione Certificados e segredos.
Em Segredos do cliente, selecione Novo segredo do cliente, insira um nome e selecione Adicionar. Registre o valor secreto em uma localização segura para uso em uma etapa posterior.
Em Gerenciar, selecione Permissões de API>Adicionar uma permissão. Selecione Microsoft Graph.
Selecione Permissões de aplicativo.
No nó Usuário, selecione User.Read.All e selecione Adicionar permissões.

Etapa 2: Baixar o projeto Java

Baixar o projeto de daemon Java

Etapa 3: Configurar o projeto Java

Extraia o arquivo. zip em uma pasta local próxima à raiz do disco, como C:\Azure-Samples.
Navegue até a subpasta msal-client-credential-secret.
Edite src\main\resources\application.properties e substitua os valores dos campos AUTHORITY, CLIENT_ID e SECRET pelo seguinte snippet:

  AUTHORITY=https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/
  CLIENT_ID=Enter_the_Application_Id_Here
  SECRET=Enter_the_Client_Secret_Here

Em que:

Enter_the_Application_Id_Here - é a ID do aplicativo (cliente) que você registrou.
Enter_the_Tenant_Id_Here: substitua esse valor pela ID do Locatário ou pelo Nome do locatário (por exemplo, contoso.microsoft.com).
Enter_the_Client_Secret_Here – substitua esse valor pelo segredo do cliente criado na etapa 1.

Dica

Para encontrar os valores de ID do aplicativo (cliente), ID de diretório (locatário), acesse a página Visão Geral do aplicativo. Para gerar uma nova chave, acesse a página Certificados e segredos.

Se você tentar executar o aplicativo neste ponto, receberá o erro HTTP 403 – Proibido: Insufficient privileges to complete the operation. Esse erro acontece porque qualquer permissão somente do aplicativo exige o Consentimento do administrador: um Administrador Global do seu diretório precisa dar consentimento ao seu aplicativo. Selecione uma das opções abaixo, dependendo de sua função:

Administrator de locatário global

Se você é um administrador de locatários global, acesse a página Permissões de API em Registros de aplicativo e selecione Fornecer o consentimento do administrador para {Nome do Locatário} (em que {Nome do Locatário} é o nome do seu diretório).

Usuário padrão

Se você for usuário padrão do seu locatário, precisará pedir que o Administrador Global dê consentimento do administrador para seu aplicativo. Para fazer isso, dê a seguinte URL ao administrador:

https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here

Em que:

Enter_the_Tenant_Id_Here – substitua esse valor pela ID do locatário ou pelo Nome do locatário (por exemplo, contoso.microsoft.com)
Enter_the_Application_Id_Here - é a ID do aplicativo (cliente) que você registrou.

Etapa 5: Executar o aplicativo

Teste o exemplo diretamente executando o método principal de ClientCredentialGrant.java no IDE.

No shell ou na linha de comando:

$ mvn clean compile assembly:single

Isso vai gerar um arquivo msal-client-credential-secret-1.0.0.jar no diretório /targets. Execute-o usando o executável Java, conforme mostrado abaixo:

$ java -jar msal-client-credential-secret-1.0.0.jar

Após a execução, o aplicativo exibirá a lista de usuários no locatário configurado.

Importante

Este aplicativo de início rápido usa um segredo do cliente para se identificar como cliente confidencial. Como o segredo do cliente é adicionado como texto sem formatação a seus arquivos de projeto, por motivos de segurança, é recomendável que você use um certificado, em vez de um segredo do cliente, antes de considerar o aplicativo como aplicativo de produção. Para obter mais informações sobre como usar um certificado, confira estas instruções no mesmo repositório GitHub da amostra, mas na segunda pasta MSAL-client-credential-certificate.

Mais informações

MSAL Java

MSAL Java é a biblioteca usada para conectar usuários e solicitar tokens usados para acessar uma API protegida pela plataforma de identidade da Microsoft. Conforme descrito, este início rápido solicita tokens usando a identidade do próprio aplicativo, em vez de permissões delegadas. O fluxo de autenticação usado nesse caso é conhecido como fluxo OAuth de credenciais do cliente . Para obter mais informações sobre como usar a MSAL Java com aplicativos daemon, confira este artigo.

Adicione a MSAL4J ao seu aplicativo usando o Maven ou o Gradle para gerenciar as dependências fazendo as alterações a seguir no arquivo pom.xml (Maven) ou build.gradle (Gradle) do aplicativo.

No pom.xml:

<dependency>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>msal4j</artifactId>
    <version>1.0.0</version>
</dependency>

No build.gradle:

compile group: 'com.microsoft.azure', name: 'msal4j', version: '1.0.0'

Inicialização da MSAL

Adicione uma referência à MSAL para Java incluindo o seguinte código ao início do arquivo no qual você usará a MSAL4J:

import com.microsoft.aad.msal4j.*;

Em seguida, inicialize a MSAL usando o seguinte código:

IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_SECRET);

ConfidentialClientApplication cca =
        ConfidentialClientApplication
                .builder(CLIENT_ID, credential)
                .authority(AUTHORITY)
                .build();

Em que:	Descrição
`CLIENT_SECRET`	É o segredo do cliente criado para o aplicativo.
`CLIENT_ID`	É a ID do aplicativo (cliente) que você registrou. Você pode encontrar esse valor na página Visão Geral do aplicativo.
`AUTHORITY`	O ponto de extremidade do STS para o usuário autenticar. Normalmente, `https://login.microsoftonline.com/{tenant}` para a nuvem pública, em que {tenant} é o nome do seu locatário ou o ID do seu locatário.

Solicitando tokens

Para solicitar um token usando a identidade do aplicativo, use o método acquireToken:

IAuthenticationResult result;
     try {
         SilentParameters silentParameters =
                 SilentParameters
                         .builder(SCOPE)
                         .build();

         // try to acquire token silently. This call will fail since the token cache does not
         // have a token for the application you are requesting an access token for
         result = cca.acquireTokenSilently(silentParameters).join();
     } catch (Exception ex) {
         if (ex.getCause() instanceof MsalException) {

             ClientCredentialParameters parameters =
                     ClientCredentialParameters
                             .builder(SCOPE)
                             .build();

             // Try to acquire a token. If successful, you should see
             // the token information printed out to console
             result = cca.acquireToken(parameters).join();
         } else {
             // Handle other exceptions accordingly
             throw ex;
         }
     }
     return result;

Em que: Descrição

SCOPE Contém os escopos solicitados. Para clientes confidenciais, ele deve usar um formato semelhante a {Application ID URI}/.default para indicar que os escopos solicitados são os estaticamente definidos no objeto de aplicativo (no caso do Microsoft Graph, {Application ID URI} aponta para https://graph.microsoft.com). Para APIs Web personalizadas, o {Application ID URI} é definido na seção Expor uma API em Registros de aplicativo.

Em que:	Descrição
`SCOPE`	Contém os escopos solicitados. Para clientes confidenciais, ele deve usar um formato semelhante a `{Application ID URI}/.default` para indicar que os escopos solicitados são os estaticamente definidos no objeto de aplicativo (no caso do Microsoft Graph, `{Application ID URI}` aponta para `https://graph.microsoft.com`). Para APIs Web personalizadas, o `{Application ID URI}` é definido na seção Expor uma API em Registros de aplicativo.

Ajuda e suporte

Se precisar de ajuda, quiser relatar um problema ou desejar saber mais sobre as opções de suporte, confira Ajuda e suporte para desenvolvedores.

Próximas etapas

Para saber mais sobre aplicativos daemon, confira a página de aterrissagem do cenário.

Aplicativo daemon que chama APIs Web