重定向和授权端点 - Amazon Cognito
GET /oauth2/authorize示例：授权码授权示例：使用 PKCE 授予授权码示例：要求使用重新进行身份验证 prompt=login示例：使用静默身份验证 prompt=none示例：没有openid作用域的代币（隐式）授权示例：带openid作用域的代币（隐式）授权错误响应
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

重定向和授权端点

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

授权端点重定向到托管登录或 IdP 登录页面。此端点上的用户会话的目的地是您的用户必须直接在其浏览器中与之交互的网页。

要使用 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）标准的授权端点中详细了解授权端点的定义。

请求参数

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 还支持应用程序回调， URLs 例如。myapp://example

state

可选，推荐。

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

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

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

identity_provider

可选。

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

  • 对于社交提供者，您可以使用 identity_provider 值 Facebook、Google、LoginWithAmazon 和 SignInWithApple。

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

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

idp_identifier

可选。

添加此参数以重定向到具有 identity_provider 名称的替代名称的提供程序。您可以 IdPs 从 Amazon Cognito 控制台的社交和外部提供商菜单中输入 SAML 2.0 和 OIDC 的标识符。

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

可选。

您从中生成的密钥代码交换证明 (PKCE) 质询。code_verifier有关更多信息，请参阅 在授权代码授予中使用 PKCE。

仅当您指定 code_challenge_method 参数时是必需的。

nonce

可选。

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

lang

可选。

您想要显示用户交互式页面的语言。托管登录页面可以本地化，但托管用户界面（经典）页面不能。有关更多信息，请参阅 托管登录本地化。

login_hint

可选。

要传递给授权服务器的用户名提示。您可以从用户那里收集用户名、电子邮件地址或电话号码，并允许目的地提供者预先填入用户的登录名。当您向oauth2/authorize终端节点提交login_hint参数和否idp_identifier或identity_provider参数时，托管登录会使用您的提示值填充用户名字段。您也可以将此参数传递给 登录端点 并自动填入用户名值。

当您的授权请求调用指向 OIDC IdPs 或 Google 的重定向时，Amazon Cognito 会向该第三方授权机构在请求中添加一个login_hint参数。你无法将登录提示转发给 SAML、Apple、Login With Amazon 或 Facebook（Meta） IdPs。

prompt

可选。

一个 OIDC 参数，用于控制现有会话的身份验证行为。仅在托管登录品牌版本中可用，不适用于经典托管用户界面。有关 OIDC 规范的更多信息，请参阅身份验证请求。值none和login会影响用户池的身份验证行为。

IdPs 当用户选择向第三方提供商进行身份验证时，Amazon Cognito 会none将prompt除您的值之外的所有值转发给您。当用户访问的 URL 包含identity_provider或idp_identifier参数，或者授权服务器将他们重定向到，然后他们从可用按钮中选择登录端点和 IdP 时，就会出现这种情况。

提示参数值
prompt=none

Amazon Cognito 会以静默方式继续对拥有有效身份验证会话的用户进行身份验证。使用此提示，用户可以在用户池中的不同应用程序客户端之间进行静默身份验证。如果用户尚未通过身份验证，则授权服务器会返回login_required错误。

prompt=login

Amazon Cognito 要求用户重新进行身份验证，即使他们已有会话。当您想再次验证用户的身份时，请发送此值。拥有现有会话的经过身份验证的用户可以在不使该会话失效的情况下返回登录状态。当已有会话的用户再次登录时，Amazon Cognito 会为他们分配一个新的会话 Cookie。也可以将此参数转发给您的 IdPs。 IdPs接受此参数的用户还会向用户请求新的身份验证尝试。

prompt=select_account

此值对本地登录没有影响，必须在重定向到 IdPs的请求中提交。当包含在您的授权请求中时，此参数将添加prompt=select_account到 IdP 重定向目标的 URL 路径中。当 IdPs 支持此参数时，他们会要求用户选择他们想要登录的账户。

prompt=consent

此值对本地登录没有影响，必须在重定向到 IdPs的请求中提交。当包含在您的授权请求中时，此参数将添加prompt=consent到 IdP 重定向目标的 URL 路径中。当 IdPs支持此参数时，他们会先征得用户同意，然后再重定向回您的用户池。

当您在请求中省略该prompt参数时，托管登录将遵循默认行为：除非他们的浏览器具有有效的托管登录会话 Cookie，否则用户必须登录。例如，您可以将的多个值prompt与空格字符分隔符组合在一起。prompt=login consent

示例：授权码授权

这是授权代码授予的示例请求。

以下请求会启动会话，以便检索您的用户在 redirect_uri 目的地传递给应用程序的授权代码。该会话请求的范围包括用户属性和对 Amazon Cognito 自助服务 API 操作的访问权限。

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin

Amazon Cognito 身份验证服务器使用授权代码和状态重新导向回您的应用程序。授权代码的有效期为五分钟。

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

示例：使用 PKCE 授予授权码

此示例流程使用 PKCE 执行授权码授权。

此请求添加了一个code_challenge参数。要完成令牌代码的交换，必须在向 /oauth2/token 端点发出的请求中包括 code_verifier 参数。

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin&
code_challenge_method=S256&
code_challenge=a1b2c3d4...

授权服务器使用授权码和状态重定向回您的应用程序。您的应用程序处理授权码并将其兑换为令牌。

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

示例：要求使用重新进行身份验证 prompt=login

以下请求添加了一个prompt=login参数，要求用户再次进行身份验证，即使他们已有会话。

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin&
prompt=login

授权服务器重定向到登录端点，需要重新进行身份验证。

HTTP/1.1 302 Found Location: https://mydomain.auth.us-east-1.amazoncognito.com/login?response_type=code&client_id=1example23456789&redirect_uri=https://www.example.com&state=abcdefg&scope=openid+profile+aws.cognito.signin.user.admin&prompt=login

示例：使用静默身份验证 prompt=none

以下请求添加了一个prompt=none参数，用于静默检查用户是否有有效的会话。

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin&
prompt=none

当不存在有效的会话时，授权服务器会向重定向 URI 返回错误

HTTP/1.1 302 Found Location: https://www.example.com?error=login_required&state=abcdefg

存在有效会话时，授权服务器会返回授权码。

HTTP/1.1 302 Found Location: https://www.example.com?code=AUTHORIZATION_CODE&state=abcdefg

示例：没有openid作用域的代币（隐式）授权

此示例流程生成隐式授权，并 JWTs 直接返回到用户的会话。

请求来自您的授权服务器的隐式授权。它请求访问令牌中的作用域来授权用户配置文件自助服务操作。

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=token&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin

授权服务器仅使用访问令牌重定向回您的应用程序。由于未请求 openid 范围，Amazon Cognito 不会返回 ID 令牌。此外，Amazon Cognito 不会在此流程中返回刷新令牌。

HTTP/1.1 302 Found
Location: https://example.com/callback#access_token=eyJra456defEXAMPLE&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=1example23456789& 
redirect_uri=https://www.example.com& 
state=abcdefg&
scope=aws.cognito.signin.user.admin+openid+profile

授权服务器使用访问令牌和 ID 令牌重定向回您的应用程序（因为包含了openid范围）：

HTTP/1.1 302 Found
Location: https://www.example.com#id_token=eyJra67890EXAMPLE&access_token=eyJra12345EXAMPLE&token_type=bearer&expires_in=3600&state=abcdefg

负向响应的示例

Amazon Cognito 可能会拒绝您的请求。失败的请求附带 HTTP 错误代码和相关描述，您可以使用这些信息来更正请求参数。以下是负向响应的示例。

  • 如果 client_id 和 redirect_uri 有效，但请求参数格式不正确，身份验证服务器会将该错误重定向到客户端的 redirect_uri 并在 URL 参数中附加错误消息。以下是错误格式的示例。

    • 该请求不包括 response_type 参数。

    • 授权请求提供了 code_challenge 参数，但没有提供 code_challenge_method 参数。

    • code_challenge_method 参数的值不是 S256。

    以下是使用了错误格式的示例请求的响应。

    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 通过联合身份验证向第三方 IdPs进行身份验证时，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_uri 端点进行 ID 令牌验证时连接超时，身份验证服务器会重定向到客户端的 redirect_uri，并出现如下所示的错误：

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=error_description=Timeout+in+calling+jwks+uri

  • 通过联合第三方进行身份验证时 IdPs，提供商可能会返回错误响应。这可能是由于配置错误或其他原因而造成，例如以下原因：

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