令牌发布者端点
/oauth2/token
处的 OAuth 2.0 令牌端点
您的用户池 OAuth 2.0 授权服务器从令牌端点向以下类型的会话发放 JSON Web 令牌(JWT)。
-
已完成授权码授权请求的用户。成功兑换代码会返回 ID、访问令牌和刷新令牌。
-
已完成客户端凭证授权的机器对机器(M2M)会话。成功使用客户端机密进行授权会返回访问令牌。
-
之前已登录并收到刷新令牌的用户。刷新令牌身份验证会返回新的 ID 令牌和访问令牌。
注意
在托管 UI 中使用授权代码授权或通过联合身份验证登录的用户可以随时从令牌端点刷新其令牌。当记忆设备在您的用户池中未处于活动状态时,使用 API 操作
InitiateAuth
和AdminInitiateAuth
登录的用户可以使用令牌端点刷新其令牌。如果记忆设备处于活动状态,则使用InitiateAuth
或AdminInitiateAuth
API 请求中REFRESH_TOKEN_AUTH
的AuthFlow
来刷新令牌。
当您向用户池添加域时,令牌端点将公开可用。它接受 HTTP POST 请求。为了实现应用程序安全性,请将 PKCE 与授权代码登录事件结合使用。PKCE 会验证传递授权码的用户是否与经过身份验证的用户相同。有关 PKCE 的更多信息,请参阅 IETF RFC 7636
要详细了解用户池应用程序客户端及其授权类型、客户端机密、授权范围和客户端 ID,请访问特定于应用程序的应用程序客户端设置。要详细了解 M2M 授权、客户端凭证授权以及使用访问令牌范围的授权,请访问范围、M2M 和带资源服务器的 API。
要从用户的访问令牌中检索有关用户的信息,可以将其传递给 userInfo 端点 或 GetUser API 请求。
POST /oauth2/token
/oauth2/token
端点只支持 HTTPS POST
。您的应用程序直接对此端点发出请求,而不通过用户浏览器。
令牌端点支持 client_secret_basic
和 client_secret_post
身份验证。有关 OpenID Connect 规范的更多信息,请参阅客户端身份验证
标头中的请求参数
Authorization
-
如果向客户端发布了密钥,则客户端可以在授权标头中将其
client_id
和client_secret
作为client_secret_basic
HTTP 授权传递。您还可以在请求正文中包含client_id
和client_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_code
、refresh_token
或client_credentials
。在以下条件下,您可以从令牌端点请求自定义范围的访问令牌:-
您在应用程序客户端配置中启用请求的范围。
-
您为应用程序客户端配置了客户端密钥。
-
您在应用程序客户端中启用客户端凭证授予。
-
client_id
-
(可选)用户池中应用程序客户端的 ID。指定对用户进行身份验证的同一个应用程序客户端。
如果客户端为公有且没有密钥,或在
client_secret_post
授权中有client_secret
,则必须提供此参数。 client_secret
-
(可选)对用户进行身份验证的应用程序客户端的客户端密钥。如果您的应用程序客户端具有客户端密钥,并且您未发送
Authorization
标头,则为必需的。 scope
-
(可选)可以是与应用程序客户端关联的任何自定义范围的组合。必须为应用程序客户端激活您请求的任何范围。如果未激活,Amazon Cognito 会忽略它。如果客户端不请求任何范围,则身份验证服务器将分配您在应用程序客户端配置中授权的所有自定义范围。
仅当
grant_type
为client_credentials
时使用。 redirect_uri
-
(可选)必须是用于在
/oauth2/authorize
中获取authorization_code
的相同redirect_uri
。如果
grant_type
是authorization_code
,则必须提供此参数。 refresh_token
-
(可选)要为用户的会话生成新的访问令牌和 ID 令牌,请将您的
/oauth2/token
请求中的refresh_token
参数的值设置为同一个应用程序客户端中以前颁发的刷新令牌。 code
-
(可选)来自授权代码授予的授权代码。如果授权请求包括
authorization_code
的grant_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_type
为 authorization_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_type
为 authorization_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_type
为 authorization_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_type
是refresh_token
,但未包括refresh_token
。 invalid_client
-
客户端身份验证失败。例如,客户端的授权标头中包含
client_id
和client_secret
,但没有这样的客户端带有client_id
和client_secret
。 invalid_grant
-
已撤销刷新令牌。
授权代码已使用或不存在。
应用程序客户端对请求的范围内的所有属性都没有读取权限。例如,您的应用程序请求
email
范围,应用程序客户端可以读取email
属性,但不能读取email_verified
。 unauthorized_client
-
客户端不允许代码授予流或刷新令牌。
unsupported_grant_type
-
如果
grant_type
是authorization_code
、refresh_token
或client_credentials
之外的任意内容,则返回。