Создание приложений Java с помощью Microsoft Graph и проверки подлинности только для приложений

Статья
Developer (Начальный уровень)
20 мин до завершения

В этом руководстве описано, как создать консольное приложение Java, которое использует API Microsoft Graph для доступа к данным с помощью проверки подлинности только для приложений. Проверка подлинности только для приложений — это хороший выбор для фоновых служб или приложений, которым требуется доступ к данным для всех пользователей в организации.

Примечание.

Сведения о том, как использовать Microsoft Graph для доступа к данным от имени пользователя, см. в этом руководстве по проверке подлинности пользователя (делегированная).

В этом руководстве описан порядок выполнения перечисленных ниже задач.

Перечисление пользователей

Совет

Кроме того, вы можете скачать или клонировать репозиторий GitHub и следовать инструкциям в файле README, чтобы зарегистрировать приложение и настроить проект.

Предварительные условия

Прежде чем приступить к работе с этим руководством, на компьютере разработки должны быть установлены Пакет средств разработки Java SE (JDK) и Gradle .

У вас также должна быть рабочая или учебная учетная запись Майкрософт с ролью глобального администратора. Если у вас нет клиента Microsoft 365, вы можете претендовать на него в рамках Программы разработчиков Microsoft 365. Дополнительные сведения см. в разделе Вопросы и ответы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.

Примечание.

Это руководство было написано с openJDK версии 17.0.2 и Gradle 7.4.2. Действия, описанные в этом руководстве, могут работать с другими версиями, но не были протестированы.

Регистрация приложения на портале

Осталось 19 мин

В этом упражнении вы зарегистрируете новое приложение в Azure Active Directory, чтобы включить проверку подлинности только для приложений. Вы можете зарегистрировать приложение в Центре администрирования Microsoft Entra или с помощью пакета SDK Для Microsoft Graph PowerShell.

Регистрация приложения для проверки подлинности только для приложений

В этом разделе описано, как зарегистрировать приложение, которое поддерживает проверку подлинности только для приложений с помощью потока учетных данных клиента.

Центр администрирования Microsoft Entra
PowerShell

Откройте браузер и перейдите в Центр администрирования Microsoft Entra и войдите с помощью учетной записи глобального администратора.
Выберите Идентификатор Microsoft Entra в области навигации слева, разверните узел Удостоверение, Приложения, а затем выберите Регистрация приложений.
Выберите Новая регистрация. Введите имя приложения, например Graph App-Only Auth Tutorial.
Задайте для параметра Поддерживаемые типы учетных записейзначение Учетные записи только в этом каталоге организации.
Оставьте поле URI перенаправления пустым.
Нажмите Зарегистрировать. На странице Обзор приложения скопируйте значение идентификатора приложения (клиента) и идентификатора каталога (клиента) и сохраните их. Эти значения потребуются на следующем шаге.
Выберите Разрешения API в разделе Управление.
Удалите разрешение User.Read по умолчанию в разделе Настроенные разрешения , выбрав многоточие (...) в строке и выбрав Удалить разрешение.
Выберите Добавить разрешение, а затем — Microsoft Graph.
Выберите Разрешения приложения.
Выберите User.Read.All, а затем выберите Добавить разрешения.
Выберите Предоставить согласие администратора для..., а затем нажмите кнопку Да , чтобы предоставить согласие администратора для выбранного разрешения.
Выберите Сертификаты и секреты в разделе Управление, а затем выберите Новый секрет клиента.
Введите описание, выберите длительность и нажмите кнопку Добавить.
Скопируйте секрет из столбца Значение . Он понадобится на следующих шагах.

Важно!

Система никогда не покажет секрет клиента повторно, поэтому убедитесь, что вы скопировали его.

Чтобы использовать PowerShell, вам потребуется пакет SDK Для Microsoft Graph PowerShell. Если у вас его нет, инструкции по установке см. в разделе Установка пакета SDK Для Microsoft Graph PowerShell .

Создайте файл с именем RegisterAppForAppOnlyAuth.ps1 и добавьте следующий код.

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

Сохраните файл.
Откройте PowerShell и измените текущий каталог на расположение RegisterAppForAppOnlyAuth.ps1.

Выполните следующую команду.

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

Следуйте запросу, чтобы открыть https://microsoft.com/devicelogin в браузере, введите предоставленный код и завершите процесс проверки подлинности.
Скопируйте значения идентификатора клиента, идентификатора клиента и секрета клиента из выходных данных скрипта. Эти значения потребуются на следующем шаге.
```
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
```

Примечание.

Обратите внимание, что в отличие от действий при регистрации для проверки подлинности пользователей в этом разделе вы настроили разрешения Microsoft Graph для регистрации приложения. Это связано с тем, что проверка подлинности только для приложений использует поток учетных данных клиента, который требует настройки разрешений на регистрацию приложения. Дополнительные сведения см . в разделе Область по умолчанию .

Создание консольного приложения Java

Осталось 16 мин

В этом разделе вы создадите базовое консольное приложение Java.

Откройте интерфейс командной строки (CLI) в каталоге, в котором вы хотите создать проект. Выполните следующую команду, чтобы создать проект Gradle.
```
gradle init --dsl groovy --test-framework junit --type java-application --project-name graphapponlytutorial --package graphapponlytutorial
```
После создания проекта убедитесь, что он работает, выполнив следующую команду, чтобы запустить приложение в интерфейсе командной строки.
```
./gradlew --console plain run
```
Если это работает, приложение должно вывести .Hello World.

Установка зависимостей

Прежде чем переходить дальше, добавьте некоторые дополнительные зависимости, которые будут использоваться позже.

Клиентская библиотека удостоверений Azure для Java для проверки подлинности пользователя и получения маркеров доступа.
Пакет SDK Microsoft Graph для Java для выполнения вызовов к Microsoft Graph.

Откройте ./app/build.gradle. Обновите dependencies раздел, чтобы добавить эти зависимости.

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

Добавьте следующий код в конец ./app/build.gradle.
```
run {
    standardInput = System.in
}
```
При следующей сборке проекта Gradle загрузит эти зависимости.

Загрузка параметров приложения

В этом разделе вы добавите в проект сведения о регистрации приложения.

Создайте новый каталог с именем graphapponlytutorial в каталоге ./app/src/main/resources .
Создайте новый файл в каталоге ./app/src/main/resources/graphapponlytutorial с именем oAuth.properties и добавьте в этот файл следующий текст.
```
app.clientId=YOUR_CLIENT_ID_HERE
app.clientSecret=YOUR_CLIENT_SECRET_HERE
app.tenantId=YOUR_TENANT_ID_HERE
```

Обновите значения в соответствии со следующей таблицей.

Параметр	Значение
`app.clientId`	Идентификатор клиента для регистрации приложения
`app.tenantId`	Идентификатор клиента вашей организации
`app.clientSecret`	Секрет клиента

Важно!

Если вы используете систему управления версиями, например Git, то теперь лучше исключить файл oAuth.properties из системы управления версиями, чтобы избежать случайной утечки идентификатора приложения.

Проектирование приложения

В этом разделе вы создадите простое меню на основе консоли.

Откройте ./app/src/main/java/graphapponlytutorial/App.java и добавьте следующие 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;

Замените имеющуюся функцию main указанным ниже кодом.

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

Добавьте следующие методы-заполнители в конец файла. Вы будете реализовывать их на последующих шагах.

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

private static void displayAccessToken() {
    // TODO
}

private static void listUsers() {
    // TODO
}

private static void makeGraphCall() {
    // TODO
}

Это реализует базовое меню и считывает выбор пользователя из командной строки.

Удалите ./app/src/test/java/graphapponlytutorial/AppTest.java.

Добавление проверки подлинности только для приложений

Осталось 11 мин

В этом разделе вы добавите в приложение проверку подлинности только для приложений. Это необходимо для получения необходимого маркера доступа OAuth для вызова Microsoft Graph. На этом шаге вы интегрируете клиентную библиотеку удостоверений Azure для Java в приложение и настроите проверку подлинности для пакета SDK Microsoft Graph для Java.

Настройка клиента Graph для проверки подлинности только для приложений

В этом разделе вы будете ClientSecretCredential использовать класс для запроса маркера доступа с помощью потока учетных данных клиента.

Создайте новый файл в каталоге ./app/src/main/java/graphapponlytutorialс именем Graph.java и добавьте в этот файл следующий код.

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;

Добавьте пустое определение класса Graph .
```
public class Graph {
}
```

Добавьте следующий код в класс 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" });
    }
}

Замените пустую initializeGraph функцию в App.java следующей.

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

Этот код объявляет два частных свойства: ClientSecretCredential объект и GraphServiceClient объект . Функция initializeGraphForAppOnlyAuth создает новый экземпляр ClientSecretCredential, а затем использует его для создания нового экземпляра GraphServiceClient. Каждый раз, когда вызов API выполняется в Microsoft Graph через _appClient, он будет использовать предоставленные учетные данные для получения маркера доступа.

Тестирование ClientSecretCredential

Затем добавьте код для получения маркера доступа из ClientSecretCredential.

Добавьте к классу 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();
}

Замените пустую displayAccessToken функцию в App.java следующей.

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

Выполните сборку и запуск приложения. Введите 1 при появлении запроса на выбор параметра. Приложение отображает маркер доступа.
```
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...
```
Совет

Только для проверки и отладки можно декодировать маркеры доступа пользователей (только для рабочих или учебных учетных записей) с помощью средства синтаксического анализа токенов Майкрософт в сети по адресу https://jwt.ms. Это может быть полезно, если при вызове Microsoft Graph возникают ошибки маркера. Например, убедитесь, что scp утверждение в маркере содержит ожидаемые области разрешений Microsoft Graph.

Перечисление пользователей

Осталось 7 мин

В этом разделе вы добавите возможность вывода списка всех пользователей в Azure Active Directory с помощью проверки подлинности только для приложений.

Откройте Graph.java и добавьте следующую функцию в класс 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" };
    });
}

Замените пустую listUsers функцию в App.java следующей.

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

Запустите приложение, войдите в систему и выберите вариант 4, чтобы получить список пользователей.

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

Описание кода

Рассмотрим код в getUsers функции.

Доступ к коллекции

Этот метод возвращает коллекцию пользователей. Большинство API в Microsoft Graph, возвращающих коллекцию, не возвращают все доступные результаты в одном ответе. Вместо этого они используют разбиение на страницы , чтобы вернуть часть результатов, предоставляя метод для клиентов, чтобы запросить следующую "страницу".

Размеры страниц по умолчанию

API, использующие разбиение на страницы, реализуют размер страницы по умолчанию. Для пользователей значение по умолчанию — 10. Клиенты могут запрашивать больше (или меньше) с помощью параметра запроса $top . В getUsersэто выполняется с помощью top свойства в конфигурации запроса.

Примечание.

Значение, заданное в top , является верхней границей, а не явным числом. API возвращает число пользователей до указанного значения.

Получение последующих страниц

Если на сервере доступно больше результатов, ответы коллекции содержат @odata.nextLink свойство с URL-адресом API для доступа к следующей странице. Клиентская библиотека Java предоставляет этот метод в getOdataNextLink качестве метода для объектов ответа коллекции. Если этот метод возвращает значение, отличное от NULL, доступны дополнительные результаты.

Сортировка коллекций

Функция использует orderBy свойство в конфигурации запроса для запроса результатов, отсортированных по отображаемым именам пользователей. При этом параметр запроса $orderby добавляется в вызов API.

Необязательно: добавление собственного кода

Осталось 5 мин

В этом разделе вы добавите в приложение собственные возможности Microsoft Graph. Это может быть фрагмент кода из документации Microsoft Graph или обозревателя Graph или созданный вами код. Этот раздел является необязательным.

Обновите приложение

Откройте Graph.java и добавьте следующую функцию в класс Graph .
```
public static void makeGraphCall() {
    // INSERT YOUR CODE HERE
}
```

Замените пустую MakeGraphCallAsync функцию в App.java следующей.

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

Выбор API

Найдите API в Microsoft Graph, который вы хотите попробовать. Например, API создания событий . Вы можете использовать один из примеров в документации по API или настроить запрос API в Graph Explorer и использовать созданный фрагмент кода.

Настройка разрешений

Ознакомьтесь с разделом Разрешения справочной документации по выбранному API, чтобы узнать, какие методы проверки подлинности поддерживаются. Некоторые API не поддерживают только приложения или личные учетные записи Майкрософт, например.

Чтобы вызвать API с проверкой подлинности пользователя (если API поддерживает проверку подлинности пользователя (делегированная) проверка подлинности, см. руководство по проверке подлинности пользователя (делегированная).
Чтобы вызвать API с проверкой подлинности только для приложений (если API поддерживает ее), добавьте требуемую область разрешений в Центре администрирования Azure AD.

Добавление кода

Скопируйте код в функцию makeGraphCallAsyncв Graph.java. Если вы копируете фрагмент из документации или обозревателя Graph, обязательно переименуйте GraphServiceClient_appClientв .

Поделиться через

Создание приложений Java с помощью Microsoft Graph и проверки подлинности только для приложений

Предварительные условия

Регистрация приложения на портале

Регистрация приложения для проверки подлинности только для приложений

Создание консольного приложения Java

Установка зависимостей

Загрузка параметров приложения

Проектирование приложения

Добавление проверки подлинности только для приложений

Настройка клиента Graph для проверки подлинности только для приложений

Тестирование ClientSecretCredential

Перечисление пользователей

Описание кода

Доступ к коллекции

Размеры страниц по умолчанию

Получение последующих страниц

Сортировка коллекций

Необязательно: добавление собственного кода

Обновите приложение

Выбор API

Настройка разрешений

Добавление кода

Поздравляем!

Примеры Java