OAuth 2.0 授权代码授予

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。
  • 为每个授权请求生成新的 statePKCE nonce验证程序。
  • 仅从启动请求的客户端兑换一次授权代码。
  • 不要记录授权代码、客户端凭据、访问令牌、刷新令牌或 ID 令牌。
  • 验证 API 中的访问令牌。 不要将拥有授权代码或 ID 令牌视为 API 授权。