Amazon Cognito
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

AUTHORIZATION 终端节点

/oauth2/authorize 终端节点让用户登录。

GET /oauth2/authorize

/oauth2/authorize 终端节点只支持 HTTPS GET。用户池客户端一般通过系统浏览器发出此请求,在 Android 中这通常是“Custom Chrome”选项卡,在 iOS 中是“Safari View Control”。

请求参数

response_type

响应类型。必须为 codetoken。指示客户端需要最终用户的授权代码 (授权代码授予流) 还是直接为最终用户发布令牌 (隐式流)。

必需

client_id

客户端 ID。

必须是在用户池中预注册的客户端,并且必须已启用联合功能。

必需

redirect_uri

在用户授权之后,身份验证服务器将浏览器重定向到的 URL。

必须已经预注册到客户端。

必需

state

客户端添加到初始请求的不透明值。授权服务器在重定向回客户端时包括此值。

客户端必须使用此值来防止 CSRF 攻击。

此值可选,但强烈建议使用。

identity_provider

由开发人员直接用来在特定提供商处进行身份验证。

可选

idp_identifier

由开发人员用于映射到提供商名称而不公开提供商名称。

可选

scope

可以是任何系统预留范围或与客户端关联的自定义范围的组合。范围必须以空格分隔。系统预留范围为 openidemailphoneprofileaws.cognito.signin.user.admin。使用的任意范围必须预先与客户端关联,否则它将在运行时被忽略。

如果客户端不请求任何范围,则身份验证服务器使用与客户端关联的所有范围。

如果请求 openid 范围,则只返回 ID 令牌。如果请求 aws.cognito.signin.user.admin 范围,则访问令牌只能用于 Amazon Cognito 用户池。如果同时请求了 openid 范围,则只能请求 phoneemailprofile 范围。这些范围控制进入 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_idredirect_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。这不应该是在浏览器中向最终用户显示的 HTTP 500 错误,因为此错误不发送到客户端。应返回以下错误:

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=server_error

本页内容: