本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
AUTHORIZATION 终端节点
/oauth2/authorize
终端节点让用户登录。
GET /oauth2/authorize
的 /oauth2/authorize
端点仅支持 HTTPS GET
。用户池客户端通常通过浏览器发出此请求。Web 浏览器包括 Chrome 或 Firefox。Android 浏览器包括自定义 Chrome 选项卡。iOS 浏览器包括
Safari View 控件。
授权服务器在访问授权终端节点时需要 HTTPS 而不是 HTTP 作为协议。有关规范的更多信息,请参阅授权终端节点
请求参数
- response_type
-
响应类型。必须
code
或token
。指示客户端是否想要为最终用户提供授权代码(授权代码授予流)或直接为最终用户发行令牌(隐式流)。必填
- client_id
-
客户端 ID。
必须是在用户池中预注册的客户端,并且必须已启用联合功能。
必填
- redirect_uri
-
在用户授权之后,身份验证服务器将浏览器重定向到的 URL。
重定向 URI 必须:
-
是绝对 URI。
-
已预先向客户端注册。
-
不包含片段组件。
请参阅 OAuth 2.0 – 重定向终端节点
。 Amazon Cognito 需要基于
HTTP
的HTTPS
,对于仅用于测试目的的http://localhost
除外。应用程序回调 URL(如
myapp://example
)也受支持。必填
-
- state
-
客户端添加到初始请求的不透明值。授权服务器在重定向回客户端时包括此值。
客户端必须使用此值来防止 CSRF
攻击。 此值可选,但强烈建议使用。
- identity_provider
-
由开发人员直接用来在特定提供商处进行身份验证。
-
对于社交登录,有效值为 Facebook、Google、LoginWithAmazon 和 SignInWithApple。
-
对于 Amazon Cognito 用户池,有效值为 COGNITO。
-
对于其他身份提供商,这将是您在用户池中分配给 IdP 的名称。
:可选。
-
- idp_identifier
-
由开发人员用于映射到提供商名称而不公开提供商名称。
:可选。
- scope
-
可以是任何系统预留范围或与客户端关联的自定义范围的组合。范围必须以空格分隔。系统保留的范围是
openid
,email
,phone
,profile
、和aws.cognito.signin.user.admin
。所使用的任何范围必须与客户端预先关联,否则将在运行时忽略。如果客户端不请求任何范围,则身份验证服务器使用与客户端关联的所有范围。
如果请求
openid
范围,则只返回 ID 令牌。如果请求aws.cognito.signin.user.admin
范围,则访问令牌只能用于 Amazon Cognito 用户池。如果同时请求了phone
范围,则只能请求email
、profile
和openid
范围。这些范围控制进入 ID 令牌中的声明。:可选。
- code_challenge_method
-
用于生成质询的方法。PKCE RFC
定义两个方法:S256 和 plain;但是,Amazon Cognito 身份验证服务器仅支持 S256。 :可选。
- code_challenge
-
从
code_verifier
生成的质询。仅在指定
code_challenge_method
时必需。
具有正向响应的示例请求
授予授权代码
示例请求
GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize? response_type=code& client_id=ad398u21ijw3s9w3939& redirect_uri=https://YOUR_APP/redirect_uri& state=STATE& scope=openid+profile+aws.cognito.signin.user.admin
示例响应
Amazon Cognito 身份验证服务器使用授权代码和状态重定向回您的应用程序。代码和状态必须在查询字符串参数中返回,而不是在片段中。查询字符串是 Web 请求的一部分,显示在 字符之后;该字符串可以包含一个或多个使用 字符分隔的参数。片段是 Web 请求中显示在“#”字符后的部分,用于指定文档的子部分。
HTTP/1.1 302 Found
Location: https://YOUR_APP/redirect_uri?code=AUTHORIZATION_CODE&state=STATE
具有 PKCE 的授权代码授予
示例请求
GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize? response_type=code& client_id=ad398u21ijw3s9w3939& redirect_uri=https://YOUR_APP/redirect_uri& state=STATE& scope=aws.cognito.signin.user.admin& code_challenge_method=S256& code_challenge=CODE_CHALLENGE
示例响应
身份验证服务器使用授权代码和状态重定向回您的应用程序。代码和状态必须在查询字符串参数中返回,而不是在片段中。
HTTP/1.1 302 Found
Location: https://YOUR_APP/redirect_uri?code=AUTHORIZATION_CODE&state=STATE
不带 openid
范围的令牌授予
示例请求
GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize? response_type=token& client_id=ad398u21ijw3s9w3939& redirect_uri=https://YOUR_APP/redirect_uri& state=STATE& scope=aws.cognito.signin.user.admin
示例响应
Amazon Cognito 授权服务器重定向回您的应用程序,带有访问令牌。由于未请求 openid
范围,不会返回 ID 令牌。此流中从不返回刷新令牌。令牌和状态在片段中返回,而不是在查询字符串中。
HTTP/1.1 302 Found
Location: https://YOUR_APP/redirect_uri#access_token=ACCESS_TOKEN&token_type=bearer&expires_in=3600&state=STATE
具有 openid
范围的令牌授予
示例请求
GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize? response_type=token& client_id=ad398u21ijw3s9w3939& redirect_uri=https://YOUR_APP/redirect_uri& state=STATE& scope=aws.cognito.signin.user.admin+openid+profile
示例响应
授权服务器重定向回您的应用程序,带有访问令牌和 ID 令牌 (因为包括了 openid
范围)。
HTTP/1.1 302 Found
Location: https://YOUR_APP/redirect_ur#id_token=ID_TOKEN&access_token=ACCESS_TOKEN&token_type=bearer&expires_in=3600&state=STATE
负向响应的示例
以下是负向响应的示例:
-
如果
client_id
和redirect_uri
有效,但请求参数有其他问题 (例如,如果未包括response_type
;如果提供了code_challenge
但未提供code_challenge_method
;或者如果code_challenge_method
不是“S256”),则身份验证服务器会将错误重定向到客户端的redirect_uri
。HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request
-
如果客户端在
response_type
中请求“code”或“token”,但没有这些请求的权限,则 Amazon Cognito 授权服务器应将unauthorized_client
返回到客户端的redirect_uri
,如下所示:HTTP 1.1 302 Found Location: https://client_redirect_uri?error=unauthorized_client
-
如果客户端请求无效、未知、范围格式错误,则 Amazon Cognito 授权服务器应将
invalid_scope
返回到客户端redirect_uri
,如下所示:HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_scope
-
如果服务器出现意外错误,则认证服务器应返回
server_error
至客户的redirect_uri
。不应是浏览器中显示的向最终用户显示的HTTP500错误,因为此错误不会发送到客户端。应返回以下错误:HTTP 1.1 302 Found Location: https://client_redirect_uri?error=server_error
-
通过联合第三方身份提供商进行身份验证时,Cognito 可能会遇到以下连接问题:
-
如果从身份提供商处请求令牌时连接超时,身份验证服务器会将该错误重定向到客户端的
redirect_uri
,如下所示:HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Timeout+occurred+in+calling+IdP+token+endpoint
-
如果在调用 jwks 终端节点进行 id_token 验证时连接超时,身份验证服务器会将该错误重定向到客户端的
redirect_uri
,如下所示:HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=error_description=Timeout+in+calling+jwks+uri
-
-
通过联合第三方身份提供商进行身份验证时,提供商可能会因配置错误或其他原因返回错误响应,如下所示:
-
如果从其他提供商处收到错误响应,身份验证服务器会将该错误重定向到客户端的
redirect_uri
,如下所示:HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=[IdP name]+Error+-+[status code]+error getting token
-
如果从 Google 收到错误响应,身份验证服务器会将该错误重定向到客户端的
redirect_uri
,如下所示:HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Google+Error+-+[status code]+[Google provided error code]
-
-
在极少数情况下,如果 Cognito 在与外部身份提供商建立连接时遇到通信协议异常,身份验证服务器会将该错误重定向到客户端的
redirect_uri
,并显式以下错误消息:-
HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Connection+reset
-
HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Read+timed+out
-