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

Вызов API в примере приложения управляющей программы Node.js

  • Статья

В этом руководстве используется пример приложения Node.js управляющей программы, чтобы показать, как приложение управляющей программы получает маркер для вызова веб-API. Microsoft Entra защищает веб-API.

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

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

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

Регистрация приложения управляющей программы и веб-API

На этом шаге вы создадите управляющая программа и регистрации приложений веб-API, а также укажите области веб-API.

Регистрация приложения веб-API

  1. Войдите в Центр администрирования Microsoft Entra как минимум разработчик приложений.

  2. Если у вас есть доступ к нескольким клиентам, используйте значок параметров в верхнем меню, чтобы переключиться на внешний клиент из меню каталогов и подписок.

  3. Перейдите к приложениям> удостоверений>Регистрация приложений.

  4. Выберите + Создать регистрацию.

  5. Откроется страница "Регистрация приложения", где необходимо ввести сведения о регистрации приложения:

    1. В разделе "Имя" введите понятное имя приложения, которое будет отображаться пользователям приложения, например ciam-ToDoList-api.

    2. В разделе Поддерживаемые типы учетных записей выберите Учетные записи только в этом каталоге организации.

  6. Выберите Зарегистрировать, чтобы создать приложение.

  7. Панель обзора приложения отображается при завершении регистрации. Запишите идентификатор каталога (клиента) и идентификатор приложения (клиента), которые будут использоваться в исходном коде приложения.

Настройка ролей приложения

API должен опубликовать не менее одной роли приложения для приложений, которые также называются разрешениями приложений, чтобы клиентские приложения получили маркер доступа как сами. Разрешения приложений — это тип разрешений, которые api-интерфейсы должны публиковать, когда они хотят разрешить клиентским приложениям успешно проходить проверку подлинности как сами и не должны выполнять вход пользователей. Чтобы опубликовать разрешение приложения, выполните следующие действия.

  1. На странице Регистрация приложений выберите созданное приложение (например, ciam-ToDoList-api), чтобы открыть страницу обзора.

  2. В разделе "Управление" выберите роли приложения.

  3. Выберите " Создать роль приложения", а затем введите следующие значения, а затем нажмите кнопку "Применить ", чтобы сохранить изменения:

    Свойство Значение
    Отображаемое имя ToDoList.Read.All
    Разрешенные типы элементов Приложения
    Значение ToDoList.Read.All
    Description Разрешить приложению считывать список toDo каждого пользователя с помощью todopi TodoListApi.

  4. Снова нажмите кнопку "Создать роль приложения", а затем введите следующие значения для второй роли приложения, а затем нажмите кнопку "Применить ", чтобы сохранить изменения:

    Свойство Значение
    Отображаемое имя ToDoList.ReadWrite.All
    Разрешенные типы элементов Приложения
    Значение ToDoList.ReadWrite.All
    Description Разрешить приложению считывать и записывать список toDopi каждого пользователя с помощью toDoListApi

Настройка необязательных утверждений

Вы можете бездействующее утверждение, чтобы помочь веб-API определить, является ли токен маркером приложения или приложением и маркером пользователя. Хотя вы можете использовать сочетание утверждений scp и ролей для той же цели, используя утверждение idtyp, проще всего определить маркер приложения и приложение + маркер пользователя. Например, значение этого утверждения — это приложение , когда маркер является маркером только для приложений.

Регистрация приложения управляющей программы

Чтобы приложение входить в систему с помощью Microsoft Entra, Внешняя идентификация Microsoft Entra должны быть осведомлены о создаваемом приложении. Регистрация приложения устанавливает отношение доверия между приложением и Microsoft Entra. При регистрации приложения внешний идентификатор создает уникальный идентификатор, известный как идентификатор приложения (клиента), значение, используемое для идентификации приложения при создании запросов проверки подлинности.

Ниже показано, как зарегистрировать приложение в Центре администрирования Microsoft Entra:

  1. Войдите в Центр администрирования Microsoft Entra как минимум разработчик приложений.

  2. Если у вас есть доступ к нескольким клиентам, используйте значок параметров в верхнем меню, чтобы переключиться на внешний клиент из меню каталогов и подписок.

  3. Перейдите к приложениям> удостоверений>Регистрация приложений.

  4. Выберите + Создать регистрацию.

  5. На отображаемой странице регистрации приложения;

    1. Введите понятное имя приложения, отображаемое пользователям приложения, например ciam-client-app.
    2. В разделе Поддерживаемые типы учетных записей выберите Учетные записи только в этом каталоге организации.

  6. Выберите Зарегистрировать.

  7. Панель обзора приложения отображается при успешной регистрации. Запишите идентификатор приложения (клиента), который будет использоваться в исходном коде приложения.

Создание секрета клиента

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

  1. На странице Регистрация приложений выберите созданное приложение (например, ciam-client-app), чтобы открыть страницу обзора.
  2. В разделе Управление выберите Сертификаты и секреты.
  3. Щелкните Создать секрет клиента.
  4. В поле "Описание" введите описание секрета клиента (например, секрет клиента приложения ciam).
  5. В разделе "Срок действия" выберите срок действия, для которого секрет действителен (для правил безопасности организации), а затем нажмите кнопку "Добавить".
  6. Запишите значение секрета в поле Значение. Это значение будет использовано позже для конфигурации. Значение секрета не будет отображаться снова и не извлекается с помощью каких-либо средств после перехода от сертификатов и секретов. Обязательно запишите его.

Предоставление разрешений API приложению управляющей программы

  1. На странице Регистрация приложений выберите созданное приложение, например ciam-client-app.

  2. В разделе Управление выберите Разрешения API.

  3. В разделе Настроенные разрешения выберите Добавить разрешение.

  4. Щелкните вкладку API, используемые моей организацией.

  5. В списке API выберите API, например ciam-ToDoList-api.

  6. Выберите параметр "Разрешения приложения". Мы выбираем этот параметр как приложение войдите как само по себе, а не пользователи.

  7. В списке разрешений выберите TodoList.Read.All, ToDoList.ReadWrite.All (при необходимости используйте поле поиска).

  8. Нажмите кнопку Add permissions (Добавить разрешения).

  9. На этом этапе вы правильно назначили разрешения. Однако, так как приложение управляющей программы не позволяет пользователям взаимодействовать с ним, сами пользователи не могут согласиться на эти разрешения. Чтобы устранить эту проблему, администратор должен согласиться с этими разрешениями от имени всех пользователей в клиенте:

    1. Выберите "Предоставить согласие администратора" для <имени> клиента, а затем нажмите кнопку "Да".
    2. Выберите "Обновить", а затем убедитесь, что <имя> клиента предоставлено в разделе "Состояние" для обоих разрешений.

Клонирование или скачивание примера приложения управляющей программы и веб-API

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

  • Чтобы клонировать пример, откройте командную строку и перейдите к месту создания проекта и введите следующую команду:

    git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git

  • Скачайте файл .zip. Извлеките его в путь к файлу, где длина имени меньше 260 символов.

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

  1. Откройте окно консоли и перейдите в каталог, содержащий пример приложения Node.js:

    cd 2-Authorization\3-call-api-node-daemon\App

  2. Для установки зависимостей приложения выполните следующие команды:

    npm install && npm update

Настройка примера приложения управляющей программы и API

Чтобы использовать регистрацию приложения в примере клиентского веб-приложения, сделайте следующее:

  1. В редакторе кода откройте App\authConfig.js файл.

  2. Найдите заполнитель:

    • Enter_the_Application_Id_Here и замените его идентификатором приложения (клиента) управляющей программы, зарегистрированного ранее.

    • Enter_the_Tenant_Subdomain_Here и замените его поддоменом каталога (клиента). Например, если основной домен клиента — это contoso.onmicrosoft.com, используйте contoso. Если у вас нет имени клиента, узнайте, как прочитать сведения о клиенте.

    • Enter_the_Client_Secret_Here и замените его значением секрета приложения управляющей программы, скопированным ранее.

    • Enter_the_Web_Api_Application_Id_Here и замените его идентификатором приложения (клиента) веб-API, скопированного ранее.

Чтобы использовать регистрацию приложения в примере веб-API, сделайте следующее:

  1. В редакторе кода откройте API\ToDoListAPI\appsettings.json файл.

  2. Найдите заполнитель:

    • Enter_the_Application_Id_Here и замените его идентификатором приложения (клиента) скопированного веб-API.

    • Enter_the_Tenant_Id_Here и замените его идентификатором каталога (клиента), скопированным ранее.

    • Enter_the_Tenant_Subdomain_Here и замените его поддоменом каталога (клиента). Например, если основной домен клиента — это contoso.onmicrosoft.com, используйте contoso. Если у вас нет имени клиента, узнайте, как прочитать сведения о клиенте.

Запуск и тестирование примера приложения управляющей программы и API

  1. Откройте окно консоли, а затем запустите веб-API с помощью следующих команд:

    cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI
dotnet run

  2. Запустите клиент веб-приложения с помощью следующих команд:

    2-Authorization\3-call-api-node-daemon\App
node . --op getToDos

  • Если приложение управляющей программы и веб-API успешно запущены, в окне консоли должно появиться примерно то же, что и следующий массив JSON.

    {
    "id": 1,
    "owner": "3e8....-db63-43a2-a767-5d7db...",
    "description": "Pick up grocery"
},
{
    "id": 2,
    "owner": "c3cc....-c4ec-4531-a197-cb919ed.....",
    "description": "Finish invoice report"
},
{
    "id": 3,
    "owner": "a35e....-3b8a-4632-8c4f-ffb840d.....",
    "description": "Water plants"
}

Принцип работы

Приложение Node.js использует учетные данные клиента OAuth 2.0 для получения маркера доступа для себя, а не для пользователя. Маркер доступа, который запрашивает приложение, содержит разрешения, представленные в качестве ролей. Поток учетных данных клиента использует этот набор разрешений вместо областей пользователей для маркеров приложения. Вы предоставили эти разрешения приложения в веб-API ранее, а затем предоставили им управляющее приложение.

На стороне API веб-API должен убедиться, что маркер доступа имеет необходимые разрешения (разрешения приложения). Веб-API не может принять маркер доступа, который не имеет необходимых разрешений.

Доступ к данным

Конечная точка веб-API должна быть готова принимать вызовы от пользователей и приложений. Таким образом, он должен иметь способ ответить на каждый запрос соответствующим образом. Например, вызов пользователя с помощью делегированных разрешений или областей получает список данных пользователя. С другой стороны, вызов из приложения через разрешения или роли приложения может получить весь список действий. Однако в этой статье мы вызываем только приложение, поэтому нам не нужно настраивать делегированные разрешения и области.

Связанный контент