重定向和授权端点 - Amazon Cognito

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

重定向和授权端点

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

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

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

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

  • 你URL想要最终到达的回调。

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

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

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

GET /oauth2/authorize

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

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

请求参数

response_type

(必填)响应类型。必须为 codetoken

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

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

client_id

(必填)应用程序客户端 ID。

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

redirect_uri

(必填)在 Amazon Cognito 对用户进行授权后,身份验证服务器将浏览器重定向到URL何处。

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

  • 它必须是绝对的URI。

  • 您必须已向URI客户预先注册。

  • 不能包含片段组件。

请参阅 OAuth2.0-重定向端点

Amazon Cognito 要求您URI使用重定向 HTTPShttp://localhost,但您可以将其设置URL为回调以进行测试。

Amazon Cognito 还支持应用程序回调,URLs例如。myapp://example

state

(可选,推荐)当您的应用程序向请求添加状态参数时,当/oauth2/authorize终端节点重定向您的用户时,Amazon Cognito 会将其值返回给您的应用程序。

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

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

identity_provider

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

  • 对于社交提供者,您可以使用 identity_providerFacebookGoogleLoginWithAmazon和。SignInWithApple

  • 对于 Amazon Cognito 用户池,请使用该值。COGNITO

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

idp_identifier

(可选)添加此参数以重定向到具有替代名称的 id entity_p rovider 名称的提供商。您可以在 Amazon Cognito 控制台的 “登录体验” 选项卡OIDC IdPs 中输入 SAML 2.0 版的标识符。

scope

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

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

如果请求 openid 范围,则只返回 ID 令牌。如果请求 aws.cognito.signin.user.admin 范围,则访问令牌只能用于 Amazon Cognito 用户池。如果同时请求了 phone 范围,则只能请求 emailprofileopenid 范围。这些范围控制进入 ID 令牌中的声明。

code_challenge_method

(可选)您用来生成质询的哈希协议。PKCERFC定义了两种方法,S256 和普通方法;但是,Amazon Cognito 身份验证服务器仅支持 S256。

code_challenge

(可选)您从中生成的挑战code_verifier

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

nonce

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

回复为正面的请求示例

以下示例说明了向/oauth2/authorize终端节点发出的HTTP请求的格式。

授予授权代码

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

示例-GET 请求

以下请求启动会话,以检索您的用户在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

示例-GET 请求

以下请求为上一个请求添加了一个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

不带 openid 范围的令牌授予

这是一个生成隐式授权并JWTs直接返回到用户会话的示例请求。

示例-GET 请求

以下请求是请求您的授权服务器进行隐式授权。来自亚马逊 Cognito 的访问令牌授权自助服务操作。API

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
示例-响应

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 范围的令牌授予

这是一个生成隐式授权并JWTs直接返回到用户会话的示例请求。

示例-GET 请求

以下请求是请求您的授权服务器进行隐式授权。来自 Amazon Cognito 的访问令牌授权访问用户属性和自助服务操作。API

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

负向响应的示例

亚马逊 Cognito 可能会拒绝您的请求。否定请求附带HTTP错误代码和描述,您可以用来更正请求参数。以下是负面回应的示例。

  • 如果client_idredirect_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
  • 如果客户端请求codetoken进入response_type,但无权处理这些请求,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