对端点授权 - Amazon Cognito
GET /oauth2/authorize
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

对端点授权

/oauth2/authorize 端点是支持两个重定向目标的重定向端点。如果您在 URL 中包括 identity_provider 或 idp_identifier 参数，则它会静默地将用户重定向到该身份提供者 (IdP) 的登录页面。否则，它会使用您在请求中包括的相同 URL 参数重定向到 登录端点。

要使用 authorize 端点，请在 /oauth2/authorize 上使用为您的用户群体提供有关以下用户群体详细信息的信息的参数调用用户的浏览器。

  • 您希望登录到的应用程序客户端。

  • 您希望最终到达的回调 URL。

  • 您希望在用户的访问令牌中请求的 OAuth 2.0 范围。

  • （可选）您希望用于登录的第三方 IdP。

您还可以提供 Amazon Cognito 用来验证传入声明的 state 和 nonce 参数。

GET /oauth2/authorize

/oauth2/authorize 终端节点只支持 HTTPS GET。您的应用程序通常在用户的浏览器中发起此请求。您只能通过 HTTPS 向 /oauth2/authorize 端点发出请求。

您可以在 OpenID Connect (OIDC) 标准的 Authorization Endpoint（授权端点）中详细了解授权端点的定义。

请求参数

response_type

响应类型。必须为 code 或 token。

response_type 为 code 的成功请求返回授权代码授予。授权代码授予是 Amazon Cognito 附加到重定向 URL 的 code 参数。您的应用程序可以将包含 令牌端点的代码交换为访问权限、ID 和刷新令牌。作为安全最佳实践，以及要为您的用户接收刷新令牌，请在您的应用程序中使用授权代码授予。

response_type 为 token 的成功请求返回隐式授予。隐式授予是 Amazon Cognito 附加到您的重定向 URL 的 ID 和访问令牌。隐式授予的安全性较差，因为它会向用户公开令牌和潜在的识别信息。您可以在应用程序客户端的配置中停用对隐式授予的支持。

必需。

client_id

客户端 ID。

client_id 的值必须是您在其中发出请求的用户群体中应用程序客户端的 ID。您的应用程序客户端必须支持 Amazon Cognito 本机用户或至少一个第三方 IdP 登录。

必需。

redirect_uri

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

重定向统一资源标识符 (URI) 必须具有以下属性：

  • 必须是绝对 URI。

  • 您必须已经将 URI 预注册到客户端。

  • 不能包含片段组件。

请参阅 OAuth 2.0 – 重定向端点。

Amazon Cognito 要求您的重新导向 URI 使用 HTTPS，但 http://localhost 除外，您可以将其设置为回调 URL 以进行测试。

Amazon Cognito 还支持应用程序回调 URL，如 myapp://example。

必需。

state

当应用程序向请求添加 state 参数时，如果 /oauth2/authorize 端点重新导向您的用户，则 Amazon Cognito 将此参数的值返回给您的应用程序。

将此值添加到您的请求中以防止 CSRF 攻击。

不能将 state 参数的值设置为 URL 编码的 JSON 字符串。要在 state 参数中传递与此格式匹配的字符串，请将该字符串编码为 Base64，然后在应用程序中对其进行解码。

可选但不推荐。

identity_provider

添加此参数以绕过托管 UI 并将您的用户重定向到提供商登录页面。identity_provider 参数的值是出现在您的用户池中的身份提供商 (IdP) 的名称。

  • 对于社交提供商，您可以使用以下 identity_provider 值：Facebook、Google（谷歌）、LoginWithAmazon（使用亚马逊账号登录）和 SignInWithApple（使用苹果账号登录）。

  • 对于 Amazon Cognito 用户池，使用值 COGNITO。

  • 对于 SAML 2.0 和 OpenID Connect (OIDC) 身份提供者 (IdP)，使用您在用户群体中分配给 IdP 的名称。

可选。

idp_identifier

添加此参数以重定向到具有 identity_provider 名称的替代名称的提供程序。您可以从 Amazon Cognito 控制台的 Sign-in experience（登录体验）选项卡中为您的 SAML 2.0 和 OIDC IdP 输入标识符。

可选。

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 参数时是必需的。

nonce

您可以添加到请求中的随机值。您提供的 nonce 值包含在 Amazon Cognito 发出的 ID 令牌中。为了防范重播攻击，您的应用程序可以检查 ID 令牌中的 nonce 声明并将其与您生成的声明进行比较。有关 nonce 声明的更多信息，请参阅《OpenID Connect 标准》中的 ID token validation（ID 令牌验证）。

具有正向响应的示例请求

授予授权代码

示例请求

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 请求中显示在“#”字符后的部分，用于指定文档的子部分。

注意

响应返回有效期为 5 分钟的一次性使用代码。

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 范围，Amazon Cognito 不会返回 ID 令牌。此外，Amazon Cognito 不会在此流程中返回刷新令牌。Amazon Cognito 在片段中返回访问令牌和状态，而不是在查询字符串中。

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_uri#id_token=ID_TOKEN&access_token=ACCESS_TOKEN&token_type=bearer&expires_in=3600&state=STATE

负向响应的示例

以下是负向响应的示例：

  • 如果 client_id 和 redirect_uri 有效，但请求参数格式不正确，身份验证服务器会将该错误重定向到客户端的 redirect_uri 并在 URL 参数中附加错误消息。格式错误的示例包括：如果响应提供 code_challenge 而不是 code_challenge_method，或者 code_challenge_method 不是“S256”，则请求不包含 response_type 参数。

    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

  • 当 Amazon Cognito 通过联合第三方 IdP 进行身份验证时，Amazon Cognito 可能会遇到以下连接问题：

    • 如果从 IdP 处请求令牌时连接超时，身份验证服务器会将该错误重定向到客户端的 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

  • 通过联合第三方 IdP 进行身份验证时，提供程序可能会因配置错误或其他原因返回错误响应，如下所示：

    • 如果从其他提供商处收到错误响应，身份验证服务器会将该错误重定向到客户端的 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]

  • 如果 Amazon Cognito 在与外部 IdP 建立连接时遇到通信协议异常，身份验证服务器会将该错误重定向到客户端的 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