Вызов Microsoft Graph из приложения CSP

Статья
04/01/2024

Примечание: Этот раздел относится только к разработчикам приложений поставщика облачных решений Майкрософт (CSP). Программа поставщиков облачных решений Майкрософт (CSP) позволяет партнерам Корпорации Майкрософт перепродавать клиентам службы Microsoft Online и управлять ими.

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

Важно!

Вызов Microsoft Graph из приложения CSP поддерживается только для ресурсов каталога (пользователей, групп, устройств, организаций) и Intune ресурсов.

Приложение, управляемое партнером

Программа CSP позволяет партнерам Корпорации Майкрософт перепродавать клиентам веб-службы Майкрософт (например, Microsoft 365, Microsoft Azure и CRM Online) и управлять ими. Управление клиентскими службами осуществляется с помощью делегированных привилегий Администратор, что позволяет назначенным пользователям-партнерам (называемым агентами) получать доступ к средам своих клиентов и настраивать их.

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

Настройка приложения, управляемого партнером

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

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

Регистрация и настройка мультитенантного приложения

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

Зарегистрируйте приложение в клиенте партнера с помощью Центр администрирования Microsoft Entra. Для работы в качестве приложения, управляемого партнером, приложение должно быть настроено как мультитенантное приложение. Кроме того, если приложение развернуто и продается в нескольких географических регионах, необходимо зарегистрировать приложение в каждом из этих регионов, как описано здесь.
Настройте мультитенантное приложение с помощью Центр администрирования Microsoft Entra с необходимыми разрешениями для использования подхода с минимальными привилегиями.

Предварительная поддержка приложения для всех ваших клиентов

Наконец, предоставьте приложению, управляемому партнером, настроенные разрешения для всех ваших клиентов. Это можно сделать, добавив servicePrincipal, который представляет приложение, в группу Администраторы в клиенте партнера, используя Azure AD PowerShell версии 2 или Microsoft Graph PowerShell. Выполните следующие действия, чтобы найти группу AdminagentsservicePrincipal и добавить ее в группу.

Примечание.

модули PowerShell Azure AD и MSOnline устарели с 30 марта 2024 г. Дополнительные сведения см. в статье Обновление для прекращения поддержки. После этой даты поддержка этих модулей ограничивается поддержкой миграции пакета SDK Для Microsoft Graph PowerShell и исправлениями безопасности. Устаревшие модули будут работать до 30 марта 2025 г.

Мы рекомендуем выполнить миграцию в Microsoft Graph PowerShell для взаимодействия с Microsoft Entra ID (ранее Azure AD). Распространенные вопросы о миграции см. в разделе Вопросы и ответы о миграции. Примечание: В версиях 1.0.x MSOnline может возникнуть сбой после 30 июня 2024 г.

PowerShell для Azure AD
Microsoft Graph PowerShell

Откройте сеанс PowerShell и подключитесь к клиенту партнера, введя учетные данные администратора в окне входа.
```
Connect-AzureAd
```

Найдите группу Adminagents.

$group = Get-AzureADGroup -Filter "displayName eq 'Adminagents'"

Найдите субъект-службу с тем же, appId, что и у приложения.
```
$sp = Get-AzureADServicePrincipal -Filter "appId eq '{yourAppsAppId}'"
```

Добавьте субъект-службу в группу Adminagents.

Add-AzureADGroupMember -ObjectId $group.ObjectId -RefObjectId $sp.ObjectId

Откройте сеанс PowerShell и подключитесь к клиенту партнера, введя учетные данные администратора в окне входа.
```
Connect-MgGraph
```

Найдите группу Adminagents.

$group = Get-MgGroup -Filter "displayName eq 'Adminagents'"

Найдите субъект-службу с тем же, appId, что и у приложения.
```
$sp = Get-MgServicePrincipal -Filter "appId eq '{yourAppsAppId}'"
```
Добавьте субъект-службу в группу Adminagents.
```
New-MgGroupMember -GroupId $group.Id -DirectoryObjectId $sp.Id
```

Потоки получения маркеров

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

Помимо предварительно заданного доступа ко всем клиентам клиентов, приложения, управляемые партнерами, имеют еще одну возможность. Это позволяет агентам использовать приложение для доступа к данным клиента клиентов (используя делегированные права администратора). Концептуально это работает следующим образом:

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

Это стандартный поток предоставления кода авторизации, за исключением того, что агенты должны выполнять вход с помощью учетных записей партнеров. Чтобы увидеть, как это будет выглядеть, представьте, что клиент партнера является partner.com (который является домашним клиентом для ваших агентов), а один из ваших клиентов — customer.com:

Получите код авторизации: Приложение отправляет запрос к конечной точке /authorize и должно использовать клиент клиента, в нашем примере customer.com, для целевого клиента. Ваши агенты по-прежнему будут выполнять вход со своей username@partner.com учетной записью.
```
GET https://login.microsoftonline.com/customer.com/oauth2/authorize
```
Получите маркер доступа, используя код авторизации. Отправляя запрос в конечную точку token, приложение должно использовать домен клиента в качестве целевого домена, в нашем примере это customer.com:
```
POST https://login.microsoftonline.com/customer.com/oauth2/token
```
Теперь, когда у вас есть маркер доступа, вызовем Microsoft Graph, поместив маркер доступа в заголовок авторизации HTTP:
```
GET https://graph.microsoft.com/beta/users
Authorization: Bearer <token>
```

Регистрация приложения в доступных регионах

В настоящее время взаимодействие с клиентами CSP ограничено одним регионом. Приложения, управляемые партнерами, имеют такое же ограничение. Это означает, что у вас должен быть отдельный клиент для каждого региона, в который вы продаете. Например, если управляемое партнером приложение зарегистрировано в клиенте в США, а клиент находится в ЕС, приложение, управляемое партнером, не будет работать. Каждый из ваших региональных клиентов-партнеров должен поддерживать собственный набор приложений, управляемых партнером, для управления клиентами в одном регионе. Для этого может потребоваться дополнительная логика в вашем приложении (до входа), чтобы получить имя пользователя для входа клиентов, чтобы решить, какое удостоверение приложения, управляемое партнером, будет использоваться для обслуживания пользователя.

Вызов Microsoft Graph сразу же после создания пользователя

При создании нового клиента с помощью API Центра партнеров создается новый клиент клиента. Кроме того, создается партнерские отношения, что делает вас партнером записи для этого нового клиента. Распространение этих партнерских отношений в новом клиенте может занять до 3 минут. Если приложение вызывает Microsoft Graph сразу после создания, оно, скорее всего, получит сообщение об ошибке "Отказано в доступе". Аналогичная задержка может возникнуть, когда существующий клиент принимает ваше приглашение. Это связано с тем, что преконсент зависит от партнерских отношений, присутствующих в клиенте клиента.

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

Примечание: При повторной попытке необходимо получить новый маркер доступа от Microsoft Entra ID, прежде чем вызывать Microsoft Graph. Вызов Microsoft Graph с уже имеющимся у вас маркером доступа не будет работать, так как маркер доступа подходит в течение часа и не будет содержать предварительно разрешенные утверждения разрешений.