令牌发布者端点 - Amazon Cognito
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

令牌发布者端点

/oauth2/token 处的 OAuth 2.0 令牌端点会发放 JSON 网络令牌(JWT)。这些令牌是使用用户池进行身份验证的最终结果。这些令牌包含有关用户(ID 令牌)、用户的访问级别(访问令牌)以及用户保留其已登录会话的权利(刷新令牌)的信息。OpenID Connect(OIDC)依赖方库处理向此端点发出的请求以及来自此端点的响应有效载荷。令牌提供可验证的身份验证证明、配置文件信息以及用于访问后端系统的机制。

您的用户池 OAuth 2.0 授权服务器从令牌端点向以下类型的会话发放 JSON Web 令牌(JWT)。

  1. 已完成授权码授权请求的用户。成功兑换代码会返回 ID、访问令牌和刷新令牌。

  2. 已完成客户端凭证授权的机器对机器(M2M)会话。成功使用客户端机密进行授权会返回访问令牌。

  3. 之前已登录并收到刷新令牌的用户。刷新令牌身份验证会返回新的 ID 令牌和访问令牌。

    注意

    在托管 UI 中使用授权代码授权或通过联合身份验证登录的用户可以随时从令牌端点刷新其令牌。当记忆设备在您的用户池中处于活动状态时,使用 API 操作 InitiateAuthAdminInitiateAuth 登录的用户可以使用令牌端点刷新其令牌。如果记忆设备处于活动状态,则使用 InitiateAuthAdminInitiateAuth API 请求中 REFRESH_TOKEN_AUTHAuthFlow 来刷新令牌。

当您向用户池添加域时,令牌端点将公开可用。它接受 HTTP POST 请求。为了实现应用程序安全性,请将 PKCE 与授权代码登录事件结合使用。PKCE 会验证传递授权码的用户是否与经过身份验证的用户相同。有关 PKCE 的更多信息,请参阅 IETF RFC 7636

要详细了解用户池应用程序客户端及其授权类型、客户端机密、授权范围和客户端 ID,请访问特定于应用程序的应用程序客户端设置。要详细了解 M2M 授权、客户端凭证授权以及使用访问令牌范围的授权,请访问范围、M2M 和带资源服务器的 API

要从用户的访问令牌中检索有关用户的信息,可以将其传递给 userInfo 端点GetUser API 请求。

POST /oauth2/token

/oauth2/token 端点只支持 HTTPS POST。您的应用程序直接对此端点发出请求,而不通过用户浏览器。

令牌端点支持 client_secret_basicclient_secret_post 身份验证。有关 OpenID Connect 规范的更多信息,请参阅客户端身份验证。有关 OpenID Connect 规范中令牌端点的更多信息,请参阅令牌端点

标头中的请求参数

Authorization

如果向客户端发布了密钥,则客户端可以在授权标头中将其 client_idclient_secret 作为 client_secret_basic HTTP 授权传递。您还可以在请求正文中包含 client_idclient_secret 作为 client_secret_post 授权。

授权标头字符串是 基本 Base64Encode(client_id:client_secret)。以下示例是具有客户端密钥 abcdef01234567890 的应用程序客户端 djc98u3jiedmi283eu928 的授权标头,其使用字符串 djc98u3jiedmi283eu928:abcdef01234567890 的 Base64 编码版本:

Authorization: Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw
Content-Type

将此参数的值设置为 'application/x-www-form-urlencoded'

正文中的请求参数

grant_type

(必需)要请求的 OIDC 授予的类型。

必须为 authorization_coderefresh_tokenclient_credentials。在以下条件下,您可以从令牌端点请求自定义范围的访问令牌:

  • 您在应用程序客户端配置中启用请求的范围。

  • 您为应用程序客户端配置了客户端密钥。

  • 您在应用程序客户端中启用客户端凭证授予。

client_id

(可选)用户池中应用程序客户端的 ID。指定对用户进行身份验证的同一个应用程序客户端。

如果客户端为公有且没有密钥,或在 client_secret_post 授权中有 client_secret,则必须提供此参数。

client_secret

(可选)对用户进行身份验证的应用程序客户端的客户端密钥。如果您的应用程序客户端具有客户端密钥,并且您未发送 Authorization 标头,则为必需的。

scope

(可选)可以是与应用程序客户端关联的任何自定义范围的组合。必须为应用程序客户端激活您请求的任何范围。如果未激活,Amazon Cognito 会忽略它。如果客户端不请求任何范围,则身份验证服务器将分配您在应用程序客户端配置中授权的所有自定义范围。

仅当 grant_typeclient_credentials 时使用。

redirect_uri

(可选)必须是用于在 /oauth2/authorize 中获取 authorization_code 的相同 redirect_uri

如果 grant_typeauthorization_code,则必须提供此参数。

refresh_token

(可选)要为用户的会话生成新的访问令牌和 ID 令牌,请将您的 /oauth2/token 请求中的 refresh_token 参数的值设置为同一个应用程序客户端中以前颁发的刷新令牌。

code

(可选)来自授权代码授予的授权代码。如果授权请求包括 authorization_codegrant_type,则必须提供此参数。

code_verifier

(可选)您在 PKCE 的授权代码授予请求中用来计算 code_challenge 的任意值。

具有正向响应的示例请求

为获取令牌交换授权代码

示例:POST 请求

POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token& Content-Type='application/x-www-form-urlencoded'& Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw grant_type=authorization_code& client_id=1example23456789& code=AUTHORIZATION_CODE& redirect_uri=com.myclientapp://myclient/redirect

示例:响应

HTTP/1.1 200 OK Content-Type: application/json { "access_token": "eyJra1example", "id_token": "eyJra2example", "refresh_token": "eyJj3example", "token_type": "Bearer", "expires_in": 3600 }
注意

仅当 grant_typeauthorization_code 时,令牌端点才返回 refresh_token

用客户端凭证交换访问令牌:授权标头中的客户端密钥

示例:POST 请求

POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token > Content-Type='application/x-www-form-urlencoded'& Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw grant_type=client_credentials& client_id=1example23456789& scope=resourceServerIdentifier1/scope1 resourceServerIdentifier2/scope2

示例:响应

HTTP/1.1 200 OK Content-Type: application/json { "access_token": "eyJra1example", "token_type": "Bearer", "expires_in": 3600 }

用客户端凭证交换访问令牌:请求正文中的客户端密钥

示例:POST 请求

POST /oauth2/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded X-Amz-Target: AWSCognitoIdentityProviderService.Client credentials request User-Agent: USER_AGENT Accept: / Accept-Encoding: gzip, deflate, br Content-Length: 177 Referer: http://auth.example.com/oauth2/token Host: auth.example.com Connection: keep-alive grant_type=client_credentials&client_id=1example23456789&scope=my_resource_server_identifier%2Fmy_custom_scope&client_secret=9example87654321

示例:响应

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Date: Tue, 05 Dec 2023 16:11:11 GMT x-amz-cognito-request-id: 829f4fe2-a1ee-476e-b834-5cd85c03373b { "access_token": "eyJra12345EXAMPLE", "expires_in": 3600, "token_type": "Bearer" }

为获取令牌交换具有 PKCE 的授权代码授予

示例:POST 请求

POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token Content-Type='application/x-www-form-urlencoded'& Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw grant_type=authorization_code& client_id=1example23456789& code=AUTHORIZATION_CODE& code_verifier=CODE_VERIFIER& redirect_uri=com.myclientapp://myclient/redirect

示例:响应

HTTP/1.1 200 OK Content-Type: application/json { "access_token": "eyJra1example", "id_token": "eyJra2example", "refresh_token": "eyJj3example", "token_type": "Bearer", "expires_in": 3600 }
注意

仅当 grant_typeauthorization_code 时,令牌端点才返回 refresh_token

为获取令牌交换刷新令牌

示例:POST 请求

POST https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/token > Content-Type='application/x-www-form-urlencoded'& Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw grant_type=refresh_token& client_id=1example23456789& refresh_token=eyJj3example

示例:响应

HTTP/1.1 200 OK Content-Type: application/json { "access_token": "eyJra1example", "id_token": "eyJra2example", "token_type": "Bearer", "expires_in": 3600 }
注意

仅当 grant_typeauthorization_code 时,令牌端点才返回 refresh_token

负向响应的示例

示例:错误响应

HTTP/1.1 400 Bad Request Content-Type: application/json;charset=UTF-8 { "error":"invalid_request|invalid_client|invalid_grant|unauthorized_client|unsupported_grant_type" }
invalid_request

请求缺少必需的参数、包括不支持的参数值(除了 unsupported_grant_type 之外)或者格式错误。例如,grant_typerefresh_token,但未包括 refresh_token

invalid_client

客户端身份验证失败。例如,客户端的授权标头中包含 client_idclient_secret,但没有这样的客户端带有 client_idclient_secret

invalid_grant

已撤销刷新令牌。

授权代码已使用或不存在。

应用程序客户端对请求的范围内的所有属性都没有读取权限。例如,您的应用程序请求 email 范围,应用程序客户端可以读取 email 属性,但不能读取 email_verified

unauthorized_client

客户端不允许代码授予流或刷新令牌。

unsupported_grant_type

如果 grant_typeauthorization_coderefresh_tokenclient_credentials 之外的任意内容,则返回。