Бөлісу құралы:

Краткое руководство: вызов веб-API в примере демон-приложения

  • Мақала

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

Прежде чем начать, используйте Выбрать тип клиента селектор в верхней части этой страницы, чтобы выбрать тип клиента. Идентификатор Microsoft Entra предоставляет две конфигурации клиента, рабочей силы и внешних. Конфигурация арендатора рабочей силы предназначена для ваших сотрудников, внутренних приложений и других организационных ресурсов. Внешний клиент предназначен для ваших клиентских приложений.

Пример приложения, используемого в этом кратком руководстве, получает маркер доступа для вызова API Microsoft Graph.

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

  • Учетная запись Azure с активной подпиской. Если у вас еще нет учетной записи, создайте бесплатную учетную запись.
  • Эта учетная запись Azure должна иметь разрешения на управление приложениями. Любые из следующих ролей Microsoft Entra включают необходимые разрешения:
    • Администратор приложений
    • Разработчик приложений
    • Администратор облачных приложений
  • Клиент рабочей силы. Вы можете использовать каталог по умолчанию или настроить нового арендатора.
  • Зарегистрируйте новое приложение в центре администрирования Microsoft Entra с помощью следующей конфигурации. Дополнительные сведения см. в разделе Регистрация приложения.
    • Имя: identity-client-daemon-app
    • Поддерживаемые типы учетных записей: учетные записи в этом каталоге организации (только один клиент)

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

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

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

При создании учетных данных для конфиденциального клиентского приложения:

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

  • В целях тестирования можно создать самозаверяющий сертификат и настроить приложения для проверки подлинности с его помощью. Однако в производственной среденеобходимо приобрести сертификат, подписанный известным центром сертификации, а затем использовать Azure Key Vault для управления доступом к сертификату и сроком действия.

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

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

Для .NET демон-приложения вам не нужно предоставлять или соглашаться на какие-либо разрешения. Это демон-приложение считывает информацию о собственной регистрации, поэтому ему не нужны какие-либо разрешения приложения.

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

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

  • Чтобы клонировать пример, откройте командную строку и перейдите к месту создания проекта и введите следующую команду:
git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git
  • Скачайте .zip файл. Извлеките его в путь к файлу, где имя имеет длину меньше 260 символов.

Настройка проекта

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

  1. Откройте окно консоли и перейдите к каталогу ms-identity-docs-code-dotnet/console-daemon:

    cd ms-identity-docs-code-dotnet/console-daemon

  2. Откройте Program.cs и замените содержимое файла следующим фрагментом кода;

     // Full directory URL, in the form of https://login.microsoftonline.com/<tenant_id>
 Authority = " https://login.microsoftonline.com/Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center",
 // 'Enter the client ID obtained from the Microsoft Entra admin center
 ClientId = "Enter the client ID obtained from the Microsoft Entra admin center",
 // Client secret 'Value' (not its ID) from 'Client secrets' in the Microsoft Entra admin center
 ClientSecret = "Enter the client secret value obtained from the Mifcrosoft Entra admin center",
 // Client 'Object ID' of app registration in Microsoft Entra admin center - this value is a GUID
 ClientObjectId = "Enter the client Object ID obtained from the Microsoft Entra admin center"
    • Authority - Орган — это URL-адрес, указывающий каталог, из которого MSAL может запрашивать токены. Замените Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center данными Идентификатор каталога (арендатора), записанными ранее.
    • ClientId — идентификатор приложения, который также называется клиентом. Замените текст в кавычках значением Application (client) ID, записанным ранее на странице обзора зарегистрированного приложения.
    • ClientSecret — секрет клиента, созданный для приложения в Центре администрирования Microsoft Entra. Введите значение секрета клиента.
    • ClientObjectId — идентификатор объекта клиентского приложения. Замените текст в кавычках значением Object ID, записанным ранее на странице обзора зарегистрированного приложения.

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

Вы настроили образец приложения. Вы можете запустить и протестировать это.

В окне консоли выполните следующую команду, чтобы создать и запустить приложение:

dotnet run

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

{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
"id": "00001111-aaaa-2222-bbbb-3333cccc4444",
"deletedDateTime": null,
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"applicationTemplateId": null,
"disabledByMicrosoftStatus": null,
"createdDateTime": "2021-01-17T15:30:55Z",
"displayName": "identity-dotnet-console-app",
"description": null,
"groupMembershipClaims": null,
...
}

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

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

Приложение получает токен доступа от платформы идентификации Microsoft. Маркер доступа предназначен для API Microsoft Graph. Затем приложение использует маркер доступа для запроса собственных сведений о регистрации приложения из API Microsoft Graph. Приложение может запрашивать любой ресурс из API Microsoft Graph, если маркер доступа имеет правильные разрешения.

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

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

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

  • Учетная запись Azure с активной подпиской. Если вы еще не зарегистрированы, зарегистрируйтесь бесплатно.
  • Эта учетная запись Azure должна иметь разрешения на управление приложениями. Любые из следующих ролей Microsoft Entra включают необходимые разрешения:
    • Администратор приложений
    • Разработчик приложений
    • Администратор облачных приложений
  • Внешний арендатор. Чтобы создать его, выберите один из следующих методов:
  • Зарегистрируйте новое приложение в центре администрирования Microsoft Entra с помощью следующей конфигурации. Дополнительные сведения см. в разделе Регистрация приложения.
    • Имя: ciam-daemon-app
    • Поддерживаемые типы учетных записей: учетные записи в этом каталоге организации (только один клиент)
  • Visual Studio Code или любой другой редактор кода.
  • .NET 7.0 или новее.
  • Node.js (только для реализации узла)

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

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

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

При создании учетных данных для конфиденциального клиентского приложения:

  • Корпорация Майкрософт рекомендует использовать сертификат вместо секрета клиента перед перемещением приложения в рабочую среду. Дополнительные сведения об использовании сертификата см. в инструкциях по учетным данным сертификата аутентификации приложения платформы идентификации Microsoft .

  • В целях тестирования можно создать самозаверяющий сертификат и настроить приложения для проверки подлинности с его помощью. Однако в рабочейнеобходимо приобрести сертификат, подписанный известным центром сертификации, а затем использовать Azure Key Vault для управления доступом к сертификатам и временем существования.

Предоставление разрешений 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. Нажмите кнопку Добавить разрешения.

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

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

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

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

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

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

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

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

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

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

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

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

Клонируйте или скачайте пример приложения-демона и веб-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 на .NET должен убедиться, что токен доступа имеет необходимые разрешения (разрешения приложения). Веб-API не может принять маркер доступа, который не имеет необходимых разрешений.

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

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

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