Criar aplicações Java com o Microsoft Graph e a autenticação apenas de aplicações

Artigo
Developer (Iniciante)
20 minutos para concluir

Este tutorial ensina-o a criar uma aplicação de consola Java que utiliza a Microsoft Graph API para aceder a dados através da autenticação apenas de aplicações. A autenticação apenas de aplicações é uma boa opção para serviços em segundo plano ou aplicações que precisam de aceder aos dados de todos os utilizadores numa organização.

Observação

Para saber como utilizar o Microsoft Graph para aceder a dados em nome de um utilizador, veja este tutorial de autenticação de utilizador (delegado).

Neste tutorial, você vai:

Listar usuários

Dica

Como alternativa a seguir este tutorial, pode transferir ou clonar o repositório do GitHub e seguir as instruções no README para registar uma aplicação e configurar o projeto.

Pré-requisitos

Antes de iniciar este tutorial, deve ter o Java SE Development Kit (JDK) e o Gradle instalados no seu computador de desenvolvimento.

Também deve ter uma conta escolar ou profissional da Microsoft com a função de Administrador global. Se não tiver um inquilino do Microsoft 365, poderá qualificar-se para um através do Programa para Programadores do Microsoft 365; para obter detalhes, veja as FAQ. Em alternativa, pode inscrever-se numa avaliação gratuita de um mês ou comprar um plano do Microsoft 365.

Observação

Este tutorial foi escrito com a versão 17.0.2 e Gradle 7.4.2 do OpenJDK. Os passos neste guia podem funcionar com outras versões, mas isso não foi testado.

Registrar o aplicativo no portal

19 minutos restantes

Neste exercício, irá registar uma nova aplicação no Azure Active Directory para ativar a autenticação apenas de aplicações. Pode registar uma aplicação através do centro de administração do Microsoft Entra ou através do SDK do PowerShell do Microsoft Graph.

Registar aplicação para autenticação apenas de aplicação

Nesta secção, irá registar uma aplicação que suporta a autenticação apenas da aplicação através do fluxo de credenciais de cliente.

Centro de administração do Microsoft Entra
PowerShell

Abra um browser e navegue para o centro de administração do Microsoft Entra e inicie sessão com uma conta de Administrador global.
Selecione Microsoft Entra ID no painel de navegação esquerdo, expanda Identidade, expanda Aplicações e, em seguida, selecione Registos de aplicações.
Selecione Novo registro. Introduza um nome para a sua aplicação, por exemplo, Graph App-Only Auth Tutorial.
Defina Tipos de conta suportados como Contas apenas neste diretório organizacional.
Deixe o URI de Redirecionamento vazio.
Selecione Registrar. Na página Descrição Geral da aplicação, copie o valor do ID da Aplicação (cliente) e do ID do Diretório (inquilino) e guarde-os, irá precisar destes valores no próximo passo.
Selecione Permissões de API em Gerenciar.
Remova a permissão User.Read predefinida em Permissões configuradas ao selecionar as reticências (...) na respetiva linha e selecionar 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, em seguida, selecione Sim para dar consentimento do administrador para a permissão selecionada.
Selecione Certificados e segredos em Gerir e, em seguida, selecione Novo segredo do cliente.
Introduza uma descrição, escolha uma duração e selecione Adicionar.
Copie o segredo da coluna Valor . Irá precisar dele nos próximos passos.

Importante

Este segredo do cliente nunca é mostrado novamente, portanto, certifique-se de copiá-lo agora.

Para utilizar o PowerShell, precisará do SDK do PowerShell do Microsoft Graph. Se não o tiver, veja Instalar o SDK do PowerShell do Microsoft Graph para obter instruções de instalação.

Crie um novo ficheiro com o nomeRegisterAppForAppOnlyAuth.ps1 e adicione o seguinte código.

param(
  [Parameter(Mandatory=$true,
  HelpMessage="The friendly name of the app registration")]
  [String]
  $AppName,

  [Parameter(Mandatory=$true,
  HelpMessage="The application permission scopes to configure on the app registration")]
  [String[]]
  $GraphScopes,

  [Parameter(Mandatory=$false)]
  [Switch]
  $StayConnected = $false
)

$graphAppId = "00000003-0000-0000-c000-000000000000"

# Requires an admin
Connect-MgGraph -Scopes "Application.ReadWrite.All AppRoleAssignment.ReadWrite.All User.Read" -UseDeviceAuthentication -ErrorAction Stop

# Get context for access to tenant ID
$context = Get-MgContext -ErrorAction Stop
$authTenant = $context.TenantId

# Create app registration
$appRegistration = New-MgApplication -DisplayName $AppName -SignInAudience "AzureADMyOrg" -ErrorAction Stop
Write-Host -ForegroundColor Cyan "App registration created with app ID" $appRegistration.AppId

# Create corresponding service principal
$appServicePrincipal = New-MgServicePrincipal -AppId $appRegistration.AppId -ErrorAction SilentlyContinue `
  -ErrorVariable SPError
if ($SPError)
{
  Write-Host -ForegroundColor Red "A service principal for the app could not be created."
  Write-Host -ForegroundColor Red $SPError
  Exit
}

Write-Host -ForegroundColor Cyan "Service principal created"

# Lookup available Graph application permissions
$graphServicePrincipal = Get-MgServicePrincipal -Filter ("appId eq '" + $graphAppId + "'") -ErrorAction Stop
$graphAppPermissions = $graphServicePrincipal.AppRoles

$resourceAccess = @()

foreach($scope in $GraphScopes)
{
  $permission = $graphAppPermissions | Where-Object { $_.Value -eq $scope }
  if ($permission)
  {
    $resourceAccess += @{ Id =  $permission.Id; Type = "Role"}
  }
  else
  {
    Write-Host -ForegroundColor Red "Invalid scope:" $scope
    Exit
  }
}

# Add the permissions to required resource access
Update-MgApplication -ApplicationId $appRegistration.Id -RequiredResourceAccess `
 @{ ResourceAppId = $graphAppId; ResourceAccess = $resourceAccess } -ErrorAction Stop
Write-Host -ForegroundColor Cyan "Added application permissions to app registration"

# Add admin consent
foreach ($appRole in $resourceAccess)
{
  New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $appServicePrincipal.Id `
   -PrincipalId $appServicePrincipal.Id -ResourceId $graphServicePrincipal.Id `
   -AppRoleId $appRole.Id -ErrorAction SilentlyContinue -ErrorVariable SPError | Out-Null
  if ($SPError)
  {
    Write-Host -ForegroundColor Red "Admin consent for one of the requested scopes could not be added."
    Write-Host -ForegroundColor Red $SPError
    Exit
  }
}
Write-Host -ForegroundColor Cyan "Added admin consent"

# Add a client secret
$clientSecret = Add-MgApplicationPassword -ApplicationId $appRegistration.Id -PasswordCredential `
 @{ DisplayName = "Added by PowerShell" } -ErrorAction Stop

Write-Host
Write-Host -ForegroundColor Green "SUCCESS"
Write-Host -ForegroundColor Cyan -NoNewline "Client ID: "
Write-Host -ForegroundColor Yellow $appRegistration.AppId
Write-Host -ForegroundColor Cyan -NoNewline "Tenant ID: "
Write-Host -ForegroundColor Yellow $authTenant
Write-Host -ForegroundColor Cyan -NoNewline "Client secret: "
Write-Host -ForegroundColor Yellow $clientSecret.SecretText
Write-Host -ForegroundColor Cyan -NoNewline "Secret expires: "
Write-Host -ForegroundColor Yellow $clientSecret.EndDateTime

if ($StayConnected -eq $false)
{
  Disconnect-MgGraph | Out-Null
  Write-Host "Disconnected from Microsoft Graph"
}
else
{
  Write-Host
  Write-Host -ForegroundColor Yellow `
   "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

Salve o arquivo.
Abra o PowerShell e altere o diretório atual para a localização de RegisterAppForAppOnlyAuth.ps1.

Execute o seguinte comando:

.\RegisterAppForAppOnlyAuth.ps1 -AppName "Graph App-Only Auth Tutorial" -GraphScopes "User.Read.All"

Siga o pedido para abrir https://microsoft.com/devicelogin num browser, introduza o código fornecido e conclua o processo de autenticação.

Copie os valores ID de Cliente, ID do Inquilino e Segredo do cliente do resultado do script. Irá precisar destes valores no próximo passo.

SUCCESS
Client ID: ae2386e6-799e-4f75-b191-855d7e691c75
Tenant ID: 5927c10a-91bd-4408-9c70-c50bce922b71
Client secret: ...
Secret expires: 10/28/2024 5:01:45 PM

Observação

Repare que, ao contrário dos passos ao registar para autenticação de utilizador, nesta secção, configurou as permissões do Microsoft Graph no registo de aplicações. Isto deve-se ao facto de a autenticação apenas da aplicação utilizar o fluxo de credenciais do cliente, o que requer que as permissões sejam configuradas no registo de aplicações. Veja O âmbito .default para obter detalhes.

Criar um aplicativo de console Java

16 minutos restantes

Nesta secção, irá criar uma aplicação de consola Java básica.

Abra a interface de linha de comandos (CLI) num diretório onde pretende criar o projeto. Execute o seguinte comando para criar um novo projeto gradle.
```
gradle init --dsl groovy --test-framework junit --type java-application --project-name graphapponlytutorial --package graphapponlytutorial
```
Assim que o projeto for criado, verifique se funciona ao executar o seguinte comando para executar a aplicação na CLI.
```
./gradlew --console plain run
```
Se funcionar, a aplicação deverá produzir Hello World..

Instalar dependências

Antes de continuar, adicione algumas dependências adicionais que irá utilizar mais tarde.

Biblioteca de cliente da Identidade do Azure para Java para autenticar o utilizador 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 secçã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 fim de ./app/build.gradle.
```
run {
    standardInput = System.in
}
```
Da próxima vez que criar o projeto, o Gradle irá transferir essas dependências.

Carregar as definições da aplicação

Nesta secção, irá adicionar os detalhes do registo da aplicação ao projeto.

Crie um novo diretório com o nome graphapponlytutorial no diretório ./app/src/main/resources .
Crie um novo ficheiro no diretório ./app/src/main/resources/graphapponlytutorial com o nome oAuth.properties e adicione o seguinte texto nesse ficheiro.
```
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 seguinte.

Configuração Valor

app.clientId O ID de cliente do registo de aplicações

app.tenantId O ID de inquilino da sua organização

app.clientSecret O segredo do cliente

Importante

Se estiver a utilizar o controlo de origem, como o git, agora seria uma boa altura para excluir o ficheiro oAuth.properties do controlo de origem para evitar fugas inadvertidas do ID da aplicação.

Configuração	Valor
`app.clientId`	O ID de cliente do registo de aplicações
`app.tenantId`	O ID de inquilino da sua organização
`app.clientSecret`	O segredo do cliente

Design do aplicativo

Nesta secção, irá criar um menu simples baseado na consola.

Abra ./app/src/main/java/graphapponlytutorial/App.java e adicione as seguintes import instruções.

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 marcador de posição no final do ficheiro. Irá implementá-los em passos posteriores.

private static void initializeGraph(Properties properties) {
    // TODO
}

private static void displayAccessToken() {
    // TODO
}

private static void listUsers() {
    // TODO
}

private static void makeGraphCall() {
    // TODO
}

Esta ação implementa um menu básico e lê a escolha do utilizador a partir da linha de comandos.

Elimine ./app/src/test/java/graphapponlytutorial/AppTest.java.

Adicionar autenticação apenas de aplicação

11 minutos restantes

Nesta secção, irá adicionar a autenticação apenas de aplicação à aplicação. Isto é necessário para obter o token de acesso OAuth necessário para chamar o Microsoft Graph. Neste passo, irá integrar a biblioteca de cliente da Identidade do Azure para Java na aplicação e configurar a autenticação para o SDK do Microsoft Graph para Java.

Configurar o cliente do Graph para autenticação apenas de aplicações

Nesta secção, irá utilizar a ClientSecretCredential classe para pedir um token de acesso com o fluxo de credenciais de cliente.

Crie um novo ficheiro no diretório ./app/src/main/java/graphapponlytutorial com o nome Graph.java e adicione o seguinte código a esse ficheiro.

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 seguinte código à 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 empty 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());
    }
}

Este código declara duas propriedades privadas, um ClientSecretCredential objeto e um GraphServiceClient objeto. A initializeGraphForAppOnlyAuth função cria uma nova instância de ClientSecretCredentiale, em seguida, utiliza essa instância para criar uma nova instância de GraphServiceClient. Sempre que for efetuada uma chamada à API para o Microsoft Graph através do _appClient, utilizará a credencial fornecida para obter um token de acesso.

Testar o ClientSecretCredential

Em seguida, adicione código para obter um token de acesso a ClientSecretCredentialpartir do .

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 empty 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 a aplicação. Introduza 1 quando lhe for pedida uma opção. A aplicação apresenta 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

Apenas para fins de validação e depuração, pode descodificar tokens de acesso de utilizador (apenas para contas escolares ou profissionais) com o analisador de tokens online da Microsoft em https://jwt.ms. Isto pode ser útil se encontrar erros de token ao chamar o Microsoft Graph. Por exemplo, verificar se a scp afirmação no token contém os âmbitos de permissão esperados do Microsoft Graph.

Listar usuários

7 minutos restantes

Nesta secção, irá adicionar a capacidade de listar todos os utilizadores no Azure Active Directory através da autenticação apenas de aplicações.

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 empty 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 a aplicação, inicie sessão e selecione a opção 4 para listar os utilizadores.

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 .

Aceder a uma coleção

Este método devolve uma coleção de utilizadores. A maioria das APIs no Microsoft Graph que devolvem uma coleção não devolvem todos os resultados disponíveis numa única resposta. Em vez disso, utilizam a paginação para devolver uma parte dos resultados, ao mesmo tempo que fornecem um método para os clientes solicitarem a "página" seguinte.

Tamanhos de página predefinidos

As APIs que utilizam a paginação implementam um tamanho de página predefinido. Para os utilizadores, o valor predefinido é 10. Os clientes podem pedir mais (ou menos) através do parâmetro de consulta $top . No getUsers, isto é conseguido com a top propriedade na configuração do pedido.

Observação

O valor definido em top é um limite superior e não um número explícito. A API devolve um número de utilizadores até ao valor especificado.

Obter páginas subsequentes

Se existirem mais resultados disponíveis no servidor, as respostas da coleção incluem uma @odata.nextLink propriedade com um URL de API para aceder à página seguinte. A biblioteca de cliente Java expõe-no como o getOdataNextLink método nos objetos de resposta da coleção. Se este método devolver não nulo, existem mais resultados disponíveis.

Classificando coleções

A função utiliza a orderBy propriedade na configuração do pedido para pedir resultados ordenados pelos nomes a apresentar dos utilizadores. Esta ação adiciona o parâmetro de consulta $orderby à chamada à API.

Opcional: adicionar o seu próprio código

5 minutos restantes

Nesta secção, irá adicionar as suas próprias capacidades do Microsoft Graph à aplicação. Pode ser um fragmento de código da documentação do Microsoft Graph ou do Graph Explorer ou código que criou. Esta secçã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 empty 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

Localize uma API no Microsoft Graph que gostaria de experimentar. Por exemplo, a API Criar evento . Pode utilizar um dos exemplos na documentação da API ou personalizar um pedido de API no Graph Explorer e utilizar o fragmento gerado.

Configurar as permissões

Verifique a secção Permissões da documentação de referência da API escolhida para ver que métodos de autenticação são suportados. Algumas APIs não suportam apenas aplicações ou contas Microsoft pessoais, por exemplo.

Para chamar uma API com autenticação de utilizador (se a API suportar a autenticação de utilizador (delegado), veja o tutorial de autenticação do utilizador (delegado ).
Para chamar uma API com autenticação apenas de aplicação (se a API a suportar), adicione o âmbito de permissão necessário no centro de administração do Azure AD.

Adicionar o código

Copie o código para a makeGraphCallAsync função no Graph.java. Se estiver a copiar um fragmento da documentação ou do Graph Explorer, certifique-se de que muda o GraphServiceClient nome para _appClient.

Compartilhar via

Criar aplicações Java com o Microsoft Graph e a autenticação apenas de aplicações

Pré-requisitos

Registrar o aplicativo no portal

Registar aplicação para autenticação apenas de aplicação

Criar um aplicativo de console Java

Instalar dependências

Carregar as definições da aplicação

Design do aplicativo

Adicionar autenticação apenas de aplicação

Configurar o cliente do Graph para autenticação apenas de aplicações

Testar o ClientSecretCredential

Listar usuários

Código explicado

Aceder a uma coleção

Tamanhos de página predefinidos

Obter páginas subsequentes

Classificando coleções

Opcional: adicionar o seu próprio código

Atualizar o aplicativo

Escolher uma API

Configurar as permissões

Adicionar o código

Parabéns!

Exemplos de Java