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

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

  • Статья

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

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

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

Регистрация веб-API

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

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

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

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

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

  4. Выберите + Новая регистрация.

  5. На появившейся странице регистрации приложения введите сведения о его регистрации:

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

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

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

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

Настройка областей 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
    Государство включено

  8. В разделе Управлениевыберите Манифест, чтобы открыть редактор манифеста API.

  9. Задайте для свойства accessTokenAcceptedVersion значение 2.

  10. Выберите Сохранить.

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

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

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

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

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

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

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

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

    Свойство Ценность
    Отображаемое имя ToDoList.ReadWrite.All
    Разрешенные типы участников приложения
    Ценность ToDoList.ReadWrite.All
    Описание Разрешить приложению читать и записывать список 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. Если у вас нет имени арендатора, узнайте, как [узнать сведения о внешнем арендаторе](../external-id/customers/how-to-create-external-tenant-portal.md#get-the-external-tenant-details).
    • 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\4-call-api-express\API\ToDoListAPI
dotnet run

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

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

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

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

    снимок экрана входа в веб-приложение узла.

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

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

    снимок экрана: вход в веб-приложение узла и вызов API.

Вызов API

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

    снимок экрана API для управления списком задач.

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

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

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

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

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