Criar aplicativos Java com o Microsoft Graph e a autenticação somente aplicativo
Este tutorial ensina como criar um aplicativo de console Java que usa o microsoft API do Graph para acessar dados usando autenticação somente aplicativo. A autenticação somente aplicativo é uma boa opção para serviços em segundo plano ou aplicativos que precisam acessar dados para todos os usuários de uma organização.
Observação
Para saber como usar o Microsoft Graph para acessar dados em nome de um usuário, consulte este tutorial de autenticação de usuário (delegado).
Neste tutorial, você vai:
Dica
Como alternativa a seguir este tutorial, você pode baixar ou clonar o repositório GitHub e seguir as instruções no README para registrar um aplicativo e configurar o projeto.
Pré-requisitos
Antes de iniciar este tutorial, você deve ter o JDK (Java SE Development Kit) e o Gradle instalados em seu computador de desenvolvimento.
Você também deve ter uma conta de trabalho ou de estudante da Microsoft com a função Administrador global. Se você não tiver um locatário do Microsoft 365, poderá se qualificar para um por meio do Programa de Desenvolvedores do Microsoft 365; para obter detalhes, confira as perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou comprar um plano do Microsoft 365.
Observação
Este tutorial foi escrito com OpenJDK versão 17.0.2 e Gradle 7.4.2. As etapas neste guia podem funcionar com outras versões, mas isso não foi testado.
Registrar o aplicativo no portal
Neste exercício, você registrará um novo aplicativo no Azure Active Directory para habilitar a autenticação somente aplicativo. Você pode registrar um aplicativo usando o centro de administração do Azure Active Directory ou usando o SDK do Microsoft Graph PowerShell.
Registrar aplicativo para autenticação somente aplicativo
Nesta seção, você registrará um aplicativo que dá suporte à autenticação somente aplicativo usando o fluxo de credenciais do cliente.
Abra um navegador e navegue até o centro de administração do Azure Active Directory e faça logon usando uma conta Administrador global.
Selecione Azure Active Directory na navegação esquerda e selecione Registros de aplicativos em Gerenciar.
Selecione Novo registro. Insira um nome para seu aplicativo, por exemplo,
Graph App-Only Auth Tutorial
.Defina tipos de conta com suporte apenas para contas neste diretório organizacional.
Deixe o URI de Redirecionamento vazio.
Selecione Registrar. Na página Visão geral do aplicativo, copie o valor da ID do Aplicativo (cliente) e da ID do Diretório (locatário) e salve-os, você precisará desses valores na próxima etapa.
Selecione Permissões de API em Gerenciar.
Remova a permissão padrão User.Read em Permissões configuradas selecionando as reticências (...) em sua linha e selecionando Remover permissão.
Selecione Adicionar uma permissão e, em seguida, Microsoft Graph.
Selecione Permissões de aplicativos.
Selecione User.Read.All e, em seguida, selecione Adicionar permissões.
Selecione Conceder consentimento do administrador para...e selecione Sim para fornecer o consentimento do administrador para a permissão selecionada.
Selecione Certificados e segredos em Gerenciar e selecione Novo segredo do cliente.
Insira uma descrição, escolha uma duração e selecione Adicionar.
Copie o segredo da coluna Valor , você precisará dele nas próximas etapas.
Importante
Este segredo do cliente nunca é mostrado novamente, portanto, certifique-se de copiá-lo agora.
Observação
Observe que, ao contrário das etapas ao se registrar para autenticação do usuário, nesta seção você configurou as permissões do Microsoft Graph no registro do aplicativo. Isso ocorre porque a auth somente aplicativo usa o fluxo de credenciais do cliente, o que exige que as permissões sejam configuradas no registro do aplicativo. Consulte O escopo .default para obter detalhes.
Criar um aplicativo de console Java
Nesta seção, você criará um aplicativo de console Java básico.
Abra sua CLI (interface de linha de comando) em um diretório em que você deseja criar o projeto. Execute o comando a seguir para criar um novo projeto Gradle.
gradle init --dsl groovy --test-framework junit --type java-application --project-name graphapponlytutorial --package graphapponlytutorial
Depois que o projeto for criado, verifique se ele funciona executando o comando a seguir para executar o aplicativo em sua CLI.
./gradlew --console plain run
Se funcionar, o aplicativo deverá gerar
Hello World.
.
Instalar dependências
Antes de seguir em frente, adicione algumas dependências adicionais que você usará posteriormente.
- Biblioteca de clientes do Azure Identity para Java para autenticar o usuário e adquirir tokens de acesso.
- SDK do Microsoft Graph para Java para fazer chamadas para o Microsoft Graph.
Abra ./app/build.gradle. Atualize a
dependencies
seção para adicionar essas dependências.dependencies { // Use JUnit test framework. testImplementation 'junit:junit:4.13.2' // This dependency is used by the application. implementation 'com.google.guava:guava:33.2.1-jre' implementation 'com.azure:azure-identity:1.13.0' implementation 'com.microsoft.graph:microsoft-graph:6.13.0' }
Adicione o seguinte ao final de ./app/build.gradle.
run { standardInput = System.in }
Na próxima vez que você criar o projeto, o Gradle baixará essas dependências.
Carregar configurações do aplicativo
Nesta seção, você adicionará os detalhes do registro do aplicativo ao projeto.
Crie um novo diretório chamado graphapponlytutorial no diretório ./app/src/main/resources.
Crie um novo arquivo no diretório ./app/src/main/resources/graphapponlytutorial chamado oAuth.properties e adicione o texto a seguir nesse arquivo.
app.clientId=YOUR_CLIENT_ID_HERE app.clientSecret=YOUR_CLIENT_SECRET_HERE app.tenantId=YOUR_TENANT_ID_HERE
Atualize os valores de acordo com a tabela a seguir.
Configuração Valor app.clientId
A ID do cliente do registro do aplicativo app.tenantId
A ID do locatário da sua organização app.clientSecret
O segredo do cliente Importante
Se você estiver usando o controle de origem, como o git, agora seria uma boa hora para excluir o arquivo oAuth.properties do controle de origem para evitar o vazamento inadvertida da ID do aplicativo.
Design do aplicativo
Nesta seção, você criará um menu simples baseado em console.
Abra ./app/src/main/java/graphapponlytutorial/App.java e adicione as instruções a seguir
import
.package graphapponlytutorial; import java.io.IOException; import java.util.InputMismatchException; import java.util.Properties; import java.util.Scanner; import com.microsoft.graph.models.User;
Substitua a função
main
existente pela seguinte.public static void main(String[] args) { System.out.println("Java App-Only Graph Tutorial"); System.out.println(); final Properties oAuthProperties = new Properties(); try { oAuthProperties.load(App.class.getResourceAsStream("oAuth.properties")); } catch (IOException e) { System.out.println("Unable to read OAuth configuration. Make sure you have a properly formatted oAuth.properties file. See README for details."); return; } initializeGraph(oAuthProperties); Scanner input = new Scanner(System.in); int choice = -1; while (choice != 0) { System.out.println("Please choose one of the following options:"); System.out.println("0. Exit"); System.out.println("1. Display access token"); System.out.println("2. List users"); System.out.println("3. Make a Graph call"); try { choice = input.nextInt(); } catch (InputMismatchException ex) { // Skip over non-integer input } input.nextLine(); // Process user choice switch(choice) { case 0: // Exit the program System.out.println("Goodbye..."); break; case 1: // Display access token displayAccessToken(); break; case 2: // List users listUsers(); break; case 3: // Run any Graph code makeGraphCall(); break; default: System.out.println("Invalid choice"); } } input.close(); }
Adicione os seguintes métodos de espaço reservado no final do arquivo. Você os implementará em etapas posteriores.
private static void initializeGraph(Properties properties) { // TODO } private static void displayAccessToken() { // TODO } private static void listUsers() { // TODO } private static void makeGraphCall() { // TODO }
Isso implementa um menu básico e lê a escolha do usuário na linha de comando.
- Exclua ./app/src/test/java/graphapponlytutorial/AppTest.java.
Adicionar autenticação somente aplicativo
Nesta seção, você adicionará a autenticação somente aplicativo ao aplicativo. Isso é necessário para obter o token de acesso OAuth necessário para chamar o Microsoft Graph. Nesta etapa, você integrará a biblioteca de clientes do Azure Identity para Java ao aplicativo e configurará a autenticação para o SDK do Microsoft Graph para Java.
Configurar o cliente graph para autenticação somente aplicativo
Nesta seção, você usará a ClientSecretCredential
classe para solicitar um token de acesso usando o fluxo de credenciais do cliente.
Crie um novo arquivo no diretório ./app/src/main/java/graphapponlytutorial chamado Graph.java e adicione o código a seguir a esse arquivo.
package graphapponlytutorial; import java.util.Properties; import com.azure.core.credential.AccessToken; import com.azure.core.credential.TokenRequestContext; import com.azure.identity.ClientSecretCredential; import com.azure.identity.ClientSecretCredentialBuilder; import com.microsoft.graph.models.UserCollectionResponse; import com.microsoft.graph.serviceclient.GraphServiceClient;
Adicione uma definição de classe graph vazia.
public class Graph { }
Adicione o código a seguir à classe Graph.
private static Properties _properties; private static ClientSecretCredential _clientSecretCredential; private static GraphServiceClient _appClient; public static void initializeGraphForAppOnlyAuth(Properties properties) throws Exception { // Ensure properties isn't null if (properties == null) { throw new Exception("Properties cannot be null"); } _properties = properties; if (_clientSecretCredential == null) { final String clientId = _properties.getProperty("app.clientId"); final String tenantId = _properties.getProperty("app.tenantId"); final String clientSecret = _properties.getProperty("app.clientSecret"); _clientSecretCredential = new ClientSecretCredentialBuilder() .clientId(clientId) .tenantId(tenantId) .clientSecret(clientSecret) .build(); } if (_appClient == null) { _appClient = new GraphServiceClient(_clientSecretCredential, new String[] { "https://graph.microsoft.com/.default" }); } }
Substitua a função vazia
initializeGraph
no App.java pelo seguinte.private static void initializeGraph(Properties properties) { try { Graph.initializeGraphForAppOnlyAuth(properties); } catch (Exception e) { System.out.println("Error initializing Graph for user auth"); System.out.println(e.getMessage()); } }
Esse código declara duas propriedades privadas, um ClientSecretCredential
objeto e um GraphServiceClient
objeto. A initializeGraphForAppOnlyAuth
função cria uma nova instância de ClientSecretCredential
, em seguida, usa essa instância para criar uma nova instância de GraphServiceClient
. Sempre que uma chamada de API for feita ao Microsoft Graph por meio do _appClient
, ela usará a credencial fornecida para obter um token de acesso.
Testar o ClientSecretCredential
Em seguida, adicione código para obter um token de acesso do ClientSecretCredential
.
Adicione a função a seguir à classe
Graph
.public static String getAppOnlyToken() throws Exception { // Ensure credential isn't null if (_clientSecretCredential == null) { throw new Exception("Graph has not been initialized for app-only auth"); } // Request the .default scope as required by app-only auth final String[] graphScopes = new String[] {"https://graph.microsoft.com/.default"}; final TokenRequestContext context = new TokenRequestContext(); context.addScopes(graphScopes); final AccessToken token = _clientSecretCredential.getToken(context).block(); return token.getToken(); }
Substitua a função vazia
displayAccessToken
no App.java pelo seguinte.private static void displayAccessToken() { try { final String accessToken = Graph.getAppOnlyToken(); System.out.println("Access token: " + accessToken); } catch (Exception e) { System.out.println("Error getting access token"); System.out.println(e.getMessage()); } }
Crie e execute o aplicativo. Insira
1
quando solicitado para uma opção. O aplicativo exibe um token de acesso.Java App-Only Graph Tutorial Please choose one of the following options: 0. Exit 1. Display access token 2. List users 3. Make a Graph call 1 App-only token: eyJ0eXAiOiJKV1QiLCJub25jZSI6IlVDTzRYOWtKYlNLVjVkRzJGenJqd2xvVUcwWS...
Dica
Somente para fins de validação e depuração, você pode decodificar tokens de acesso do usuário (somente para contas corporativas ou escolares) usando o analisador de token online da Microsoft em https://jwt.ms. Isso pode ser útil se você encontrar erros de token ao chamar o Microsoft Graph. Por exemplo, verificar se a
scp
declaração no token contém os escopos de permissão esperados do Microsoft Graph.
Listar usuários
Nesta seção, você adicionará a capacidade de listar todos os usuários em seu Azure Active Directory usando autenticação somente aplicativo.
Abra Graph.java e adicione a seguinte função à classe Graph .
public static UserCollectionResponse getUsers() throws Exception { // Ensure client isn't null if (_appClient == null) { throw new Exception("Graph has not been initialized for app-only auth"); } return _appClient.users().get(requestConfig -> { requestConfig.queryParameters.select = new String[] { "displayName", "id", "mail" }; requestConfig.queryParameters.top = 25; requestConfig.queryParameters.orderby = new String[] { "displayName" }; }); }
Substitua a função vazia
listUsers
no App.java pelo seguinte.private static void listUsers() { try { final UserCollectionResponse users = Graph.getUsers(); // Output each user's details for (User user: users.getValue()) { System.out.println("User: " + user.getDisplayName()); System.out.println(" ID: " + user.getId()); System.out.println(" Email: " + user.getMail()); } final Boolean moreUsersAvailable = users.getOdataNextLink() != null; System.out.println("\nMore users available? " + moreUsersAvailable); } catch (Exception e) { System.out.println("Error getting users"); System.out.println(e.getMessage()); } }
Execute o aplicativo, entre e escolha a opção 4 para listar usuários.
Please choose one of the following options: 0. Exit 1. Display access token 2. List users 3. Make a Graph call 2 User: Adele Vance ID: 05fb57bf-2653-4396-846d-2f210a91d9cf Email: AdeleV@contoso.com User: Alex Wilber ID: a36fe267-a437-4d24-b39e-7344774d606c Email: AlexW@contoso.com User: Allan Deyoung ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0 Email: AllanD@contoso.com User: Bianca Pisani ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Email: NO EMAIL User: Brian Johnson (TAILSPIN) ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Email: BrianJ@contoso.com ... More users available? True
Código explicado
Considere o código na getUsers
função.
Acessando uma coleção
Esse método retorna uma coleção de usuários. A maioria das APIs no Microsoft Graph que retornam uma coleção não retorna todos os resultados disponíveis em uma única resposta. Em vez disso, eles usam paginação para retornar uma parte dos resultados, fornecendo um método para os clientes solicitarem a próxima "página".
Tamanhos de página padrão
APIs que usam paginação implementam um tamanho de página padrão. Para usuários, o valor padrão é 10. Os clientes podem solicitar mais (ou menos) usando o parâmetro de consulta $top . No getUsers
, isso é feito com a top
propriedade na configuração da solicitação.
Observação
O valor definido em top
é um limite superior, não um número explícito. A API retorna um número de usuários até o valor especificado.
Obtendo páginas subsequentes
Se houver mais resultados disponíveis no servidor, as respostas de coleção incluirão uma @odata.nextLink
propriedade com uma URL de API para acessar a próxima página. A biblioteca de clientes Java expõe isso como o getOdataNextLink
método em objetos de resposta de coleção. Se esse método retornar não nulo, haverá mais resultados disponíveis.
Classificando coleções
A função usa a orderBy
propriedade na configuração da solicitação para solicitar resultados classificados pelos nomes de exibição dos usuários. Isso adiciona o parâmetro de consulta $orderby à chamada de API.
Opcional: adicionar seu próprio código
Nesta seção, você adicionará seus próprios recursos do Microsoft Graph ao aplicativo. Isso pode ser um snippet de código da documentação do Microsoft Graph ou do Graph Explorer ou código que você criou. Esta seção é opcional.
Atualizar o aplicativo
Abra Graph.java e adicione a seguinte função à classe Graph .
public static void makeGraphCall() { // INSERT YOUR CODE HERE }
Substitua a função vazia
MakeGraphCallAsync
no App.java pelo seguinte.private static void makeGraphCall() { try { Graph.makeGraphCall(); } catch (Exception e) { System.out.println("Error making Graph call"); System.out.println(e.getMessage()); } }
Escolher uma API
Encontre uma API no Microsoft Graph que você gostaria de experimentar. Por exemplo, a API criar eventos . Você pode usar um dos exemplos na documentação da API ou personalizar uma solicitação de API no Graph Explorer e usar o snippet gerado.
Configurar as permissões
Verifique a seção Permissões da documentação de referência da API escolhida para ver quais métodos de autenticação têm suporte. Algumas APIs não dão suporte somente a aplicativos ou contas pessoais da Microsoft, por exemplo.
- Para chamar uma API com autenticação de usuário (se a API dá suporte à autenticação do usuário (delegada), consulte o tutorial de autenticação do usuário (delegado ).
- Para chamar uma API com autenticação somente aplicativo (se a API dá suporte a ela), adicione o escopo de permissão necessário no centro de administração Azure AD.
Adicionar seu código
Copie seu makeGraphCallAsync
código na função em Graph.java. Se você estiver copiando um snippet da documentação ou do Graph Explorer, renomeie o GraphServiceClient
para _appClient
.
Parabéns!
Você concluiu o tutorial do Java Microsoft Graph. Agora que você tem um aplicativo de trabalho que chama Microsoft Graph, você pode experimentar e adicionar novos recursos.
- Saiba como usar a autenticação de usuário (delegada) com o SDK java do Microsoft Graph.
- Visite a visão geral do Microsoft Graph para ver todos os dados que você pode acessar com o Microsoft Graph.
Exemplos de Java
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.