了解身份（ID）令牌

ID 令牌是一个 JSON Web 令牌（JWT），其中包含有关经过身份验证用户的身份声明，如 name、email 和 phone_number。您可以在应用程序中使用此身份信息。此外，ID 令牌还可用于针对资源服务器或服务器应用程序对用户进行身份验证。您还可以将应用程序外部的 ID 令牌用于 Web API 操作。在这些情况下，您必须先验证 ID 令牌的签名，然后才能信任 ID 令牌内的任何声明。请参阅验证 JSON Web 令牌。

您可以将 ID 令牌过期时间设置为 5 分钟到 1 天之间的任何值。您可以按应用程序客户端设置此值。

ID 令牌包括acr和amr声明，它们描述了用户满足的身份验证级别以及他们完成的方法。有关更多信息，请参阅 ACR 和 AMR 代币索赔。

重要

当您的用户使用托管登录信息登录时，Amazon Cognito 会设置有效期为 1 小时的会话 Cookie。如果您在应用程序中使用托管登录信息进行身份验证，并为访问和 ID 令牌指定不到 1 小时的最短持续时间，则您的用户在 Cookie 过期前仍将拥有有效的会话。如果用户的令牌在一小时的会话期间过期，则用户可以刷新他们的令牌，而无需重新身份验证。

ID 令牌标头

标头包含两部分信息：密钥 ID (kid) 和算法 (alg)。


{
"kid" : "1234example=",
"alg" : "RS256"
}

kid

密钥 ID。其值指示用于保护令牌的 JSON Web Signature (JWS) 的密钥。您可以在 jwks_uri 端点上查看您的用户群体签名密钥 ID。

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

alg

Amazon Cognito 用于保护访问令牌的加密算法。用户池使用 RS256 加密算法，该算法是 RSA 签名。 SHA-256

有关 alg 参数的更多信息，请参阅算法（alg）标头参数。

ID 令牌默认有效载荷

这是来自 ID 令牌的有效负载示例。它包含有关经过身份验证的用户的声明。有关 OpenID Connect（OIDC）标准声明的更多信息，请参阅 OIDC 标准声明列表。您可以使用令牌生成前 Lambda 触发器添加自有设计的声明。

此有效载荷具有代表性，并非详尽无遗。随着新功能的增加，Amazon Cognito ID 令牌中的声明集会随着时间的推移而增加，因此您的代币所携带的声明可能与本示例有所不同。将此示例视为常见声明的快照，而不是完整的固定列表，在编写解析 Amazon Cognito 令牌的代码如何安全地解析这个令牌之前，请先阅读此示例。


<header>.{
    "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "cognito:groups": [
        "test-group-a",
        "test-group-b",
        "test-group-c"
    ],
    "email_verified": true,
    "cognito:preferred_role": "arn:aws:iam::111122223333:role/my-test-role",
    "iss": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example",
    "cognito:username": "my-test-user",
    "middle_name": "Jane",
    "nonce": "abcdefg",
    "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "cognito:roles": [
        "arn:aws:iam::111122223333:role/my-test-role"
    ],
    "aud": "xxxxxxxxxxxxexample",
    "identities": [
        {
            "userId": "amzn1.account.EXAMPLE",
            "providerName": "LoginWithAmazon",
            "providerType": "LoginWithAmazon",
            "issuer": null,
            "primary": "true",
            "dateCreated": "1642699117273"
        }
    ],
    "event_id": "64f513be-32db-42b0-b78e-b02127b4f463",
    "token_use": "id",
    "auth_time": 1676312777,
    "exp": 1676316377,
    "iat": 1676312777,
    "jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "email": "my-test-user@example.com"
}
.<token signature>

sub

经过身份验证的用户的唯一标识符（UUID）或主题。用户名在您的用户群体中可能不是唯一的。sub 声明是识别给定用户的最佳方法。

重要

Amazon Cognito 以不符合特定 UUID Cognito-specific 格式（包括 RFC UUID）的亚马逊格式生成sub。您不应该严格验证的格式sub。更笼统地说，如安全解析令牌声明指南中所述，请将每个声明视为本页记录的类型，并且不要强加比文档所说的更严格的格式。

cognito:groups

字符串数组。每个字符串都是以您的用户为成员的用户池组的名称。组可以是您提供给应用程序的标识符，也可以从身份池为首选 IAM 角色生成请求。即使用户属于单个群组，此声明也始终是一个数组。

cognito:preferred_role

与用户的最高优先级用户池组关联的 IAM 角色的 ARN。有关您的用户池如何选择此角色声明的更多信息，请参阅将优先级值分配到组。

iss

单个字符串。令牌的发布者。此声明标识了生成令牌的用户池。您的应用程序应验证此值是否与您的用户池的预期发行者 URL 相匹配。声明采用以下格式。

https://cognito-idp.<Region>.amazonaws.com/<your user pool ID>

您的用户池可以使用原始发行者或更新的发行者。更新的颁发者在多个区域托管相同的 JWKS 内容，从而提高了恢复能力和效率。有关更多信息，请参阅 Amazon Cognito 用户池作为 OIDC 发行机构。

cognito:username

用户池中用户的用户名。

nonce

nonce 声明来自同名的参数，您可以将其添加到 OAuth 2.0 authorize 端点的请求中。添加参数时，nonce 声明包含在 Amazon Cognito 颁发的 ID 令牌中，您可以使用它来防范重播攻击。如果在您的请求中未提供 nonce 值，当您通过第三方身份提供商进行身份验证时，Amazon Cognito 会自动生成并验证随机数，然后将其作为 nonce 声明添加到 ID 令牌中。Amazon Cognito 中的 nonce 声明的实现基于 OIDC 标准。

origin_jti

与用户的刷新令牌关联的令牌撤消标识符。Amazon Cognito 在检查您是否通过撤销端点或 API 操作撤销了用户的令牌时会引用该origin_jti声明。RevokeToken当您撤销令牌时，Amazon Cognito 会使所有具有相同 origin_jti 值的访问令牌和 ID 令牌失效。

cognito:roles

字符串数组。每个字符串都是与您的用户群组关联的 IAM 角色的 ARN。每个用户池组可以有一个与之关联的 IAM 角色。此数组代表用户组的所有 IAM 角色，无论优先级如何，并且即使包含单个角色也始终是一个数组。有关更多信息，请参阅向用户池添加组。

aud

单个字符串。对用户进行身份验证的用户池应用程序客户端。Amazon Cognito 在访问令牌 client_id 声明中呈现相同的值。

identities

一个对象数组。每个对象都描述了您通过联合登录或将联合用户关联到本地个人资料的方式与该用户关联的一个第三方身份提供商个人资料。每个对象都包含字段userId（用户在提供商处的唯一 ID）providerName、providerType、issuer、primary、和dateCreated。所有这些字段都是字符串，需要仔细解析两个序列化细节：primary是字符串"true"或"false"，不是 JSON 布尔值，是一个以毫秒为单位保存 Unix 时间的字符串（例如"1642699117273"），而不是数字。dateCreated该issuer字段可以是null。即使用户有一个关联身份，此声明也始终是一个数组。

token_use

令牌的预期用途。在 ID 令牌中，其值为 id。

auth_time

数值。您的用户完成身份验证时的身份验证时间，采用 Unix 时间格式。

exp

数值。用户令牌到期时的过期时间，采用 Unix 时间格式。

iat

数值。在 Amazon Cognito 发布用户令牌时以 Unix 时间格式签发。

jti

JWT 的唯一标识符。

email

单个字符串。当email属性存在且可供应用程序客户端读取时，您的用户的电子邮件地址。

ID 令牌可包含 OIDC 标准声明中所定义的 OIDC 标准声明。ID 令牌还可包含您在用户池中定义的自定义属性。无论属性类型如何，Amazon Cognito 都会将自定义属性值作为字符串写入 ID 令牌。

注意

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

如何安全地解析这个令牌

亚马逊 Cognito ID 令牌中设置的索赔未修复。令牌携带的声明因身份验证流程、用户的群组成员资格和身份提供商而异。它们还取决于您的用户池中启用的功能。OpenID Connect 规范只需要iss、、subaudexpiat、和，这些都存在于每个亚马逊 Cognito ID 令牌中。Amazon Cognito 还会始终添加token_use该值id，您应验证该值以确认收到的是身份令牌而不是访问令牌。将所有其他声明视为可选声明，并以用户如何进行身份验证为条件。

ID 令牌是几种 Amazon Cognito 令牌类型之一，相同的解析规则适用于所有令牌。有关安全解析令牌的更多信息，请参阅安全地解析用户池令牌。

按场景划分的 ID 令牌示例

ID 令牌默认有效载荷将许多可选声明合并为一个示例。实际上，令牌携带的声明取决于用户的登录方式。以下示例显示了 Amazon Cognito 针对四种常见场景发出的索赔组合。每个示例都是一个解码后的有效载荷，而不是签名和序列化的 JWT：真正的令牌是 base64url 编码的header.payload.signature，带有用户池的密钥。 RS256-signed sub、用户池 ID 和时间戳值是说明性占位符。

基准授权码 ID 令牌

大多数应用程序在令牌端点交换授权码后使用的身份令牌。的token_use值将其与访问令牌id区分开来。之所以存在此nonce声明，是因为客户端在授权请求中发送了一个nonce参数以帮助防止重放攻击。


{
    "sub": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ExAmPlE",
    "aud": "6o7h8i9jexampleclientid",
    "cognito:username": "my-test-user",
    "email": "my-test-user@example.com",
    "email_verified": true,
    "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "token_use": "id",
    "auth_time": 1759345200,
    "iat": 1759345200,
    "exp": 1759348800,
    "jti": "11112222-3333-4444-5555-666677778888",
    "nonce": "n-0S6_WzA2Mj"
}

群组和角色成员资格

当用户属于一个或多个用户池组时，Amazon Cognito 会添加群组和角色授权声明。cognito:groups和cognito:roles声明是数组；即使它们包含单个元素，也将其读取为数组。 cognito:preferred_role是一个单字符串。


{
    "sub": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ExAmPlE",
    "aud": "6o7h8i9jexampleclientid",
    "cognito:username": "my-test-user",
    "cognito:groups": ["admins", "beta-testers"],
    "cognito:roles": ["arn:aws:iam::111122223333:role/my-test-role"],
    "cognito:preferred_role": "arn:aws:iam::111122223333:role/my-test-role",
    "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "token_use": "id",
    "auth_time": 1759345200,
    "iat": 1759345200,
    "exp": 1759348800,
    "jti": "11112222-3333-4444-5555-666677778888"
}

联合登录

通过外部身份提供商（例如社交或 SAML/OIDC 提供商）登录的用户会提出声明，该identities声明描述了外部提供商链接。


{
    "sub": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ExAmPlE",
    "aud": "6o7h8i9jexampleclientid",
    "cognito:username": "LoginWithAmazon_amzn1.account.EXAMPLE",
    "identities": [
        {
            "userId": "amzn1.account.EXAMPLE",
            "providerName": "LoginWithAmazon",
            "providerType": "LoginWithAmazon",
            "issuer": null,
            "primary": "true",
            "dateCreated": "1642699117273"
        }
    ],
    "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "token_use": "id",
    "auth_time": 1759345200,
    "iat": 1759345200,
    "exp": 1759348800,
    "jti": "11112222-3333-4444-5555-666677778888"
}

注意

在每个identities对象中，primary和dateCreated被序列化为字符串（"true"和"1642699117273"），而不是 JSON 布尔值和数字。诸如identity.primary === true静默之类的比较结果为 false。读取primary为字符串"true"或"false"，dateCreated以及保存 Unix 时间的字符串（以毫秒为单位）。

身份验证强度（ACR 和 AMR）

当您的用户池报告用户达到的身份验证级别时，Amazon Cognito 会添加acr和amr声明。以下令牌来自使用密码和来自身份验证器应用程序的 TOTP（最高级别）进行身份验证的用户。每个代币恰好包含一个可能的acr关卡。有关固定水平集、满足每个水平的因子组合以及完整的amr值列表，请参见ACR 和 AMR 声明的身份验证级别。


{
    "sub": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ExAmPlE",
    "aud": "6o7h8i9jexampleclientid",
    "cognito:username": "my-test-user",
    "acr": "urn:cognito:loa:4",
    "amr": ["pwd", "otp", "mfa"],
    "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "token_use": "id",
    "auth_time": 1759345200,
    "iat": 1759345200,
    "exp": 1759348800,
    "jti": "11112222-3333-4444-5555-666677778888"
}

请求身份验证级别需要基本版或增强版功能计划。acr和amr声明由 Amazon Cognito 计算，无法通过代币生成前 Lambda 触发器进行修改。将 Amazon Cognito 等级转换为其他标准（例如 NIST 或 eIDA）是您的应用程序的责任。

ID 令牌签名

ID 令牌的签名根据 JWT 令牌的标头和负载计算。在您接受应用程序收到的任何 ID 令牌中的声明之前，请验证该令牌的签名。有关更多信息，请参阅验证 JSON 网络令牌。验证 JSON Web 令牌。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

用户池令牌

访问令牌