从云解决方案提供商应用程序中调用 Microsoft Graph

项目
04/09/2024

注意： 本主题 仅适用于 Microsoft 云解决方案提供商 (CSP) 应用程序开发人员。 Microsoft 云解决方案提供商 (CSP) 计划使 Microsoft 的合作伙伴能够向客户转售和管理 Microsoft Online 服务。

本文介绍如何使用授权代码授予流或服务服务客户端凭据流通过 Microsoft Graph 启用对合作伙伴管理的客户数据的应用程序访问。

重要

仅用户、组、设备、组织) 和Intune资源等目录资源 (支持从 CSP 应用程序调用 Microsoft Graph。

什么是合作伙伴托管的应用程序

CSP 计划使 Microsoft 的合作伙伴能够向客户转售和管理 Microsoft Online Services (，例如 Microsoft 365、Microsoft Azure 和 CRM Online) 。客户服务的管理是通过委派管理员特权完成的，它使指定的合作伙伴用户 (称为代理) 访问和配置其客户的环境。

此外，作为合作伙伴开发人员，你可以构建 合作伙伴管理的应用 来管理客户的 Microsoft 服务。合作伙伴托管的应用通常称为预先接受的应用，因为所有客户都会自动预先接受合作伙伴管理的应用。这意味着，当某个客户租户中的用户使用某个合作伙伴托管的应用时，用户无需系统提示同意即可使用它。合作伙伴托管的应用还继承了委托管理员特权，因此合作伙伴代理还可以通过合作伙伴托管的应用程序获得对客户的特权访问权限。

如何设置合作伙伴托管的应用程序

被授予访问客户数据的提升权限时，应用程序被视为合作伙伴托管。

注意：合作伙伴托管的应用仅可以在合作伙伴租户中配置，为管理客户租户资源，合作伙伴托管的应用必须配置为多租户应用程序。

注册和配置多租户应用

此处所需的初始步骤遵循注册和配置多租户应用程序所用的大部分步骤：

使用 Microsoft Entra 管理中心在合作伙伴租户中注册应用程序。若要充当合作伙伴管理的应用，必须将应用程序配置为多租户应用。此外，如果你的应用在多个地理区域中部署和销售，则需要在每个区域注册应用，如此处所述。
再次通过Microsoft Entra 管理中心配置多租户应用，并具有使用最低特权方法所需的权限。

为所有客户预先提供应用

最后，向合作伙伴管理的应用授予所有客户的配置权限。为此，可以使用 Azure AD PowerShell V2 或 Microsoft Graph PowerShell 将代表应用的 servicePrincipal 添加到合作伙伴租户中的 Adminagents 组。按照以下步骤查找 Adminagents 组 servicePrincipal 并将其添加到该组。

注意

自 2024 年 3 月 30 日起，Azure AD 和 MSOnline PowerShell 模块已弃用。若要了解详细信息，请阅读弃用更新。在此日期之后，对这些模块的支持仅限于 Microsoft Graph PowerShell SDK 和安全修补程序的迁移帮助。弃用的模块将继续运行到 2025 年 3 月 30 日。

建议迁移到 Microsoft Graph PowerShell，以便与以前为 Azure AD) Microsoft Entra ID (交互。有关常见的迁移问题，请参阅迁移常见问题解答。 注意： MSOnline 1.0.x 版可能会在 2024 年 6 月 30 日之后遇到中断。

Azure AD PowerShell
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
```
使用授权代码获取访问令牌：在我们的示例 customer.com 中，当对 token 终结点发出请求时，你的应用必须将客户租户用作目标租户：
```
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 Graph 之前从 Microsoft Entra ID 获取新的访问令牌。使用你已有的访问令牌调用 Microsoft Graph 将不起作用，因为访问令牌适用于一小时，并且不包含预先同意的权限声明。