Создание приложений TypeScript с помощью Microsoft Graph и проверки подлинности только для приложений
В этом руководстве описано, как создать консольное приложение TypeScript, которое использует API Microsoft Graph для доступа к данным с помощью проверки подлинности только для приложений. Проверка подлинности только для приложений — это хороший выбор для фоновых служб или приложений, которым требуется доступ к данным для всех пользователей в организации.
Примечание.
Сведения о том, как использовать Microsoft Graph для доступа к данным от имени пользователя, см. в этом руководстве по проверке подлинности пользователя (делегированная).
В этом руководстве описан порядок выполнения перечисленных ниже задач.
Совет
Кроме того, вы можете скачать или клонировать репозиторий GitHub и следовать инструкциям в файле README, чтобы зарегистрировать приложение и настроить проект.
Предварительные условия
Прежде чем приступить к работе с этим руководством, необходимо установить Node.js на компьютере разработки.
У вас также должна быть рабочая или учебная учетная запись Майкрософт с ролью глобального администратора. Если у вас нет клиента Microsoft 365, вы можете претендовать на него в рамках Программы разработчиков Microsoft 365. Дополнительные сведения см. в разделе Вопросы и ответы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.
Примечание.
Это руководство было написано с Node.js версии 16.14.2. Действия, описанные в этом руководстве, могут работать с другими версиями, но не были протестированы.
Регистрация приложения на портале
В этом упражнении вы зарегистрируете новое приложение в Azure Active Directory, чтобы включить проверку подлинности только для приложений. Вы можете зарегистрировать приложение в Центре администрирования Microsoft Entra или с помощью пакета SDK Для Microsoft Graph PowerShell.
Регистрация приложения для проверки подлинности только для приложений
В этом разделе описано, как зарегистрировать приложение, которое поддерживает проверку подлинности только для приложений с помощью потока учетных данных клиента.
Откройте браузер и перейдите в Центр администрирования Microsoft Entra и войдите с помощью учетной записи глобального администратора.
Выберите Идентификатор Microsoft Entra в области навигации слева, разверните узел Удостоверение, Приложения, а затем выберите Регистрация приложений.
Выберите Новая регистрация. Введите имя приложения, например
Graph App-Only Auth Tutorial
.Задайте для параметра Поддерживаемые типы учетных записейзначение Учетные записи только в этом каталоге организации.
Оставьте поле URI перенаправления пустым.
Нажмите Зарегистрировать. На странице Обзор приложения скопируйте значение идентификатора приложения (клиента) и идентификатора каталога (клиента) и сохраните их. Эти значения потребуются на следующем шаге.
Выберите Разрешения API в разделе Управление.
Удалите разрешение User.Read по умолчанию в разделе Настроенные разрешения , выбрав многоточие (...) в строке и выбрав Удалить разрешение.
Выберите Добавить разрешение, а затем — Microsoft Graph.
Выберите Разрешения приложения.
Выберите User.Read.All, а затем выберите Добавить разрешения.
Выберите Предоставить согласие администратора для..., а затем нажмите кнопку Да , чтобы предоставить согласие администратора для выбранного разрешения.
Выберите Сертификаты и секреты в разделе Управление, а затем выберите Новый секрет клиента.
Введите описание, выберите длительность и нажмите кнопку Добавить.
Скопируйте секрет из столбца Значение . Он понадобится на следующих шагах.
Важно!
Система никогда не покажет секрет клиента повторно, поэтому убедитесь, что вы скопировали его.
Примечание.
Обратите внимание, что в отличие от действий при регистрации для проверки подлинности пользователей в этом разделе вы настроили разрешения Microsoft Graph для регистрации приложения. Это связано с тем, что проверка подлинности только для приложений использует поток учетных данных клиента, который требует настройки разрешений на регистрацию приложения. Дополнительные сведения см . в разделе Область по умолчанию .
Создание консольного приложения TypeScript
Начните с создания проекта Node.js и настройки TypeScript.
Откройте интерфейс командной строки (CLI) в каталоге, в котором вы хотите создать проект. Выполните следующую команду.
npm init
Отвечайте на запросы, указав собственные значения или приняв значения по умолчанию.
Выполните следующую команду, чтобы установить TypeScript.
npm install -D typescript ts-node
Выполните следующую команду, чтобы инициализировать TypeScript.
npx tsc --init
Установка зависимостей
Прежде чем переходить дальше, добавьте некоторые дополнительные зависимости, которые будут использоваться позже.
- Клиентская библиотека удостоверений Azure для JavaScript для проверки подлинности пользователя и получения маркеров доступа.
- Клиентская библиотека JavaScript в Microsoft Graph для выполнения вызовов к Microsoft Graph.
-
изоморфная выборка для добавления
fetch
API в Node.js. Это зависимость для клиентской библиотеки JavaScript в Microsoft Graph. - readline-sync для запроса ввода данных у пользователя.
Выполните следующие команды в интерфейсе командной строки, чтобы установить зависимости.
npm install @azure/identity @microsoft/microsoft-graph-client isomorphic-fetch readline-sync
npm install -D @microsoft/microsoft-graph-types @types/node @types/readline-sync @types/isomorphic-fetch
Загрузка параметров приложения
В этом разделе вы добавите в проект сведения о регистрации приложения.
Создайте файл в корне проекта с именем appSettings.ts и добавьте следующий код.
const settings: AppSettings = { clientId: 'YOUR_CLIENT_ID_HERE', clientSecret: 'YOUR_CLIENT_SECRET_HERE', tenantId: 'YOUR_TENANT_ID_HERE', }; export interface AppSettings { clientId: string; clientSecret: string; tenantId: string; } export default settings;
Обновите значения в в
settings
соответствии со следующей таблицей.Параметр Значение clientId
Идентификатор клиента для регистрации приложения tenantId
Идентификатор клиента вашей организации. clientSecret
Секрет клиента, созданный на предыдущем шаге
Проектирование приложения
В этом разделе вы создадите простое меню на основе консоли.
Создайте файл в корне проекта с именем graphHelper.ts и добавьте следующий код заполнителя. Вы добавите дополнительный код этого файла на последующих шагах.
export {};
Создайте файл в корне проекта с именем index.ts и добавьте следующий код.
import * as readline from 'readline-sync'; import { User } from '@microsoft/microsoft-graph-types'; import settings, { AppSettings } from './appSettings'; import * as graphHelper from './graphHelper'; async function main() { console.log('TypeScript Graph Tutorial'); let choice = 0; // Initialize Graph initializeGraph(settings); const choices = ['Display access token', 'List users', 'Make a Graph call']; while (choice != -1) { choice = readline.keyInSelect(choices, 'Select an option', { cancel: 'Exit', }); switch (choice) { case -1: // Exit console.log('Goodbye...'); break; case 0: // Display access token await displayAccessTokenAsync(); break; case 1: // List users await listUsersAsync(); break; case 2: // Run any Graph code await makeGraphCallAsync(); break; default: console.log('Invalid choice! Please try again.'); } } } main();
Добавьте следующие методы-заполнители в конец файла. Вы будете реализовывать их на последующих шагах.
function initializeGraph(settings: AppSettings) { // TODO } async function displayAccessTokenAsync() { // TODO } async function listUsersAsync() { // TODO } async function makeGraphCallAsync() { // TODO }
Это реализует базовое меню и считывает выбор пользователя из командной строки.
Добавление проверки подлинности только для приложений
В этом разделе вы добавите в приложение проверку подлинности только для приложений. Это необходимо для получения необходимого маркера доступа OAuth для вызова Microsoft Graph. На этом шаге вы интегрируете клиентскую библиотеку удостоверений Azure для JavaScript в приложение и настроите проверку подлинности для клиентской библиотеки JavaScript в Microsoft Graph.
Библиотека удостоверений Azure предоставляет ряд классов, которые реализуют потоки маркеров TokenCredential
OAuth2. Клиентская библиотека Microsoft Graph использует эти классы для проверки подлинности вызовов Microsoft Graph.
Настройка клиента Graph для проверки подлинности только для приложений
В этом разделе вы будете ClientSecretCredential
использовать класс для запроса маркера доступа с помощью потока учетных данных клиента.
Откройте graphHelper.ts и добавьте следующий код.
import 'isomorphic-fetch'; import { ClientSecretCredential } from '@azure/identity'; import { Client, PageCollection } from '@microsoft/microsoft-graph-client'; // prettier-ignore import { TokenCredentialAuthenticationProvider } from '@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials'; import { AppSettings } from './appSettings'; let _settings: AppSettings | undefined = undefined; let _clientSecretCredential: ClientSecretCredential | undefined = undefined; let _appClient: Client | undefined = undefined; export function initializeGraphForAppOnlyAuth(settings: AppSettings) { // Ensure settings isn't null if (!settings) { throw new Error('Settings cannot be undefined'); } _settings = settings; if (!_clientSecretCredential) { _clientSecretCredential = new ClientSecretCredential( _settings.tenantId, _settings.clientId, _settings.clientSecret, ); } if (!_appClient) { const authProvider = new TokenCredentialAuthenticationProvider( _clientSecretCredential, { scopes: ['https://graph.microsoft.com/.default'], }, ); _appClient = Client.initWithMiddleware({ authProvider: authProvider, }); } }
Замените пустую
initializeGraph
функцию в index.ts на следующую.function initializeGraph(settings: AppSettings) { graphHelper.initializeGraphForAppOnlyAuth(settings); }
Этот код объявляет два частных свойства: ClientSecretCredential
объект и Client
объект . Функция InitializeGraphForAppOnlyAuth
создает новый экземпляр ClientSecretCredential
, а затем использует его для создания нового экземпляра Client
. Каждый раз, когда вызов API выполняется к Microsoft Graph через _appClient
, он использует предоставленные учетные данные для получения маркера доступа.
Тестирование ClientSecretCredential
Затем добавьте код для получения маркера доступа из ClientSecretCredential
.
Добавьте следующую функцию в graphHelper.ts.
export async function getAppOnlyTokenAsync(): Promise<string> { // Ensure credential isn't undefined if (!_clientSecretCredential) { throw new Error('Graph has not been initialized for app-only auth'); } // Request token with given scopes const response = await _clientSecretCredential.getToken([ 'https://graph.microsoft.com/.default', ]); return response.token; }
Замените пустую
displayAccessTokenAsync
функцию в index.ts на следующую.async function displayAccessTokenAsync() { try { const userToken = await graphHelper.getAppOnlyTokenAsync(); console.log(`App-only token: ${userToken}`); } catch (err) { console.log(`Error getting app-only access token: ${err}`); } }
Выполните следующую команду в интерфейсе командной строки в корне проекта.
npx ts-node index.ts
Введите
1
при появлении запроса на выбор параметра. Приложение отображает маркер доступа.TypeScript Graph App-Only Tutorial [1] Display access token [2] List users [3] Make a Graph call [0] Exit Select an option [1...3 / 0]: 1 App-only token: eyJ0eXAiOiJKV1QiLCJub25jZSI6IlVDTzRYOWtKYlNLVjVkRzJGenJqd2xvVUcwWS...
Совет
Только для проверки и отладки можно декодировать маркеры доступа только для приложений с помощью средства синтаксического анализа токенов Майкрософт в сети по адресу https://jwt.ms. Это может быть полезно, если при вызове Microsoft Graph возникают ошибки маркера. Например, убедитесь, что
role
утверждение в маркере содержит ожидаемые области разрешений Microsoft Graph.
Перечисление пользователей
В этом разделе вы добавите возможность вывода списка всех пользователей в Azure Active Directory с помощью проверки подлинности только для приложений.
Откройте graphHelper.ts и добавьте следующую функцию.
export async function getUsersAsync(): Promise<PageCollection> { // Ensure client isn't undefined if (!_appClient) { throw new Error('Graph has not been initialized for app-only auth'); } return _appClient ?.api('/users') .select(['displayName', 'id', 'mail']) .top(25) .orderby('displayName') .get(); }
Замените пустую
listUsersAsync
функцию в index.ts на следующую.async function listUsersAsync() { try { const userPage = await graphHelper.getUsersAsync(); const users: User[] = userPage.value; // Output each user's details for (const user of users) { console.log(`User: ${user.displayName ?? 'NO NAME'}`); console.log(` ID: ${user.id}`); console.log(` Email: ${user.mail ?? 'NO EMAIL'}`); } // If @odata.nextLink is not undefined, there are more users // available on the server const moreAvailable = userPage['@odata.nextLink'] != undefined; console.log(`\nMore users available? ${moreAvailable}`); } catch (err) { console.log(`Error getting users: ${err}`); } }
Запустите приложение, войдите в систему и выберите вариант 2, чтобы получить список пользователей.
[1] Display access token [2] List users [3] Make a Graph call [0] Exit Select an option [1...3 / 0]: 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
Описание кода
Рассмотрим код в getUsersAsync
функции. Он очень похож на код в getInboxAsync
:
- Он получает коллекцию пользователей
- Он использует
select
для запроса определенных свойств - Он использует
top
для ограничения числа возвращенных пользователей - Он использует
orderBy
для сортировки ответа
Необязательно: добавление собственного кода
В этом разделе вы добавите в приложение собственные возможности Microsoft Graph. Это может быть фрагмент кода из документации Microsoft Graph или обозревателя Graph или созданный вами код. Этот раздел является необязательным.
Обновите приложение
Откройте graphHelper.ts и добавьте следующую функцию.
// This function serves as a playground for testing Graph snippets // or other code export async function makeGraphCallAsync() { // INSERT YOUR CODE HERE }
Замените пустую
makeGraphCallAsync
функцию в index.ts на следующую.async function makeGraphCallAsync() { try { await graphHelper.makeGraphCallAsync(); } catch (err) { console.log(`Error making Graph call: ${err}`); } }
Выбор API
Найдите API в Microsoft Graph, который вы хотите попробовать. Например, API создания событий . Вы можете использовать один из примеров в документации по API или настроить запрос API в Graph Explorer и использовать созданный фрагмент кода.
Настройка разрешений
Ознакомьтесь с разделом Разрешения справочной документации по выбранному API, чтобы узнать, какие методы проверки подлинности поддерживаются. Некоторые API не поддерживают только приложения или личные учетные записи Майкрософт, например.
- Чтобы вызвать API с проверкой подлинности пользователя (если API поддерживает проверку подлинности пользователя (делегированная) проверка подлинности, см. руководство по проверке подлинности пользователя (делегированная).
- Чтобы вызвать API с проверкой подлинности только для приложений (если API поддерживает ее), добавьте требуемую область разрешений в Центре администрирования Azure AD.
Добавление кода
Скопируйте код в функцию makeGraphCallAsync
в graphHelper.ts. Если вы копируете фрагмент из документации или обозревателя Graph, обязательно переименуйте client
_appClient
в .
Поздравляем!
Вы завершили руководство по TypeScript Microsoft Graph. Теперь, когда у вас есть рабочее приложение, которое вызывает Microsoft Graph, вы можете экспериментировать и добавлять новые функции.
- Узнайте, как использовать проверку подлинности пользователя (делегированная) с помощью пакета SDK для JavaScript для Microsoft Graph.
- Просмотрите обзор Microsoft Graph , чтобы просмотреть все данные, к которым можно получить доступ с помощью Microsoft Graph.
Microsoft Graph Toolkit
Если вы создаете приложения TypeScript с помощью пользовательского интерфейса, набор средств Microsoft Graph предлагает набор компонентов, которые могут упростить разработку.
Примеры TypeScript и JavaScript
Возникла проблема с этим разделом? Если это так, отправьте нам отзыв, чтобы мы исправили этот раздел.