Compilación de aplicaciones Java con Microsoft Graph y autenticación solo de aplicaciones

Artículo
Developer (Principiante)
Tiempo para finalizar: 20 minutos

En este tutorial se explica cómo crear una aplicación de consola de Java que use Microsoft Graph API para acceder a los datos mediante la autenticación de solo aplicación. La autenticación solo de aplicación es una buena opción para los servicios en segundo plano o las aplicaciones que necesitan acceder a los datos de todos los usuarios de una organización.

Nota:

Para obtener información sobre cómo usar Microsoft Graph para acceder a datos en nombre de un usuario, consulte este tutorial de autenticación de usuario (delegado).

En este tutorial, aprenderá a:

Enumerar usuarios

Sugerencia

Como alternativa a seguir este tutorial, puede descargar o clonar el repositorio de GitHub y seguir las instrucciones de README para registrar una aplicación y configurar el proyecto.

Requisitos previos

Antes de iniciar este tutorial, debe tener instalados java SE Development Kit (JDK) y Gradle en la máquina de desarrollo.

También debe tener una cuenta profesional o educativa de Microsoft con el rol de administrador global. Si no tiene un inquilino de Microsoft 365, puede calificar para uno a través del Programa para desarrolladores de Microsoft 365; Para obtener más información, consulte las preguntas más frecuentes. Como alternativa, puede registrarse para obtener una evaluación gratuita de 1 mes o comprar un plan de Microsoft 365.

Nota:

Este tutorial se escribió con OpenJDK versión 17.0.2 y Gradle 7.4.2. Los pasos de esta guía pueden funcionar con otras versiones, pero no se han probado.

Registrar la aplicación en el portal

19 minutos restantes

En este ejercicio registrará una nueva aplicación en Azure Active Directory para habilitar la autenticación de solo aplicación. Puede registrar una aplicación mediante el Centro de administración de Microsoft Entra o mediante el SDK de PowerShell de Microsoft Graph.

Registro de la aplicación para la autenticación de solo aplicación

En esta sección registrará una aplicación que admita la autenticación de solo aplicación mediante el flujo de credenciales de cliente.

Centro de administración de Microsoft Entra
PowerShell

Abra un explorador y vaya al Centro de administración de Microsoft Entra e inicie sesión con una cuenta de administrador global.
Seleccione Microsoft Entra ID en el panel de navegación izquierdo, expanda Identidad, aplicaciones y registros de aplicaciones.
Seleccione Nuevo registro. Escriba un nombre para la aplicación, por ejemplo, Graph App-Only Auth Tutorial.
Establezca Tipos de cuenta admitidosen Solo cuentas en este directorio organizativo.
Deje URI de redireccionamiento vacía.
Seleccione Registrar. En la página Información general de la aplicación, copie el valor del identificador de aplicación (cliente) y del identificador de directorio (inquilino) y guárdelos, necesitará estos valores en el paso siguiente.
Seleccione Permisos de las API en Administrar.
Quite el permiso User.Read predeterminado en Permisos configurados ; para ello, seleccione los puntos suspensivos (...) de su fila y seleccione Quitar permiso.
Seleccione Agregar un permiso y, a continuación, Microsoft Graph.
Seleccione Permisos de aplicación.
Seleccione User.Read.All y, a continuación, seleccione Agregar permisos.
Seleccione Conceder consentimiento de administrador para...y, a continuación, seleccione Sí para proporcionar el consentimiento del administrador para el permiso seleccionado.
Seleccione Certificados y secretos en Administrar y, a continuación, seleccione Nuevo secreto de cliente.
Escriba una descripción, elija una duración y seleccione Agregar.
Copie el secreto de la columna Valor ; lo necesitará en los pasos siguientes.

Importante

El secreto de cliente no se vuelve a mostrar, así que asegúrese de copiarlo en este momento.

Para usar PowerShell, necesitará el SDK de PowerShell de Microsoft Graph. Si no lo tiene, consulte Instalación del SDK de PowerShell de Microsoft Graph para obtener instrucciones de instalación.

Cree un nuevo archivo denominado RegisterAppForAppOnlyAuth.ps1 y agregue el código siguiente.

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"
}

Guarde el archivo.
Abra PowerShell y cambie el directorio actual a la ubicación de RegisterAppForAppOnlyAuth.ps1.

Ejecuta el siguiente comando.

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

Siga el símbolo del sistema para abrir https://microsoft.com/devicelogin en un explorador, escriba el código proporcionado y complete el proceso de autenticación.

Copie los valores de Id. de cliente, Id. de inquilino y Secreto de cliente de la salida del script. Necesitará estos valores en el paso siguiente.

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

Nota:

Tenga en cuenta que, a diferencia de los pasos al registrarse para la autenticación de usuario, en esta sección configuró los permisos de Microsoft Graph en el registro de la aplicación. Esto se debe a que la autenticación de solo aplicación usa el flujo de credenciales de cliente, lo que requiere que los permisos se configuren en el registro de la aplicación. Consulte El ámbito .default para obtener más información.

Crear una aplicación de consola de Java

16 minutos restantes

En esta sección creará una aplicación de consola básica de Java.

Abra la interfaz de línea de comandos (CLI) en un directorio donde quiera crear el proyecto. Ejecute el siguiente comando para crear un nuevo proyecto de Gradle.
```
gradle init --dsl groovy --test-framework junit --type java-application --project-name graphapponlytutorial --package graphapponlytutorial
```
Una vez creado el proyecto, compruebe que funciona ejecutando el siguiente comando para ejecutar la aplicación en la CLI.
```
./gradlew --console plain run
```
Si funciona, la aplicación debe generar Hello World..

Instalar dependencias

Antes de continuar, agregue algunas dependencias adicionales que usará más adelante.

Biblioteca cliente de Identidad de Azure para Java para autenticar al usuario y adquirir tokens de acceso.
SDK de Microsoft Graph para Java para realizar llamadas a Microsoft Graph.

Abra ./app/build.gradle. Actualice la dependencies sección para agregar esas dependencias.

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'
}

Agregue lo siguiente al final de ./app/build.gradle.
```
run {
    standardInput = System.in
}
```
La próxima vez que compile el proyecto, Gradle descargará esas dependencias.

Cargar la configuración de la aplicación

En esta sección agregará los detalles del registro de la aplicación al proyecto.

Cree un nuevo directorio denominado graphapponlytutorial en el directorio ./app/src/main/resources .
Cree un nuevo archivo en el directorio ./app/src/main/resources/graphapponlytutorial denominado oAuth.properties y agregue el texto siguiente en ese archivo.
```
app.clientId=YOUR_CLIENT_ID_HERE
app.clientSecret=YOUR_CLIENT_SECRET_HERE
app.tenantId=YOUR_TENANT_ID_HERE
```

Actualice los valores según la tabla siguiente.

Configuración	Valor
`app.clientId`	El identificador de cliente del registro de la aplicación
`app.tenantId`	El identificador de inquilino de la organización
`app.clientSecret`	El secreto de cliente

Importante

Si usa el control de código fuente como git, ahora sería un buen momento para excluir el archivo oAuth.properties del control de código fuente para evitar la pérdida accidental del identificador de aplicación.

Diseñar la aplicación

En esta sección creará un menú simple basado en consola.

Abra ./app/src/main/java/graphapponlytutorial/App.java y agregue las siguientes import instrucciones.

package graphapponlytutorial;

import java.io.IOException;
import java.util.InputMismatchException;
import java.util.Properties;
import java.util.Scanner;

import com.microsoft.graph.models.User;

Reemplace la función main existente por lo siguiente.

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();
}

Agregue los siguientes métodos de marcador de posición al final del archivo. Los implementará en pasos posteriores.

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

private static void displayAccessToken() {
    // TODO
}

private static void listUsers() {
    // TODO
}

private static void makeGraphCall() {
    // TODO
}

Esto implementa un menú básico y lee la elección del usuario desde la línea de comandos.

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

Agregar autenticación de solo aplicación

11 minutos restantes

En esta sección agregará la autenticación de solo aplicación a la aplicación. Esto es necesario para obtener el token de acceso de OAuth necesario para llamar a Microsoft Graph. En este paso, integrará la biblioteca cliente de Azure Identity para Java en la aplicación y configurará la autenticación para el SDK de Microsoft Graph para Java.

Configuración del cliente de Graph para la autenticación solo de la aplicación

En esta sección usará la ClientSecretCredential clase para solicitar un token de acceso mediante el flujo de credenciales de cliente.

Cree un nuevo archivo en el directorio ./app/src/main/java/graphapponlytutorial denominado Graph.java y agregue el código siguiente a ese archivo.

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;

Agregue una definición de clase graph vacía.
```
public class Graph {
}
```

Agregue el código siguiente a la clase 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" });
    }
}

Reemplace la función vacía initializeGraph en App.java por lo siguiente.

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 dos propiedades privadas, un ClientSecretCredential objeto y un GraphServiceClient objeto . La initializeGraphForAppOnlyAuth función crea una nueva instancia de ClientSecretCredentialy, a continuación, usa esa instancia para crear una nueva instancia de GraphServiceClient. Cada vez que se realiza una llamada API a Microsoft Graph a través de _appClient, usará la credencial proporcionada para obtener un token de acceso.

Prueba de ClientSecretCredential

A continuación, agregue código para obtener un token de acceso de ClientSecretCredential.

Agregue la siguiente función a la clase 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();
}

Reemplace la función vacía displayAccessToken en App.java por lo siguiente.

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());
    }
}

Compile y ejecute la aplicación. Escriba 1 cuando se le solicite una opción. La aplicación muestra un token de acceso.
```
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...
```
Sugerencia

Solo con fines de validación y depuración, puede descodificar tokens de acceso de usuario (solo para cuentas profesionales o educativas) mediante el analizador de tokens en línea de Microsoft en https://jwt.ms. Esto puede ser útil si encuentra errores de token al llamar a Microsoft Graph. Por ejemplo, comprobar que la scp notificación del token contiene los ámbitos de permiso de Microsoft Graph esperados.

List users

7 minutos restantes

En esta sección agregará la capacidad de enumerar todos los usuarios de Azure Active Directory mediante la autenticación de solo aplicación.

Abra Graph.java y agregue la siguiente función a la clase 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" };
    });
}

Reemplace la función vacía listUsers en App.java por lo siguiente.

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());
    }
}

Ejecute la aplicación, inicie sesión y elija la opción 4 para enumerar a los usuarios.

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

Tenga en cuenta el código de la getUsers función .

Acceso a una colección

Este método devuelve una colección de usuarios. La mayoría de las API de Microsoft Graph que devuelven una colección no devuelven todos los resultados disponibles en una sola respuesta. En su lugar, usan la paginación para devolver una parte de los resultados al tiempo que proporcionan un método para que los clientes soliciten la siguiente "página".

Tamaños de página predeterminados

Las API que usan la paginación implementan un tamaño de página predeterminado. Para los usuarios, el valor predeterminado es 10. Los clientes pueden solicitar más (o menos) mediante el parámetro de consulta $top . En getUsers, esto se logra con la top propiedad en la configuración de la solicitud.

Nota:

El valor establecido en top es un límite superior, no un número explícito. La API devuelve un número de usuarios hasta el valor especificado.

Obtención de páginas posteriores

Si hay más resultados disponibles en el servidor, las respuestas de colección incluyen una @odata.nextLink propiedad con una dirección URL de API para acceder a la página siguiente. La biblioteca cliente de Java expone esto como el método en los getOdataNextLink objetos de respuesta de colección. Si este método devuelve valores no NULL, hay más resultados disponibles.

Ordenar colecciones

La función usa la orderBy propiedad en la configuración de la solicitud para solicitar resultados ordenados por los nombres para mostrar de los usuarios. Esto agrega el parámetro de consulta $orderby a la llamada API.

Opcional: agregue su propio código

5 minutos restantes

En esta sección agregará sus propias funcionalidades de Microsoft Graph a la aplicación. Podría tratarse de un fragmento de código de la documentación de Microsoft Graph o del Explorador de Graph, o código que haya creado. Esta sección es opcional.

Actualizar la aplicación

Abra Graph.java y agregue la siguiente función a la clase Graph .

public static void makeGraphCall() {
    // INSERT YOUR CODE HERE
}

Reemplace la función vacía MakeGraphCallAsync en App.java por lo siguiente.

private static void makeGraphCall() {
    try {
        Graph.makeGraphCall();
    } catch (Exception e) {
        System.out.println("Error making Graph call");
        System.out.println(e.getMessage());
    }
}

Elección de una API

Busque una API en Microsoft Graph que le gustaría probar. Por ejemplo, create event API. Puede usar uno de los ejemplos de la documentación de la API, o puede personalizar una solicitud de API en el Explorador de Graph y usar el fragmento de código generado.

Configurar permisos

Compruebe la sección Permisos de la documentación de referencia de la API elegida para ver qué métodos de autenticación se admiten. Algunas API no admiten solo aplicaciones ni cuentas personales de Microsoft, por ejemplo.

Para llamar a una API con autenticación de usuario (si la API admite la autenticación de usuario (delegado), consulte el tutorial de autenticación de usuario (delegado ).
Para llamar a una API con autenticación de solo aplicación (si la API la admite), agregue el ámbito de permisos necesario en el Centro de administración de Azure AD.

Agregar el código

Copie el código en la makeGraphCallAsync función de Graph.java. Si va a copiar un fragmento de código de la documentación o del Explorador de Graph, asegúrese de cambiar el GraphServiceClient nombre a _appClient.

Compartir a través de

Compilación de aplicaciones Java con Microsoft Graph y autenticación solo de aplicaciones

Requisitos previos

Registrar la aplicación en el portal

Registro de la aplicación para la autenticación de solo aplicación

Crear una aplicación de consola de Java

Instalar dependencias

Cargar la configuración de la aplicación

Diseñar la aplicación

Agregar autenticación de solo aplicación

Configuración del cliente de Graph para la autenticación solo de la aplicación

Prueba de ClientSecretCredential

List users

Código explicado

Acceso a una colección

Tamaños de página predeterminados

Obtención de páginas posteriores

Ordenar colecciones

Opcional: agregue su propio código

Actualizar la aplicación

Elección de una API

Configurar permisos

Agregar el código

¡Enhorabuena!

Ejemplos de Java