注册代理,以便它可以通过Microsoft Entra ID进行身份验证,并请求访问 API。 此设置为代理创建一个标识,由其安装或副本共享。
此过程使用 Microsoft Graph beta 版。 对于云代理,请为其运行时配置凭据。 对于安装在最终用户设备上的代理,请使用没有凭据的公共客户端重定向配置。 呼叫教程标识所需的部分。
Important
单实例代理标识以预览版提供。 此预览版在没有服务级别协议的情况下提供,不建议用于生产工作负荷。 某些功能可能不受支持或功能受限。 有关详细信息,请参阅 联机服务的通用许可条款。
Prerequisites
- 在 Microsoft Graph 中启用了单实例预配的 Microsoft Entra 租户 在开始之前,请与Microsoft代表确认预览版可用性和租户启用。 若要在设置后请求令牌,还确认已启用单实例身份验证;单独启用预配和身份验证。
- 有权创建和更新代理标识蓝图和代理标识的帐户,例如 代理 ID 管理员。
- 一个单独的单租户公共管理应用,已获得管理员同意,可使用委派的 Microsoft Graph 权限
AgentIdentityBlueprint.ReadWrite.All和AgentIdentity.ReadWrite.All,或有权设置管理客户端。 - 可以向管理应用的 Graph 权限授予许可的管理员。
- 可分配为蓝图发起人的用户的对象 ID。 这些示例还将该用户分配为所有者。
- 对于交互式登录,适用于客户端类型的重定向 URI。 对于基于浏览器的管理员同意,即使代理仅在运行时使用客户端凭据,也需要一个
web重定向 URI。 - 对于本地机密客户端测试,需要 X.509 证书及其私钥的安全存储。 Azure托管代理可以改用托管标识联合凭据。 仅公共客户端不需要凭据。
- 对于 API 访问,您需要提供资源应用程序的客户端 ID,以及代理所需的委派权限或应用角色的 ID。
按如下所述通过 Microsoft Graph PowerShell 运行 HTTP 示例,或使用可以发送 JSON 请求正文和标头的 REST 客户端。 在 REST 客户端中,在每个 Graph 请求的 Authorization 标头中将管理令牌作为 Bearer 令牌发送。 切勿将代理的运行时访问令牌用于管理请求。
确认管理员交接
在创建对象之前,请就以下交接达成一致。 管理同意和代理的运行时 API 同意是单独的审批。
| 谁 | Action | 何时就绪 |
|---|---|---|
| 租户管理员和Microsoft代表。 | 确认已启用预览预配和身份验证。 | 租户支持此设置的注册和令牌请求。 |
| 授权管理员。 | 批准上面列出的管理客户端的两个 Graph 权限。 | 操作员可以使用两个已获同意的范围权限登录到该客户端。 |
| 开发人员或授权操作员。 | 完成下面的注册步骤。 | 已记录蓝图对象 ID、代理标识对象 ID 和共享客户端 ID。 |
| API 所有者和同意管理员。 | 提供 API 标识符并批准调用教程所需的权限。 | 所需的运行时授权会在首次 API 调用前得到验证。 |
向管理员发送租户 ID、管理客户端 ID 和请求的 API 权限。 将 标识符工作表 与设置步骤一起保留。
如果遵循本地 HTTPS 教程,请在浏览器登录之前确认计算机上信任开发 HTTPS 证书。 遵循组织的信任过程,而不是禁用 TLS 验证。
设置管理客户端
管理客户端登录管理员或授权操作员以创建代理的注册。 它独立于代理的运行时标识。 现有的Azure CLI登录不建立此管理上下文。
在同一租户中注册应用程序。 选择仅限此组织目录中的帐户选项。 在“身份验证”下,添加
http://localhost平台,并使用重定向 URI 。在 API 权限下,添加以下Microsoft Graph>委派权限:
-
AgentIdentityBlueprint.ReadWrite.All。 -
AgentIdentity.ReadWrite.All。
-
拥有授权的管理员授予对这些权限的同意。 有关管理员同意的信息,请参阅Microsoft 标识平台 中的权限和同意。
安装 Microsoft Graph PowerShell 身份验证模块,并使用管理应用登录。
Connect-MgGraph打开已登录用户的浏览器:Install-Module Microsoft.Graph.Authentication -Scope CurrentUser Connect-MgGraph ` -ClientId "<management-app-client-id>" ` -TenantId "<tenant-id>" ` -Scopes "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentity.ReadWrite.All" ` -ContextScope Process $context = Get-MgContext if (-not $context -or -not $context.Account) { throw "Microsoft Graph sign-in didn't establish a delegated management context. Stop before creating objects." } $context | Select-Object Account, TenantId, ClientId, Scopes确认
Account并TenantIdClientId标识预期的操作员、租户和管理应用,并包括这两个Scopes权限。 如果范围缺失或再次请求同意,请停止并让授权管理员在继续之前验证应用注册和同意。
在 Windows 上,如果 Connect-MgGraph 在登录前因 必须配置窗口句柄 而失败,请对自定义管理客户端使用 文档记录的浏览器登录选项:
Set-MgGraphOption -DisableLoginByWAM $true
再次运行相同的 Connect-MgGraph 命令。 这会更改身份验证 UI,而不是租户的访问要求;请以授权操作员身份完成登录,不要绕过因合规性被拒绝的限制。 该设置在不同 PowerShell 会话之间持续生效。 如果在此更改之前启用了 WAM,完成后请使用 Set-MgGraphOption -DisableLoginByWAM $false 将其还原。
使用 Invoke-MgGraphRequest 运行 HTTP 示例,而无需复制或显示访问令牌。 例如,将 JSON 正文从 “创建蓝图 ”复制到该蓝图中 $body,替换发起人占位符:
$body = @'
<JSON-request-body>
'@
$blueprint = Invoke-MgGraphRequest -Method POST `
-Uri "https://graph.microsoft.com/beta/applications" `
-Headers @{ "OData-Version" = "4.0" } `
-ContentType "application/json" -Body $body
$blueprintObjectId = $blueprint.id
$agentClientId = $blueprint.appId
对于以后的请求,请使用每个 HTTP 示例中所示的方法、完整 URI、标头和 JSON 正文。 对于 GET 请求,省略 -Body。 该模块提供授权标头。 有关命令语法,请参阅 Invoke-MgGraphRequest。
如果注册或管理员同意被拒绝,请让租户管理员完成此设置。 不要向代理授予这些管理权限,以解决授权错误。
创建蓝图
蓝图是保存代理的身份验证设置和凭据的注册信息。
创建蓝图,并将
isSingleInstance设置为true。 将<sponsor-user-object-id>替换为发起人的对象 ID。 需要赞助人;所有者分配是可选的。在本教程中保留
isSingleInstance: true:它为代理创建一个标识,包括其安装或副本。 创建后无法更改此属性。POST https://graph.microsoft.com/beta/applications OData-Version: 4.0 Content-Type: application/json { "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint", "displayName": "Contoso Operations Agent", "signInAudience": "AzureADMyOrg", "isSingleInstance": true, "sponsors@odata.bind": [ "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>" ], "owners@odata.bind": [ "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>" ] }从
201 Created响应中保存以下值:-
id:蓝图的对象 ID,用于在Microsoft Graph中对其进行寻址。 -
appId:OAuth 请求中使用的应用程序(客户端)ID。
-
该示例创建一个将 设置为 的单租户蓝图。
预配代理标识
独立于其蓝图注册创建标识。 按照以下请求直接执行;此设置不需要蓝图主体身份。
创建代理 ID。 将
agentIdentityBlueprintId设置为蓝图的对象 ID,而不是其appId。POST https://graph.microsoft.com/beta/servicePrincipals/microsoft.graph.agentIdentity OData-Version: 4.0 Content-Type: application/json { "displayName": "Contoso Operations Agent", "agentIdentityBlueprintId": "<blueprint-object-id>", "sponsors@odata.bind": [ "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>" ] }从
id响应中保存标识的201 Created。 这是代理标识的对象 ID,而不是蓝图对象 ID 或 OAuth 客户端 ID。读取标识以验证结果:
GET https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-object-id>?$select=id,appId,displayName,agentIdentityBlueprintId,instanceMode检查返回的值:
Property 预期值 @odata.type#microsoft.graph.agentIdentity。appId蓝图的 appId.agentIdentityBlueprintId蓝图的对象 ID。 instanceModesingleInstance。
不要为每个安装、进程或用户会话预配新标识。 它们使用相同的客户端 ID。
配置重定向 URI
对于授权代码流,请在与客户端匹配的平台下注册重定向 URI。 机密客户端使用 web;公共客户端使用 publicClient。
基于浏览器的管理员同意过程还需要web重定向 URI,即使对于仅在运行时使用客户端凭据的代理也是如此。 重定向 URI 处理同意回调,而不是客户端凭据令牌请求。 仅当既不需要授权代码流,也不需要基于浏览器的管理员同意时,才跳过本部分。
读取当前重定向配置:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,web,publicClient更新相应的重定向集合。 以下示例显示了这两种客户端类型;仅包含代理程序使用的平台。 保留仍需要的所有现有重定向 URI。
PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id> OData-Version: 4.0 Content-Type: application/json { "@odata.type": "#microsoft.graph.agentIdentityBlueprint", "web": { "redirectUris": [ "https://agent.contoso.com/signin" ] }, "publicClient": { "redirectUris": [ "http://localhost" ] } }成功的更新返回
204 No Content。 重定向 URI 集合会被替换,而不是追加。 请勿用此示例覆盖现有配置而不保留其 URI。
同一蓝图可以注册两个平台。 每个授权请求都使用其客户端类型对应的重定向 URI。 即使机密组件在同一蓝图上使用证书,公共客户端也不会发送凭据。 不要更改 isFallbackPublicClient 来在这些授权代码方案之间切换。
为机密客户端添加证书
对于本地机密客户端测试,请仅在应用清单上注册公共证书。 运行时保留用于身份验证的私钥。
对于纯公共客户端,请跳过此部分。 对于使用托管标识联合的Azure托管代理,请改为配置联合凭据,然后继续声明 API 权限。
对于Windows开发计算机,可以创建自签名证书并导出其公共证书和受密码保护的 PFX。 将 PFX 保留在源树之外。 请使用用于下方 key 的 Base64 编码 DER 公共证书,而不是 PFX 或 PEM 文件的页眉和页脚。 例如:
$publicCertificate = Get-PfxCertificate -FilePath "<absolute-path-to-public-cer>"
$publicCertificateBase64 = [Convert]::ToBase64String($publicCertificate.RawData)
粘贴 $publicCertificateBase64 到注册请求中。 公共值不是凭据;而 PFX 及其密码才是凭据。 对于非Windows开发或生产,请使用组织的证书颁发和私钥存储过程。
读取当前证书集合:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,keyCredentials在保留仍需要的任何现有密钥凭据的同时添加公共证书。 以下请求显示没有现有证书的初始注册:
PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id> OData-Version: 4.0 Content-Type: application/json { "@odata.type": "#microsoft.graph.agentIdentityBlueprint", "keyCredentials": [ { "type": "AsymmetricX509Cert", "usage": "Verify", "key": "<base64-encoded-DER-certificate>", "displayName": "Contoso Operations Agent certificate" } ] }成功的更新返回
204 No Content。 切勿上传私钥,也不要将其随公共客户端分发。
有关证书格式和客户端断言指南,请参阅Microsoft 标识平台证书凭据。
声明 API 权限
仅声明代理所需的权限。 使用 Scope 表示委派权限,使用 Role 表示应用程序权限。
resourceAccess 中的这些值是资源应用程序公开的权限 ID,而不是权限名称。
读取当前声明:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,requiredResourceAccess添加资源和权限条目,保留仍然需要的现有声明。 该示例显示了一个委派权限和一个应用程序权限;如果你的代理不需要其中之一,请删除任一条目。
PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id> OData-Version: 4.0 Content-Type: application/json { "@odata.type": "#microsoft.graph.agentIdentityBlueprint", "requiredResourceAccess": [ { "resourceAppId": "<resource-app-id>", "resourceAccess": [ { "id": "<delegated-permission-id>", "type": "Scope" }, { "id": "<app-role-id>", "type": "Role" } ] } ] }成功的更新返回
204 No Content。
这些声明不授予访问权限。 用户或管理员同意会授予委派权限,管理员授予应用程序权限。 这些授权直接属于代理 ID。
如果代理还接收来自前端应用程序的请求,请 在蓝图上公开标识符 URI 和委托范围。 保留任何现有 API 范围,并将 requestedAccessTokenVersion 设置为 2。 前端请求该作用域以获取其受众为共享客户端 ID 的令牌。
Graph 请求疑难解答
如果请求失败,请在更改权限或重试操作之前检查 HTTP 状态和 Graph 错误响应。
| Response | 检查 |
|---|---|
400 Bad Request |
读取 error.code 和 error.message。 检查终结点的请求架构、所需的发起人引用、对象 ID 和属性值。 |
401 Unauthorized |
获取 Microsoft Graph 的有效访问令牌,并在 Authorization 标头中发送它。 |
403 Forbidden |
确认管理应用已具有所需的委派权限并已获得管理员同意、已登录用户有权执行该操作,并且租户已启用预览。 |
有关详细信息,请参阅Microsoft Graph错误响应。 联系管理员或 Microsoft 支持人员时,请提供 HTTP 状态、错误代码和 request-id 响应标头。 不要包含访问令牌或其他凭据。
后续步骤
返回到引导你来到这里的教程:
- 对 ASP.NET Core代理 API 的用户进行身份验证。
- 使用 ASP.NET Core 调用自定义 API 作为代理。
- 配置 Auth SDK Sidecar。
- 通过终端用户设备上的代理让用户登录。
有关直接 OAuth 请求以及此设置背后的身份模型,请参阅 验证代理身份 和 代理身份蓝图实例模式。