代币发行者端点 - Amazon Cognito

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

代币发行者端点

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

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

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

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

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

    注意

    在托管用户界面中使用授权码授权或通过联合身份登录的用户可以随时从令牌端点刷新其令牌。当记住的设备在您的用户池中处于活动状态时,使用API操作登录InitiateAuthAdminInitiateAuth可以使用令牌端点刷新令牌的用户。如果记住的设备处于活动状态,请使用of in AuthFlow InitiateAuthAdminInitiateAuthAPI请求刷新令牌。REFRESH_TOKEN_AUTH

当您向用户池添加域时,令牌端点将公开可用。它接受HTTPPOST请求。为了确保应用程序安全,请PKCE与您的授权码登录事件一起使用。PKCE验证传递授权码的用户是否与经过身份验证的用户相同。有关的更多信息PKCE,请参阅 IETFRFC7636

要详细了解用户池应用程序客户端及其授权类型、客户端密钥、授权范围和客户端,请IDs访问使用应用程序客户端进行特定于应用程序的设置。要详细了解 M2M 授权、客户凭证授予以及使用访问令牌范围的授权,请访问。作用域、M2M APIs 和资源服务器

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

POST/oauth2/token

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

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

标头中的请求参数

Authorization

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

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

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

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

仅当 grant_typeclient_credentials 时使用。

redirect_uri

(可选)必须与进入authorization_coderedirect_uri使用的相同/oauth2/authorize

如果grant_type是,则必须提供此参数authorization_code

refresh_token

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

code

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

code_verifier

(可选)您在授权码授权请求code_challenge中用来计算的任意值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& 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 之外的任意内容,则返回。