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

Руководство. Вызов API Microsoft Graph в приложении управляющей программы Node.js консоли

  • Статья

В этом руководстве вы создадите консольное приложение управляющей программы, которое вызывает API Microsoft Graph с помощью собственного удостоверения. Приложение управляющей программы, которое вы создаете, использует библиотеку проверки подлинности Майкрософт (MSAL) для Node.js.

Выполните шаги из этого руководства, чтобы:

  • регистрация приложения на портале Azure;
  • Создание проекта приложения Node.js консоли
  • Добавление логики аутентификации в приложение
  • Добавление сведений о регистрации приложения
  • добавить метод для вызова веб-API;
  • Тестирование приложения

Необходимые компоненты

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

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

Используйте следующие параметры для регистрации приложения:

  • Имя: NodeDaemonApp (рекомендуется).
  • Поддерживаемые типы учетных записей: учетные записи только в этом каталоге организации
  • Разрешения API: API Майкрософт>Microsoft Graph>Разрешения приложения>User.Read.All
  • Секрет клиента: ********* (запишите это значение для использования на последующих этапах; оно отображается только один раз).

Создание проекта

  1. Начните с создания каталога для этого проекта учебника Node.js, Например, NodeDaemonApp.

  2. В терминале перейдите в созданный каталог (корень проекта) и выполните следующие команды:

    npm init -y
npm install --save dotenv yargs axios @azure/msal-node

  3. Затем измените файл package.json в корне проекта и добавьте bin/ в начало значения main, например так:

    "main": "bin/index.js",

  4. Теперь создайте каталог bin и в каталоге bin добавьте следующий код в файл с именем index.js:

    #!/usr/bin/env node

// read in env settings
require('dotenv').config();

const yargs = require('yargs');

const fetch = require('./fetch');
const auth = require('./auth');

const options = yargs
    .usage('Usage: --op <operation_name>')
    .option('op', { alias: 'operation', describe: 'operation name', type: 'string', demandOption: true })
    .argv;

async function main() {
    console.log(`You have selected: ${options.op}`);

    switch (yargs.argv['op']) {
        case 'getUsers':

            try {
                // here we get an access token
                const authResponse = await auth.getToken(auth.tokenRequest);

                // call the web API with the access token
                const users = await fetch.callApi(auth.apiConfig.uri, authResponse.accessToken);

                // display result
                console.log(users);
            } catch (error) {
                console.log(error);
            }

            break;
        default:
            console.log('Select a Graph operation first');
            break;
    }
};

main();

Созданный вами файл index.js ссылается на два других модуля узла, которые вы создадите далее:

  • auth.js — использует MSAL Node для получения маркеров доступа от платформы удостоверений Майкрософт.
  • fetch.js — запрашивает данные из API Microsoft Graph, включая маркеры доступа (полученные в файле auth.js) в HTTP-запросы к API.

По завершении работы с этим учебником файл и структура каталога проекта будут выглядеть следующим образом:

NodeDaemonApp/
├── bin
│   ├── auth.js
│   ├── fetch.js
│   ├── index.js
├── package.json
└── .env

Добавление логики аутентификации

В каталоге bin добавьте следующий код в новый файл с именем auth.js. Код в файле auth.js получает маркер доступа от платформы удостоверений Майкрософт для включения в запросы API Microsoft Graph.

const msal = require('@azure/msal-node');

/**
 * Configuration object to be passed to MSAL instance on creation.
 * For a full list of MSAL Node configuration parameters, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
 */
const msalConfig = {
    auth: {
        clientId: process.env.CLIENT_ID,
        authority: process.env.AAD_ENDPOINT + '/' + process.env.TENANT_ID,
        clientSecret: process.env.CLIENT_SECRET,
    }
};

/**
 * With client credentials flows permissions need to be granted in the portal by a tenant administrator.
 * The scope is always in the format '<resource>/.default'. For more, visit:
 * https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow
 */
const tokenRequest = {
    scopes: [process.env.GRAPH_ENDPOINT + '/.default'],
};

const apiConfig = {
    uri: process.env.GRAPH_ENDPOINT + '/v1.0/users',
};

/**
 * Initialize a confidential client application. For more info, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/initialize-confidential-client-application.md
 */
const cca = new msal.ConfidentialClientApplication(msalConfig);

/**
 * Acquires token with client credentials.
 * @param {object} tokenRequest
 */
async function getToken(tokenRequest) {
    return await cca.acquireTokenByClientCredential(tokenRequest);
}

module.exports = {
    apiConfig: apiConfig,
    tokenRequest: tokenRequest,
    getToken: getToken
};

В приведенном выше фрагменте кода сначала создается объект конфигурации (msalConfig), который передается для инициализации объекта MSAL ConfidentialClientApplication. Затем создается метод для получения маркеров через учетные данные клиента и файлу main.js предоставляется доступ к этому модулю. Параметры конфигурации в этом модуле копируются из файла среды, который будет создан на следующем шаге.

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

Создайте файл среды для хранения сведений о регистрации приложения, которые будут использоваться при получении маркеров. Для этого создайте файл с именем ENV в корневой папке примера (NodeDaemonApp) и добавьте следующий код:

# Credentials
TENANT_ID=Enter_the_Tenant_Id_Here
CLIENT_ID=Enter_the_Application_Id_Here
CLIENT_SECRET=Enter_the_Client_Secret_Here

# Endpoints
AAD_ENDPOINT=Enter_the_Cloud_Instance_Id_Here/
GRAPH_ENDPOINT=Enter_the_Graph_Endpoint_Here/

Приведите следующие сведения, указав значения, которые вы получили на портале регистрации приложений Azure:

  • Enter_the_Tenant_Id_here должно быть одним из следующих вариантов:
    • Если приложение поддерживает учетные записи только в этом каталоге организации, замените это значение идентификатором клиента или именем клиента. Например, contoso.microsoft.com.
    • Если приложение поддерживает учетные записи в любом каталоге организации, замените это значение на organizations.
    • Если приложение поддерживает учетные записи в любом каталоге организации и личные учетные записи Майкрософт, замените это значение на common.
    • Чтобы ограничить поддержку только личными учетными записями Microsoft, замените это значение на consumers.
  • Enter_the_Application_Id_Here: идентификатор приложения (клиента), которое вы зарегистрировали.
  • Enter_the_Cloud_Instance_Id_Here: облачный экземпляр Azure, в котором зарегистрировано приложение.
    • Для основного (или глобального) облака Azure введите https://login.microsoftonline.com.
    • Для национальных облаков (например, китайского) соответствующие значения см. в статье Национальные облака.
  • Enter_the_Graph_Endpoint_Here экземпляр API Microsoft Graph, с которым должно взаимодействовать приложение.
    • Для глобальной конечной точки API Microsoft Graph замените оба экземпляра этой строки на https://graph.microsoft.com.
    • Дополнительные сведения о конечных точках в национальных облачных развертываниях см. в статье Национальные облачные развертывания в документации по Microsoft Graph.

добавить метод для вызова веб-API;

В папке bin создайте еще один файл с именем fetch.js и добавьте следующий код для выполнения вызовов REST к API Microsoft Graph:

const axios = require('axios');

/**
 * Calls the endpoint with authorization bearer token.
 * @param {string} endpoint
 * @param {string} accessToken
 */
async function callApi(endpoint, accessToken) {

    const options = {
        headers: {
            Authorization: `Bearer ${accessToken}`
        }
    };

    console.log('request made to web API at: ' + new Date().toString());

    try {
        const response = await axios.get(endpoint, options);
        return response.data;
    } catch (error) {
        console.log(error)
        return error;
    }
};

module.exports = {
    callApi: callApi
};

Здесь метод callApi используется для выполнения HTTP-запроса GET к защищенному ресурсу, которому требуется маркер доступа. Затем метод возвращает содержимое вызывающему объекту. Этот метод добавляет полученный маркер в заголовок авторизации HTTP. Защищенный ресурс здесь — это конечная точка пользователей API Microsoft Graph, в которой отображаются пользователи в арендаторе, где зарегистрировано это приложение.

Тестирование приложения

Вы создали приложение и теперь готовы протестировать его функциональность.

Запустите приложение управляющей программы консоли Node.js, выполнив следующую команду из корневой папки проекта:

node . --op getUsers

В результате вы получите некоторый ответ JSON от API Microsoft Graph и сможете просмотреть массив пользовательских объектов в консоли:

You have selected: getUsers
request made to web API at: Fri Jan 22 2021 09:31:52 GMT-0800 (Pacific Standard Time)
{
    '@odata.context': 'https://graph.microsoft.com/v1.0/$metadata#users',
    value: [
        {
            displayName: 'Adele Vance'
            givenName: 'Adele',
            jobTitle: 'Retail Manager',
            mail: 'AdeleV@msaltestingjs.onmicrosoft.com',
            mobilePhone: null,
            officeLocation: '18/2111',
            preferredLanguage: 'en-US',
            surname: 'Vance',
            userPrincipalName: 'AdeleV@msaltestingjs.onmicrosoft.com',
            id: '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'
        }
    ]
}

Интерфейс командной строки с отображением ответа Graph

Принцип работы приложения

Это приложение использует предоставление учетных данных клиента OAuth 2.0. Этот тип предоставления разрешения часто используется для взаимодействия между серверами, которое должно выполняться в фоновом режиме без непосредственного взаимодействия с пользователем. Процесс предоставления учетных данных позволяет веб-службе (конфиденциальный клиент) вместо олицетворения пользователя использовать свои собственные учетные данные для аутентификации при вызове другой веб-службы. Приложения, поддерживаемые этой моделью аутентификации, обычно представляют собой управляющие программы или учетные записи служб.

Область запросов для потока учетных данных клиента — это имя ресурса с добавлением /.default. Эта нотация сообщает идентификатору Microsoft Entra использовать разрешения на уровне приложения, объявленные статически во время регистрации приложения. Кроме того, эти разрешения API должны быть предоставлены администратором арендатора.

Следующие шаги

Если вы хотите более подробно ознакомиться с Node.js разработке приложений управляющей программы на платформа удостоверений Майкрософт, ознакомьтесь с нашими сериями сценариев с несколькими частей:

Сценарий: приложение управляющей программы