Краткое руководство - вход пользователей и вызов веб-API в примере веб-приложения Node.js

применяется к: арендаторы рабочей силы внешние клиенты (подробнее)

Из этого краткого руководства вы узнаете, как выполнить вход для пользователей и вызвать веб-API из веб-приложения Node.js в вашем внешнем арендаторе. Пример приложения вызывает API .NET. Пример веб-приложения использует библиотеку Майкрософт (MSAL) для Node.js для обработки аутентификации.

Необходимые условия

• Выполните шаги и предварительные требования в статье "Быстрое руководство: Вход пользователей в пример веб-приложения". В этой статье показано, как выполнить вход пользователей с помощью примера веб-приложения Node.js.
• Внешний арендатор. Чтобы создать его, выберите один из следующих методов:
  • (Рекомендуется) Используйте расширение Microsoft Entra External ID для настройки внешнего арендатора прямо в Visual Studio Code.
  • создание нового внешнего клиента в Центре администрирования Microsoft Entra.
• Зарегистрируйте новое приложение для веб-API в Центре администрирования Microsoft Entra, настроенное только для учетных записей в этом каталоге организации. Дополнительные сведения см. в статье "Регистрация приложения ". Запишите следующие значения на странице обзора приложения для последующего использования:
  • Идентификатор приложения (клиента)
  • Идентификатор каталога (арендатора)
• Visual Studio Code или другой редактор кода.
• Node.js.
• .NET 7.0 или более поздней версии.

Настройка областей и ролей API

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

Настройка областей API

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

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

2. В разделе Управлениевыберите Открыть API.

3. В верхней части страницы рядом с URI идентификатора приложениявыберите ссылку Добавить, чтобы создать уникальный URI для этого приложения.

4. Примите предлагаемый URI идентификатора приложения (например, api://{clientId}), а затем выберите Сохранить. Когда веб-приложение запрашивает маркер доступа для веб-API, он добавляет URI в качестве префикса для каждой области, определяемой для API.

5. В разделе Области, определенные этим API, выберите Добавить область.

6. Введите следующие значения, определяющие доступ для чтения к API, а затем выберите Добавить область, чтобы сохранить изменения:

   Свойство	Ценность
   Имя области	Список дел.Чтение
   Кто может согласиться	Только администраторы
   Отображаемое имя администраторского согласия	Чтение списка ToDo пользователей с помощью TodoListApi
   Описание согласия администратора	Разрешить приложению читать список дел пользователя с использованиемTodoListApi.
   Государство	включено

7. Выберите Снова добавить область и введите следующие значения, определяющие область доступа для чтения и записи в API. Выберите Добавить область, чтобы сохранить изменения:

   Свойство	Ценность
   Имя области	СписокДел.ЧтениеЗапись
   Кто может согласиться	Только администраторы
   Отображаемое имя администраторского согласия	Чтение и запись списка дел пользователей с помощью ToDoListApi
   Описание согласия администратора	Разрешить приложению читать и записывать список дел пользователя, используя ToDoListApi
   Государство	включено

Узнайте больше о принципе минимальных привилегий в контексте публикации разрешений для веб-API.

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

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

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

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

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

   Свойство	Ценность
   Отображаемое имя	ToDoList.Прочитать.Все
   Допустимые типы членов	приложения
   Ценность	ToDoList.Прочитать.Все
   Описание	Разрешить приложению читать Список дел каждого пользователя через TodoListApi
   Вы хотите активировать эту роль приложения?	Оставьте это отмеченным

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

   Свойство	Ценность
   Отображаемое имя	ToDoList.ЧитатьПисать.Все
   Допустимые типы членов	приложения
   Ценность	ToDoList.ЧитатьПисать.Все
   Описание	Разрешить приложению читать и записывать список ToDo каждого пользователя с помощью ToDoListApi
   Вы хотите активировать эту роль приложения?	Оставьте это отмеченным

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

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

Выполните действия, описанные в статье Настройка необязательных утверждений, чтобы добавить утверждение типа idtyp в токен доступа.

• Для типа токена выберите Access.
• В списке необязательных утверждений выберите idtyp.

Предоставление разрешений API веб-приложению

Чтобы предоставить вашему клиентскому приложению (ciam-client-app) доступ к API, выполните следующие действия.

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

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

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

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

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

6. Выберите делегированные разрешения.

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

8. Нажмите кнопку Добавить разрешения. На этом этапе вы правильно задали разрешения. Тем не менее, поскольку арендатор является арендатором клиента, сами потребители не могут согласиться с этими разрешениями. Чтобы устранить эту проблему, администратор должен согласиться с этими разрешениями от имени всех пользователей в клиенте:

   1. Выберите Предоставить согласие администратора для <вашего имени арендатора>, затем выберите Да.

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

9. В списке Настроенные разрешения выберите разрешение ToDoList.Read и разрешение ToDoList.ReadWrite, а затем скопируйте полный URI разрешения для последующего использования. Полный URI разрешений выглядит примерно так же, как api://{clientId}/{ToDoList.Read} или api://{clientId}/{ToDoList.ReadWrite}.

Клонирование или скачивание примера веб-приложения и веб-API

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

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

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

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

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

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

   cd 2-Authorization\4-call-api-express\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. Веб-приложение API — это приложение, зарегистрированное ранее в рамках предварительных требований.
   • Enter_the_Tenant_Id_Here и замените его идентификатором каталога (клиента), скопированным ранее.
   • Enter_the_Tenant_Subdomain_Here и замените его поддоменом каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет имени арендатора, узнайте, как просматривать информацию о тенанте.

Запуск и тестирование примера веб-приложения и API

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

   cd 2-Authorization\4-call-api-express\API\ToDoListAPI
   dotnet run
   

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

   cd 2-Authorization\4-call-api-express\App
   npm install
   npm start
   

3. Откройте браузер, а затем перейдите к http://localhost:3000.

4. Нажмите кнопку "Войти". Вам будет предложено войти.

   

5. На странице входа введите адрес электронной почты, выберите Далее, введите пароль, а затем выберите Войти. Если у вас нет учетной записи, выберите Нет учетной записи? Создайте одну ссылку, которая запускает поток регистрации.

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

   

Вызов API

1. Чтобы вызвать API, выберите ссылку Просмотреть ваш список задач. Вы увидите страницу, аналогичную следующему снимку экрана.

   

2. Управление списком to-do путем создания и удаления элементов.

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

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

Конечная точка веб-API должна проверить, допустимы ли разрешения или области действия в маркере доступа, предоставленном клиентским приложением. Если маркер доступа действителен, конечная точка отвечает на HTTP-запрос, в противном случае она отвечает с ошибкой 401 Unauthorized HTTP.

Связанное содержимое

• Руководство: Защита веб-API ASP.NET Core, зарегистрированного во внешнем арендаторе.