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

将令牌与用户池结合使用

在成功验证身份后,Amazon Cognito 会将用户池令牌返回到您的应用程序。您可以使用这些令牌向您的用户授予对您的服务器端资源或 Amazon API Gateway 的访问权限。或者,您可以用它们交换用于访问其他 AWS 服务的临时 AWS 凭证。请参阅 常见 Amazon Cognito 场景

 身份验证概述

您的 Web 和移动应用程序的用户池令牌处理和管理在客户端上是通过 Amazon Cognito 开发工具包提供的。有关开发工具包以及适用于 JavaScript、Android 和 iOS 的示例代码,请参阅 Amazon Cognito 用户池开发工具包。如果您需要手动处理用于服务器 API 处理的令牌,或者您使用的是其他编程语言,则有很多用于解码和验证 JWT 的好库。请参阅用于处理 JWT 令牌的库的 OpenID Foundation 列表

Amazon Cognito 用户池将实现 OpenID Connect (OIDC) 开放标准中所定义的 ID 令牌、访问令牌和刷新令牌。

  • ID 令牌包含有关经过身份验证的用户的身份声明,如 nameemailphone_number

  • 访问令牌授予对授权资源的访问权限。

  • 刷新令牌包含要获取新的 ID 令牌或访问令牌所需的令牌。

重要

我们强烈建议您在应用程序环境中保护传输和存储中的所有令牌。

有关 OIDC 的更多信息,请参阅 OpenID Connect (OIDC) 规范

使用 ID 令牌

ID 令牌是一个 JSON Web 令牌 (JWT),其中包含经身份验证的用户的身份声明,如 nameemailphone_number。您可以在应用程序中使用此身份信息。此外,ID 令牌还可用于针对资源服务器或服务器应用程序对用户进行身份验证。在应用程序外部将 ID 令牌用于 Web API 时,您必须先验证 ID 令牌的签名,然后才能信任 ID 令牌内的任何声明。请参阅 验证 JSON Web 令牌

ID 令牌会在用户进行身份验证后的 1 小时内过期。在 ID 令牌过期后,您不应该在客户端或 Web API 中对其进行处理。

有关 OIDC 标准声明的更多信息,请参阅 OIDC 标准声明

ID 令牌标头

标头包含两条令牌:密钥 ID (kid) 和算法 (alg)。

{ "kid" : "1234example=" "alg" : "RS256", }
密钥 ID (kid)

kid 参数是一个提示,指示哪些密钥用于保护令牌的 JSON Web Signature (JWS)。

有关 kid 参数的更多信息,请参阅密钥标识符 (kid) 标头参数

算法 (alg)

alg 参数表示用于保护 ID 令牌的加密算法。用户池使用 RS256 加密算法,这是一种采用 SHA-256 的 RSA 签名。

有关 alg 参数的更多信息,请参阅算法 (alg) 标头参数

ID 令牌负载

这是来自 ID 令牌的示例负载。它包含有关经过身份验证的用户的声明。有关 OIDC 标准声明的更多信息,请参阅 OIDC 标准声明

{ "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "aud": "xxxxxxxxxxxxexample", "email_verified": true, "token_use": "id", "auth_time": 1500009400, "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example", "cognito:username": "janedoe", "exp": 1500013000, "given_name": "Jane", "iat": 1500009400, "email": "janedoe@example.com" }
主题 (sub)

sub 声明是经过身份验证的用户的唯一标识符 (UUID)。它不同于用户名,后者可能不是唯一的。

发布者 (iss)

iss 声明采用以下格式:

https://cognito-idp.{region}.amazonaws.com/{userPoolId}。

例如,如果您在 us-east-1 区域中创建一个用户池且其用户池 ID 为 u123456,则针对您用户池的用户发布的 ID 令牌的 iss 声明值为

https://cognito-idp.us-east-1.amazonaws.com/u123456。

受众 (aud)

aud 声明包含在经过身份验证的用户中使用的 client_id

令牌使用 (token_use)

The token_use 声明描述了该令牌的预期用途。对于 ID 令牌,它的值始终为 id

身份验证时间 (auth_time)

auth_time 声明包含身份验证发生的时间。其值是一个 JSON 数字,代表从 1970-01-01T0:0:0Z 开始直到指定日期/时间的秒数,以 UTC 格式为单位。在刷新时,它代表原始身份验证发生的时间,而不是发布令牌的时间。

ID 令牌可包含 OIDC 标准声明中所定义的 OpenID Connect (OIDC) 标准声明。它还可包含您在用户池中定义的自定义属性。

注意

用户池自定义属性始终以 custom: 为前缀。

ID 令牌签名

ID 令牌的签名根据 JWT 令牌的标头和负载计算。在 Web API 中,当您在应用程序外部使用时,您必须始终先验证此签名,然后才能接受该令牌。请参阅 验证 JSON Web 令牌

使用访问令牌

用户池访问令牌包含有关已验证用户的声明,但与 ID 令牌不同,它不包含身份信息。访问令牌的主要用途是在用户池中用户的环境中授予 API 操作权限。例如,您可以使用访问令牌授予用户访问权限以添加、更改或删除用户属性。此外,访问令牌还可与任何 Web API 结合使用,以做出访问控制决策并为您的用户授予操作权限。

访问令牌也以 JSON Web Token (JWT) 表示。访问令牌的标头结构与 ID 令牌的相同,但密钥 ID (kid) 不同,因为用于签署 ID 令牌和访问令牌的密钥不同。与 ID 令牌一样,您必须先在 Web API 中验证访问令牌的签名,然后才能信任它的任何声明。请参阅 验证 JSON Web 令牌

访问令牌会在您的用户成功进行身份验证后的 1 小时内过期。在访问令牌过期后,您不应该使用它。

访问令牌标头

标头包含两条令牌:密钥 ID (kid) 和算法 (alg)。

{ "kid" : "1234example=" "alg" : "RS256", }
密钥 ID (kid)

kid 参数是一个提示,指示哪些密钥用于保护令牌的 JSON Web Signature (JWS)。

有关 kid 参数的更多信息,请参阅密钥标识符 (kid) 标头参数

算法 (alg)

alg 参数表示用于保护访问令牌的加密算法。用户池使用 RS256 加密算法,这是一种采用 SHA-256 的 RSA 签名。

有关 alg 参数的更多信息,请参阅算法 (alg) 标头参数

访问令牌负载

这是来自访问令牌的示例负载。有关更多信息,请参阅 JWT 声明

{ "auth_time": 1500009400, "exp": 1500013000, "iat": 1500009400, "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example", "scope": "aws.cognito.signin.user.admin", "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "token_use": "access", "username": "janedoe@example.com" }
主题 (sub)

sub 声明是经过身份验证的用户的唯一标识符 (UUID)。它不同于用户名,后者可能不是唯一的。

发布者 (iss)

iss 声明采用以下格式:

https://cognito-idp.{region}.amazonaws.com/{userPoolId}。

令牌使用 (token_use)

The token_use 声明描述了该令牌的预期用途。对于访问令牌,它的值始终为 access

身份验证时间 (auth_time)

auth_time 声明包含身份验证发生的时间。其值是一个 JSON 数字,代表从 1970-01-01T0:0:0Z 开始直到指定日期/时间的秒数,以 UTC 格式为单位。在刷新时,它代表原始身份验证发生的时间,而不是发布令牌的时间。

访问令牌签名

访问令牌的签名根据 JWT 令牌的标头和负载计算。在 Web API 中,当您在应用程序外部使用时,您必须始终先验证此签名,然后才能接受该令牌。请参阅 验证 JSON Web 令牌

使用刷新令牌

您可以使用刷新令牌来检索新的 ID 令牌和访问令牌。

默认情况下,刷新令牌会在您的应用程序用户登录用户池后的 30 天内过期。当您为用户池创建应用程序时,您可以将应用程序的刷新令牌到期时间(以天为单位)设置为介于 1 和 3650 之间的任何值。

如果存在有效的(非过期的)刷新令牌,Mobile SDK for iOS 和 适用于 Android 的 移动软件开发工具包 会自动刷新您的 ID 令牌和访问令牌,而且 ID 令牌和访问令牌至少有 5 分钟的剩余有效性。如果刷新令牌已过期,您的应用程序用户必须通过再次登录用户池来重新进行身份验证。

注意

适用于 Android 的 移动软件开发工具包 提供的选项可将 ID 令牌和访问令牌的最短有效期更改为 0 到 30 分钟之间的值。请参阅 适用于 Android 的 AWS 移动软件开发工具包 API 参考中的 CognitoIdentityProviderClientConfig 的 setRefreshThreshold() 方法。

只要您的用户在针对新账户的 UnusedAccountValidityDays 时间限制之前至少登录一次,用户账户本身就永远不会过期。

要结合使用刷新令牌与用户池 API 获取新的 ID 令牌和访问令牌,请使用 AdminInitiateAuthInitiateAuth 方法。传递 AuthFlow 参数的 REFRESH_TOKEN_AUTH。授权参数 AuthParameters 是密钥-值映射,其中密钥为“REFRESH_TOKEN”,值为实际刷新令牌。Amazon Cognito 使用新的 ID 令牌和访问令牌进行响应。

撤消某个用户的所有令牌

当您通过 GlobalSignOutAdminUserGlobalSignOut API 撤消用户的所有令牌时,用户可以从它们当前登录的所有设备中注销。用户注销后:

  • 用户的刷新令牌无法用于为用户获取新的令牌。

  • 用户的访问令牌无法用于用户池服务。

  • 用户必须重新进行身份验证以获取新的令牌。

应用程序可以使用 GlobalSignOut API 来允许单个用户自行从所有设备注销。通常,应用程序会将此选项显示为一个选择,例如 Sign out from all devices。该应用程序必须使用用户的未过期、未撤消的有效访问令牌调用此方法。此方法不能用于允许一个用户注销另一个用户。

管理员应用程序可以使用 AdminUserGlobalSignOut API 来允许管理员将一个用户从所有设备注销。管理员应用程序必须通过 AWS 开发人员凭证调用此方法,并传递用户池 ID 和用户的用户名作为参数。AdminUserGlobalSignOut API 可以在用户池中注销任何用户。