OAuth 2.0 授权代码授予用户登录并获取具有委派权限的令牌。 用户通过浏览器登录,Microsoft Entra ID返回生存期较短的授权代码,客户端在令牌终结点兑换代码。
代理 ID 解决方案可通过两种方式使用授权:
| 客户端类型 | 典型角色 | 客户端凭据 | PKCE |
|---|---|---|---|
| 公共客户端 | 本地代理直接登录用户。 | No | 必填 |
| 机密客户端 | 服务器端 Web 客户端在调用托管代理之前登录用户。 | 是的 | 推荐 |
使用Microsoft 身份验证库(MSAL)或Microsoft。Identity.Web 而不是直接创建这些请求。 本文中的请求显示了要引用的协议字段。
Warning
Microsoft 建议使用经认可的 SDK(如 Microsoft.Identity.Web 和 Microsoft Entra ID 身份验证 SDK(sidecar)库)来实现这些协议。 手动实现这些协议非常复杂且容易出错,并且使用 SDK 有助于确保安全性和符合最佳做法。
Important
公共客户端代理 ID 支持处于预览状态。 此预览版在没有服务级别协议的情况下提供,不建议用于生产工作负荷。 某些功能可能不受支持或功能受限。 有关详细信息,请参阅 联机服务的通用许可条款。
授权请求
这两种客户端类型将用户发送到租户的授权终结点:
GET https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize?
client_id={client-id}
&response_type=code
&redirect_uri={encoded-redirect-uri}
&response_mode=query
&scope=openid%20profile%20offline_access%20api://{resource-client-id}/{scope}
&state={random-state}
&nonce={random-nonce}
&code_challenge={pkce-challenge}
&code_challenge_method=S256
-
client_id标识公共或机密客户端。 基于 CIMD 的公共客户端使用其 HTTPS 元数据文档 URL 作为客户端 ID。 -
redirect_uri必须与为客户端配置的重定向 URI 完全匹配。 -
scope包含客户端请求的委托权限。 仅当客户端需要登录用户时,省略资源范围。 -
state将响应绑定到发起会话,并帮助防止跨站点请求伪造。 -
nonce将 OpenID Connect ID 令牌绑定到发起的会话。 -
code_challenge派生自使用 SHA-256 的高枚举 PKCE 验证程序。
登录并同意后,Microsoft Entra ID将浏览器重定向到已注册的重定向 URI:
GET {redirect-uri}?code={authorization-code}&state={state}
在兑换代码之前,请验证 state 并处理返回到重定向 URI 的任何 OAuth 错误。
公共客户端令牌请求
公共客户端无法保护客户端凭据。 它使用 PKCE 验证程序兑换代码:
POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={agent-id-client-id-or-cimd-url}
&grant_type=authorization_code
&code={authorization-code}
&redirect_uri={redirect-uri}
&scope=openid profile offline_access api://{resource-client-id}/{scope}
&code_verifier={pkce-verifier}
不要在此请求中发送客户端机密、证书断言或联合凭据。
已注册的公共客户端代理 ID 必须使用 单实例模式。 使用 客户端 ID 元数据文档 的客户端可以使用文档的 HTTPS URL 作为其客户端 ID。 有关实现指南,请参阅 从本地代理登录用户。
机密客户端令牌请求
机密客户端在可以保护凭据的服务器上运行。 服务器(而不是浏览器代码)兑换授权代码。 当授权请求使用 PKCE 时,请求包括客户端凭据和 PKCE 验证程序:
POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={confidential-client-id}
&grant_type=authorization_code
&code={authorization-code}
&redirect_uri={redirect-uri}
&scope=openid profile offline_access api://{agent-blueprint-client-id}/{scope}
&code_verifier={pkce-verifier}
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={signed-client-assertion}
此示例使用基于证书的客户端断言。 还支持客户端密码,但尽可能使用证书或工作负荷标识联合。
在托管代理 ID 解决方案中,机密客户端通常是上游 Web 应用程序,而不是子代理 ID。 请求访问令牌,其访问群体是托管代理的蓝图,将访问令牌发送到代理 API,并使用 On-Behalf-Of 流 调用下游 API。
对于单实例代理标识(预览), <agent-blueprint-client-id> 表示蓝图和代理标识共享的客户端 ID。 对于车队,它表示蓝图的客户端 ID,而不是单个子代理的 ID。 对于单实例模式,请在登录前通过 授予上游客户端访问权限 配置上游客户端的授权;浏览器同意不支持代理标识作为资源。
不要将授权代码或 ID 令牌发送到托管代理 API。 机密客户端模式中的子代理 ID 不会启动交互式 /authorize 请求。
令牌响应
如果请求成功,Microsoft Entra ID返回令牌,例如:
{
"token_type": "Bearer",
"scope": "api://<resource-client-id>/<scope>",
"expires_in": 3599,
"access_token": "<access-token>",
"refresh_token": "<refresh-token>",
"id_token": "<id-token>"
}
确切的响应取决于请求的范围:
- 仅对由其
aud声明标识的资源使用访问令牌。 - 使用 ID 令牌建立用户的登录会话,而不是调用 API。
- 当请求和策略允许脱机访问时,将返回刷新令牌。
安全要求
- 对公共客户端使用 PKCE 和
S256质询方法。 当库支持 PKCE 时,还对机密客户端使用 PKCE。 - 在授权和令牌请求中完全匹配重定向 URI。
- 为每个授权请求生成新的
statePKCEnonce验证程序。 - 仅从启动请求的客户端兑换一次授权代码。
- 不要记录授权代码、客户端凭据、访问令牌、刷新令牌或 ID 令牌。
- 验证 API 中的访问令牌。 不要将拥有授权代码或 ID 令牌视为 API 授权。