Настройка диспетчера учетных данных — делегированный пользователем доступ к API серверной части

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API

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

Обзор сценария

Примечание.

Этот сценарий применяется только к поставщикам учетных данных, настроенным с типом предоставления кода авторизации.

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

• Пользователь должен авторизовать приложение для доступа к защищенным ресурсам от их имени и авторизовать приложение, пользователь должен пройти проверку подлинности своего удостоверения.
• Для выполнения операций от имени пользователя приложение вызывает внешнюю серверную службу, например Microsoft Graph или GitHub.
• Каждая внешняя служба имеет способ защиты этих вызовов, например с маркером пользователя, который однозначно идентифицирует пользователя.
• Чтобы защитить вызов внешней службы, приложение должно попросить пользователя войти, чтобы он смог получить маркер пользователя.
• В рамках конфигурации поставщик учетных данных регистрируется с помощью диспетчера учетных данных в экземпляре Управление API. Он содержит сведения об используемом поставщике удостоверений вместе с допустимым идентификатором клиента OAuth и секретом, область OAuth для включения и других метаданных подключения, необходимых поставщику удостоверений.
• Кроме того, создается и используется подключение для входа пользователя и получения маркера пользователя, чтобы его можно было управлять.

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

• Доступ к клиенту Microsoft Entra, в котором у вас есть разрешения на создание регистрации приложения и предоставление согласия администратора для разрешений приложения. Подробнее

  Если вы хотите создать собственный клиент разработчика, вы можете зарегистрироваться в программе разработчика Microsoft 365.

• Один или несколько пользователей или групп в клиенте, чтобы делегировать разрешения.

• Запущенный экземпляр Управление API. Если вам нужно, создайте экземпляр Azure Управление API.

• Внутренний API OAuth 2.0, к которому вы хотите обращаться от имени пользователя или группы.

• Если вы решили использовать Azure PowerShell локально:
  • Установите последнюю версию модуля Az PowerShell.
  • Подключитесь к учетной записи Azure с помощью командлета Connect-AzAccount.
• Если вы решили использовать Azure Cloud Shell:
  • Дополнительные сведения см. в статье Общие сведения об Azure Cloud Shell.

Шаг 1. Подготовка субъекта-службы уровня данных Azure Управление API

Необходимо подготовить субъект-службу уровня данных Azure Управление API, чтобы предоставить пользователям или группам необходимые делегированные разрешения. Выполните следующие действия, чтобы подготовить субъект-службу с помощью Azure PowerShell.

1. Войдите в Azure PowerShell.

2. Если модуль AzureAD еще не установлен, установите его с помощью следующей команды:

   Install-Module -Name AzureAD -Scope CurrentUser -Repository PSGallery -Force
   

3. Подключение клиенту с помощью следующей команды:

   Connect-AzureAD -TenantId "<YOUR_TENANT_ID>"
   

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

5. Подготовьте субъект-службу уровня данных Azure Управление API с помощью следующей команды:

   New-AzureADServicePrincipal -AppId c8623e40-e6ab-4d2b-b123-2ca193542c65 -DisplayName "Azure API Management Data Plane"
   

Шаг 2. Создание регистрации приложения Microsoft Entra

Создайте приложение идентификатора Microsoft Entra для делегирования пользователей и предоставьте ему соответствующие разрешения на чтение подключения в Управление API.

1. Войдите в портал Azure с учетной записью с достаточными разрешениями в клиенте.
2. В службах Azure найдите идентификатор Microsoft Entra.
3. В меню слева выберите Регистрация приложений и нажмите кнопку +Создать регистрацию.
4. На странице регистрации приложения введите параметры регистрации приложения:
   1. В поле "Имя" введите понятное имя, отображаемое пользователям приложения, например UserPermissions.
   2. В поддерживаемых типах учетных записей выберите вариант, соответствующий вашему сценарию, например учетные записи в этом каталоге организации (только один клиент).
   3. Задайте универсальный код ресурса (URI перенаправления) в Интернете и введите https://www.postman-echo.com/get.
5. В меню слева выберите разрешения API, а затем нажмите кнопку +Добавить разрешение.
   1. Выберите API, которые моя организация использует вкладку, введите Azure Управление API плоскости данных и выберите его.
   2. В разделе "Разрешения" выберите Authorizations.Read и нажмите кнопку "Добавить разрешения".
6. В меню слева выберите "Обзор". На странице обзора найдите значение идентификатора приложения (клиента) и запишите его для использования на следующем шаге.
7. В меню слева выберите сертификаты и секреты, а затем нажмите кнопку +Создать секрет клиента.
   1. Введите Описание.
   2. Выберите параметр "Срок действия".
   3. Выберите Добавить.
   4. Скопируйте значение секрета клиента перед выходом из страницы. Они потребуются вам на следующих шагах.

Шаг 3. Настройка поставщика учетных данных в Управление API

1. Войдите на портал и перейдите к экземпляру Управление API.
2. В меню слева выберите диспетчер учетных данных и нажмите кнопку "Создать".
   
3. На странице "Создание поставщика учетных данных" введите параметры поставщика учетных данных для API. Для этого сценария в типе Grant необходимо выбрать код авторизации. Дополнительные сведения см. в разделе "Настройка поставщиков учетных данных" в диспетчере учетных данных.
4. Нажмите кнопку создания.
5. При появлении запроса просмотрите отображаемый URL-адрес перенаправления OAuth и нажмите кнопку "Да ", чтобы подтвердить соответствие URL-адреса, введенного в регистрации приложения.

Шаг 4. Настройка подключения

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

1. Введите имя Подключение ion, а затем нажмите кнопку "Сохранить".
2. На шаге 2. Войдите в подключение, выберите ссылку для входа в поставщик учетных данных. Выполните действия, чтобы авторизовать доступ и вернуться к Управление API.
3. На шаге 3. Определите, кто будет иметь доступ к этому подключению (политика доступа) и нажмите кнопку +Добавить. В зависимости от сценария делегирования выберите "Пользователи " или "Группа".
4. В окне выбора элемента сделайте выбор в следующем порядке:
   1. Сначала найдите одного или нескольких пользователей (или групп), чтобы добавить и проверка поле выбора.
   2. Затем в появившемся списке найдите регистрацию приложения, созданную в предыдущем разделе.
   3. Затем щелкните Выбрать.
5. Выберите Завершено.

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

Совет

Используйте портал для добавления, обновления или удаления подключений к поставщику учетных данных в любое время. Дополнительные сведения см. в разделе "Настройка нескольких подключений".

Шаг 5. Получение маркера доступа к идентификатору Microsoft Entra

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

1. Вставьте следующий URL-адрес в браузере, заменив значения для <tenant-id> и <client-id> значениями из регистрации приложения Microsoft Entra:

   https://login.microsoftonline.com/<tenant-id>/oauth2/authorize?client_id=<client-id>&response_type=code&redirect_uri=https://www.postman-echo.com/get&response_mode=query&resource=https://azure-api.net/authorization-manager&state=1234`
   

2. Когда появится запрос, выполните вход. В тексте ответа скопируйте значение предоставленного кода (например: "0.AXYAh2yl…").

3. Отправьте следующий POST запрос в конечную точку токена, заменив <tenant-id> идентификатор клиента, включая указанный заголовок и параметры тела из регистрации приложения и код, скопированный на предыдущем шаге.

   POST https://login.microsoftonline.com/<tenant-id>/oauth2/token HTTP/1.1
   

   Верхний колонтитул

   Content-Type: application/x-www-form-urlencoded

   Текст

   grant_type: "authorization_code"
   client_id: <client-id>
   client_secret: <client-secret>
   redirect_uri: <redirect-url> 
   code: <code>   ## The code you copied in the previous step
   

4. В тексте ответа скопируйте значение access_token , предоставленное (например: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjZqQmZ1...). Это значение будет передаваться в конфигурации политики на следующем шаге.

Шаг 6. Настройка политики контекста get-authorization-context для серверного API

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

1. Войдите на портал и перейдите к экземпляру Управление API.

2. В меню слева выберите API и выберите внутренний API OAuth 2.0.

3. Выберите Все операции. В разделе Обработка исходящих запросов выберите значок редактора кода (</>).

4. get-authorization-context Настройте политику в разделе с параметром identity-type inbound jwt:

   <policies>
       <inbound>
           [...]
           <get-authorization-context provider-id="<credential-provider-id>" authorization-id="<connection-id>" context-variable-name="auth-context" identity-type="jwt" identity="<access-token>" ignore-error="false" />
           [...]
       </inbound> 
   </policies>
   

В приведенном выше определении политики замените следующее:

• <credential-provider-id> и <connection-id> имена поставщика учетных данных и подключения соответственно, настроенные на предыдущем шаге.

• <access-token> с маркером доступа к идентификатору Microsoft Entra, созданному на предыдущем шаге.

Шаг 7. Тестирование API

1. На вкладке "Тест" выберите одну операцию, настроенную.

2. Выберите Отправить.

   Успешный ответ возвращает пользовательские данные из серверного API.

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

• Дополнительные сведения о политиках проверки подлинности и авторизации
• Дополнительные сведения о область и разрешениях см. в идентификаторе Microsoft Entra.