Создание приложений PHP с помощью Microsoft Graph и проверки подлинности только для приложений
В этом руководстве описано, как создать консольное приложение PHP, которое использует microsoft API Graph для доступа к данным с помощью проверки подлинности только для приложений. Проверка подлинности только для приложений — это хороший выбор для фоновых служб или приложений, которым требуется доступ к данным для всех пользователей в организации.
Примечание.
Сведения о том, как использовать Microsoft Graph для доступа к данным от имени пользователя, см. в этом руководстве по проверке подлинности пользователя (делегированная).
В этом руководстве описан порядок выполнения перечисленных ниже задач.
Совет
Кроме того, вы можете скачать или клонировать репозиторий GitHub и следовать инструкциям в файле README, чтобы зарегистрировать приложение и настроить проект.
Предварительные требования
Перед началом работы с этим руководством на компьютере разработки должны быть установлены PHP и Composer .
У вас также должна быть рабочая или учебная учетная запись Майкрософт с ролью глобальный администратор. Если у вас нет клиента Microsoft 365, вы можете претендовать на него в рамках Программы разработчиков Microsoft 365. Дополнительные сведения см. в разделе Вопросы и ответы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.
Примечание.
Это руководство было написано с PHP версии 8.1.5 и Composer версии 2.3.5. Действия, описанные в этом руководстве, могут работать с другими версиями, но не были протестированы.
Регистрация приложения на портале
В этом упражнении вы зарегистрируете новое приложение в Azure Active Directory, чтобы включить проверку подлинности только для приложений. Вы можете зарегистрировать приложение с помощью Центра администрирования Azure Active Directory или с помощью пакета SDK Для Microsoft Graph PowerShell.
Регистрация приложения для проверки подлинности только для приложений
В этом разделе описано, как зарегистрировать приложение, которое поддерживает проверку подлинности только для приложений с помощью потока учетных данных клиента.
Откройте браузер, перейдите в Центр администрирования Azure Active Directory и выполните вход с помощью учетной записи глобальный администратор.
Выберите Azure Active Directory на панели навигации слева, затем выберите Регистрация приложений в разделе Управление.
Выберите Новая регистрация. Введите имя приложения, например
Graph App-Only Auth Tutorial
.Задайте для параметра Поддерживаемые типы учетных записейзначение Учетные записи только в этом каталоге организации.
Оставьте поле URI перенаправления пустым.
Нажмите Зарегистрировать. На странице Обзор приложения скопируйте значение идентификатора приложения (клиента) и идентификатора каталога (клиента) и сохраните их. Эти значения потребуются на следующем шаге.
Выберите Разрешения API в разделе Управление.
Удалите разрешение User.Read по умолчанию в разделе Настроенные разрешения , выбрав многоточие (...) в строке и выбрав Удалить разрешение.
Выберите Добавить разрешение, а затем — Microsoft Graph.
Выберите Разрешения приложения.
Выберите User.Read.All, а затем выберите Добавить разрешения.
Выберите Предоставить согласие администратора для..., а затем нажмите кнопку Да , чтобы предоставить согласие администратора для выбранного разрешения.
Выберите Сертификаты и секреты в разделе Управление, а затем выберите Новый секрет клиента.
Введите описание, выберите длительность и нажмите кнопку Добавить.
Скопируйте секрет из столбца Значение . Он понадобится на следующих шагах.
Важно!
Система никогда не покажет секрет клиента повторно, поэтому убедитесь, что вы скопировали его.
Примечание.
Обратите внимание, что в отличие от действий при регистрации для проверки подлинности пользователей в этом разделе вы настроили разрешения Microsoft Graph для регистрации приложения. Это связано с тем, что проверка подлинности только для приложений использует поток учетных данных клиента, который требует настройки разрешений на регистрацию приложения. Дополнительные сведения см. в область по умолчанию.
Создание консольного приложения PHP
Начните с инициализации нового проекта Composer. Откройте интерфейс командной строки (CLI) в каталоге, в котором вы хотите создать проект. Выполните следующую команду.
composer init
Ответьте на запросы. Вы можете принять значения по умолчанию для большинства вопросов, но ответить на n
следующие вопросы:
Would you like to define your dependencies (require) interactively [yes]? n
Would you like to define your dev dependencies (require-dev) interactively [yes]? n
Add PSR-4 autoload mapping? Maps namespace "Microsoft\Graphapponlytutorial" to the entered relative path. [src/, n to skip]: n
Установка зависимостей
Прежде чем переходить дальше, добавьте некоторые дополнительные зависимости, которые будут использоваться позже.
- Пакет SDK Microsoft Graph для PHP для выполнения вызовов к Microsoft Graph.
- vlucas/phpdotenv для чтения переменных среды из ENV-файлов.
Выполните следующую команду в интерфейсе командной строки, чтобы установить зависимости.
composer require microsoft/microsoft-graph vlucas/phpdotenv
Загрузка параметров приложения
В этом разделе вы добавите в проект сведения о регистрации приложения.
Создайте файл в корневом каталоге проекта с именем .env и добавьте следующий код.
CLIENT_ID=YOUR_CLIENT_ID_HERE CLIENT_SECRET=YOUR_CLIENT_SECRET_HERE_IF_USING_APP_ONLY TENANT_ID=YOUR_TENANT_ID_HERE_IF_USING_APP_ONLY
Обновите значения в соответствии со следующей таблицей.
Параметр Значение CLIENT_ID
Идентификатор клиента для регистрации приложения CLIENT_SECRET
Секрет клиента для регистрации приложения TENANT_ID
Идентификатор клиента вашей организации Важно!
Если вы используете систему управления версиями, например Git, то теперь лучше исключить ENV-файл из системы управления версиями, чтобы избежать случайной утечки идентификатора приложения.
Проектирование приложения
В этом разделе вы создадите простое меню на основе консоли.
Создайте файл в корневом каталоге проекта с именем main.php. Добавьте открывающий и закрывающий теги PHP.
<?php ?>
Добавьте следующий код между тегами PHP.
// Enable loading of Composer dependencies require_once realpath(__DIR__ . '/vendor/autoload.php'); require_once 'GraphHelper.php'; print('PHP Graph Tutorial'.PHP_EOL.PHP_EOL); // Load .env file $dotenv = Dotenv\Dotenv::createImmutable(__DIR__); $dotenv->load(); $dotenv->required(['CLIENT_ID', 'CLIENT_SECRET', 'TENANT_ID']); initializeGraph(); $choice = -1; while ($choice != 0) { echo('Please choose one of the following options:'.PHP_EOL); echo('0. Exit'.PHP_EOL); echo('1. Display access token'.PHP_EOL); echo('2. List users'.PHP_EOL); echo('3. Make a Graph call'.PHP_EOL); $choice = (int)readline(''); switch ($choice) { case 1: displayAccessToken(); break; case 2: listUsers(); break; case 3: makeGraphCall(); break; case 0: default: print('Goodbye...'.PHP_EOL); } }
Добавьте следующие методы заполнителей в конец файла перед закрывающим тегом PHP. Вы будете реализовывать их на последующих шагах.
function initializeGraph(): void { // TODO } function displayAccessToken(): void { // TODO } function listUsers(): void { // TODO } function makeGraphCall(): void { // TODO }
Это реализует базовое меню и считывает выбор пользователя из командной строки.
Добавление проверки подлинности только для приложений
В этом разделе вы добавите в приложение проверку подлинности только для приложений. Это необходимо для получения необходимого маркера доступа OAuth для вызова Microsoft Graph.
Настройка клиента Graph для проверки подлинности только для приложений
В этом разделе вы будете PhpLeagueAuthenticationProvider
использовать класс для запроса маркера доступа с помощью потока учетных данных клиента.
Создайте файл в корневом каталоге проекта с именем GraphHelper.php. Добавьте в него указанный ниже код.
<?php class GraphHelper { } ?>
Добавьте следующие
using
инструкции в теги PHP.use Microsoft\Graph\Core\Authentication\GraphPhpLeagueAccessTokenProvider; use Microsoft\Graph\Generated\Models; use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetQueryParameters; use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration; use Microsoft\Graph\GraphServiceClient; use Microsoft\Kiota\Authentication\Oauth\ClientCredentialContext;
Добавьте приведенный ниже код в класс
GraphHelper
.private static string $clientId = ''; private static string $clientSecret = ''; private static string $tenantId = ''; private static ClientCredentialContext $tokenContext; private static GraphServiceClient $appClient; public static function initializeGraphForAppOnlyAuth(): void { GraphHelper::$clientId = $_ENV['CLIENT_ID']; GraphHelper::$clientSecret = $_ENV['CLIENT_SECRET']; GraphHelper::$tenantId = $_ENV['TENANT_ID']; GraphHelper::$tokenContext = new ClientCredentialContext( GraphHelper::$tenantId, GraphHelper::$clientId, GraphHelper::$clientSecret); GraphHelper::$appClient = new GraphServiceClient( GraphHelper::$tokenContext, ['https://graph.microsoft.com/.default']); }
Замените пустую
initializeGraph
функцию в main.php следующим кодом.function initializeGraph(): void { GraphHelper::initializeGraphForAppOnlyAuth(); }
Этот код загружает сведения из ENV-файла и инициализирует два свойства: ClientCredentialContext
объект и GraphServiceClient
объект . Объект ClientCredentialContext
будет использоваться для проверки подлинности запросов, а GraphServiceClient
объект будет использоваться для вызовов Microsoft Graph.
Тестирование потока учетных данных клиента
Затем добавьте код для получения маркера доступа из GraphHelper
.
Добавьте к классу
GraphHelper
следующую функцию:public static function getAppOnlyToken(): string { // Create an access token provider to get the token $tokenProvider = new GraphPhpLeagueAccessTokenProvider(GraphHelper::$tokenContext); return $tokenProvider ->getAuthorizationTokenAsync('https://graph.microsoft.com') ->wait(); }
Замените пустую
displayAccessToken
функцию в main.php следующим кодом.function displayAccessToken(): void { try { $token = GraphHelper::getAppOnlyToken(); print('App-only token: '.$token.PHP_EOL.PHP_EOL); } catch (Exception $e) { print('Error getting access token: '.$e->getMessage().PHP_EOL.PHP_EOL); } }
Выполните сборку и запуск приложения. Введите
1
при появлении запроса на выбор параметра. Приложение отображает маркер доступа, который оно извлекло, используя сведения о проверке подлинности, настроенные ранее в переменных среды.$ php main.php PHP 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 возникают ошибки маркера. Например, убедитесь, что
role
утверждение в маркере содержит ожидаемые области разрешений Microsoft Graph.
Перечисление пользователей
В этом разделе вы добавите возможность вывода списка всех пользователей в Azure Active Directory с помощью проверки подлинности только для приложений.
Добавьте приведенный ниже код в класс
GraphHelper
.public static function getUsers(): Models\UserCollectionResponse { $configuration = new UsersRequestBuilderGetRequestConfiguration(); $configuration->queryParameters = new UsersRequestBuilderGetQueryParameters(); // Only request specific properties $configuration->queryParameters->select = ['displayName','id','mail']; // Sort by display name $configuration->queryParameters->orderby = ['displayName']; // Get at most 25 results $configuration->queryParameters->top = 25; return GraphHelper::$appClient->users()->get($configuration)->wait(); }
Замените пустую
listUsers
функцию в main.php следующим кодом.function listUsers(): void { try { $users = GraphHelper::getUsers(); // Output each user's details foreach ($users->getValue() as $user) { print('User: '.$user->getDisplayName().PHP_EOL); print(' ID: '.$user->getId().PHP_EOL); $email = $user->getMail(); $email = isset($email) ? $email : 'NO EMAIL'; print(' Email: '.$email.PHP_EOL); } $nextLink = $users->getOdataNextLink(); $moreAvailable = isset($nextLink) && $nextLink != '' ? 'True' : 'False'; print(PHP_EOL.'More users available? '.$moreAvailable.PHP_EOL.PHP_EOL); } catch (Exception $e) { print(PHP_EOL.'Error getting users: '.$e->getMessage().PHP_EOL.PHP_EOL); } }
Запустите приложение, войдите в систему и выберите вариант 2, чтобы получить список пользователей.
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
функции.
- Он получает коллекцию пользователей.
- Он использует
queryParameters->select
для запроса определенных свойств - Он использует
queryParameters->top
для ограничения числа возвращенных пользователей - Он использует
queryParameters->orderby
для сортировки ответа
Необязательно: добавление собственного кода
В этом разделе вы добавите в приложение собственные возможности Microsoft Graph. Это может быть фрагмент кода из документации Microsoft Graph, Обозреватель Graph или созданный вами код. Этот раздел является необязательным.
Обновите приложение
Добавьте приведенный ниже код в класс
GraphHelper
.public static function makeGraphCall(): void { // INSERT YOUR CODE HERE }
Замените пустую
makeGraphCall
функцию в main.php следующим кодом.function makeGraphCall(): void { try { GraphHelper::makeGraphCall(); } catch (Exception $e) { print(PHP_EOL.'Error making Graph call'.PHP_EOL.PHP_EOL); } }
Выбор API
Найдите API в Microsoft Graph, который вы хотите попробовать. Например, API создания событий . Вы можете использовать один из примеров из документации по API или создать собственный запрос API.
Настройка разрешений
Ознакомьтесь с разделом Разрешения справочной документации по выбранному API, чтобы узнать, какие методы проверки подлинности поддерживаются. Некоторые API не поддерживают только приложения или личные учетные записи Майкрософт, например.
- Чтобы вызвать API с проверкой подлинности пользователя (если API поддерживает проверку подлинности пользователя (делегированная) проверка подлинности, см. руководство по проверке подлинности пользователя (делегированная).
- Чтобы вызвать API с проверкой подлинности только для приложений (если API поддерживает ее), добавьте необходимый область разрешений в Центре администрирования Azure AD.
Добавление кода
Добавьте код в функцию makeGraphCall
в GraphHelper.php.
Поздравляем!
Вы завершили работу с руководством по PHP Microsoft Graph. Теперь, когда у вас есть рабочее приложение, которое вызывает Microsoft Graph, вы можете экспериментировать и добавлять новые функции.
- Узнайте, как использовать проверку подлинности пользователя (делегированная) с помощью пакета SDK для PHP Для Microsoft Graph.
- Просмотрите обзор Microsoft Graph , чтобы просмотреть все данные, к которым можно получить доступ с помощью Microsoft Graph.
Примеры PHP
Возникла проблема с этим разделом? Если это так, отправьте нам отзыв, чтобы мы исправили этот раздел.