# 了解令牌声明
<a name="id_roles_providers_outbound_token_claims"></a>

当您调用 [GetWebIdentityToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetWebIdentityToken.html) API 时，AWS Security Token Service 会返回一个已签名的 JSON Web 令牌（JWT），其中包含一组代表 IAM 主体身份的声明。这些令牌均符合 [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)。了解这些令牌的结构和内容可帮助您实现安全的身份验证流程，在外部服务中配置适当的声明验证，并有效地使用自定义声明实现精细的访问控制。

JWT 包含标准 OpenID Connect（OIDC）声明，例如主题（“sub”）、受众（“aud”）、发布者（“iss”），以便于实现不同外部服务之间的互操作性。在适用的情况下，AWS STS 会使用 AWS 身份特定的声明（如 AWS 账户 ID 和主体标签）和会话上下文声明（如 EC2 实例 ARN）填充令牌。您还可以通过将自定义声明作为请求标签传递给 [GetWebIdentityToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetWebIdentityToken.html) API 将其添加到令牌。AWS 身份特定的声明、会话上下文声明和自定义声明嵌套在令牌中的“https://sts.amazonaws.com/”命名空间下。

有关令牌中包含的声明列表，请参阅下面的示例令牌。请注意，所有这些声明可能不会同时出现在令牌中。

```
{
  "iss": "https://abc123-def456-ghi789-jkl012.tokens.sts.global.api.aws",
  "aud": "https://api.example.com",
  "sub": "arn:aws:iam::123456789012:role/DataProcessingRole",
  "iat": 1700000000,
  "exp": 1700000900,
  "jti": "xyz123-def456-ghi789-jkl012",
  "https://sts.amazonaws.com/": {
    "aws_account": "123456789012",
    "source_region": "us-east-1",
    "org_id": "o-abc1234567",
    "ou_path": "o-a1b2c3d4e5/r-ab12/ou-ab12-11111111/ou-ab12-22222222/",
    "principal_tags": {
      "environment": "production",
      "team": "data-engineering",
      "cost-center": "engineering"
    },
    "lambda_source_function_arn": "arn:aws:lambda:us-east-1:123456789012:function:process-data",
    "request_tags": {
        "job-id": "job-2024-001",
        "priority": "high",
        "data-classification": "sensitive"
    }
  }
}
```

## 标准声明
<a name="standard-claims"></a>

令牌中存在的标准 OIDC 声明有助于实现与各种外部服务的互操作性。这些声明可以使用大多数 JWT 库进行验证。


| 声明 | 名称 | 描述 | 示例值 | 
| --- | --- | --- | --- | 
| iss | 发布者 | 账户特定的发布者 URL。外部服务会验证此声明，以确保其匹配可信发布者。 | https://abc123-def456-ghi789-jkl012.tokens.sts.global.api.aws | 
| aud | 受众 | [GetWebIdentityToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetWebIdentityToken.html) 请求中指定的令牌的预期接收者。 | https://api.example.com | 
| sub | 主题 | 请求令牌的 IAM 主体的 ARN。 | arn:aws:iam::123456789012:role/DataProcessingRole | 
| iat | 发布时间 | 标识 JWT 发布时间的 NumericDate 值。 | 1,700,000,000 | 
| exp | 过期 | 标识过期时间的 NumericDate 值，在该时间或之后不得接受 JWT 进行处理。 | 1,700,000,900 | 
| jti | JWT ID | 此令牌实例的唯一标识符。 | xyz123-def456-ghi789-jkl012 | 

## 自定义声明
<a name="custom-claims"></a>

除了标准 OIDC 声明外，AWS STS 还会添加关于身份和会话上下文的声明（如果适用）。您还可以通过将自有声明作为请求标签传递来将其添加到令牌。自定义声明嵌套在 https://sts.amazonaws.com/ 命名空间下。

### AWS 身份声明
<a name="aws-identity-claims"></a>

这些声明提供有关您的 AWS 账户、组织结构和 IAM 主体的详细信息。


| 声明 | 描述 | 条件键映射 | 示例值 | 
| --- | --- | --- | --- | 
| aws\_account | 您的 AWS 账户 ID | [aws:PrincipalAccount](reference_policies_condition-keys.md#condition-keys-principalaccount) | 123456789012 | 
| source\_region | 请求令牌的 AWS 区域 | [aws:RequestedRegion](reference_policies_condition-keys.md#condition-keys-requestedregion) | us-east-1 | 
| org\_id | 您的 AWS Organizations ID（如果您的账户是组织的成员） | [aws:PrincipalOrgID](reference_policies_condition-keys.md#condition-keys-principalorgid) | o-abc1234567 | 
| ou\_path | 您的组织单位路径（如果适用） | [aws:PrincipalOrgPaths](reference_policies_condition-keys.md#condition-keys-principalorgpaths) | o-a1b2c3d4e5/r-ab12/ou-ab12-11111111/ou-ab12-22222222/ | 
| principal\_tags | 附加到 IAM 主体或代入角色会话的标签。请求令牌时，如果请求的 IAM 主体同时有主体标签和会话标签，则会话标签将出现在 JWT 中。 | [aws:PrincipalTag/<tag-key>](reference_policies_condition-keys.md#condition-keys-principaltag) | {"environment": "production", "team": "data-engineering", "cost-center":"engineering"} | 

### 会话上下文声明
<a name="session-context-claims"></a>

这些声明提供有关发起令牌请求的计算环境和会话的信息。AWS STS 会根据请求主体的会话上下文自动包含这些声明（如果适用）。


| 声明 | 描述 | 条件键映射 | 示例值 | 
| --- | --- | --- | --- | 
| original\_session\_exp | 原始角色会话凭证过期时间（适用于代入的角色） | 不适用 | 2024-01-15T10:00:00Z | 
| federated\_provider | 联合身份验证会话的身份提供商名称 | [aws:FederatedProvider](reference_policies_condition-keys.md#condition-keys-federatedprovider) | arn:aws:iam::111122223333:oidc-provider/your\_oidc\_provider | 
| identity\_store\_user\_id | IAM Identity Center 用户 ID | [identitystore:UserId](reference_policies_condition-keys.md#condition-keys-identity-store-user-id) | user-abc123def456 | 
| identity\_store\_arn | Identity Center 身份存储的 ARN | [identitystore:IdentityStoreArn](https://docs.aws.amazon.com/singlesignon/latest/userguide/condition-context-keys-sts-idc.html#condition-keys-identity-store-arn) | arn:aws:identitystore::123456789012:identitystore/d-abc1234567 | 
| ec2\_source\_instance\_arn | 请求 EC2 实例的 ARN | [ec2:SourceInstanceArn](reference_policies_condition-keys.md#condition-keys-ec2-source-instance-arn) | arn:aws:ec2:us-east-1:123456789012:instance/i-abc123def456 | 
| ec2\_instance\_source\_vpc | 提供 EC2 角色凭证的 VPC ID | [aws:Ec2InstanceSourceVpc](reference_policies_condition-keys.md#condition-keys-ec2instancesourcevpc) | vpc-abc123def456 | 
| ec2\_instance\_source\_private\_ipv4 | EC2 实例的私有 IPv4 地址 | [aws:Ec2InstanceSourcePrivateIPv4](reference_policies_condition-keys.md#condition-keys-ec2instancesourceprivateip4) | 10.0.1.25 | 
| ec2\_role\_delivery | 实例元数据服务版本 | [ec2:RoleDelivery](reference_policies_condition-keys.md#condition-keys-ec2-role-delivery) | 2 | 
| source\_identity | 主体设置的来源身份 | [aws:SourceIdentity](reference_policies_condition-keys.md#condition-keys-sourceidentity) | admin-user | 
| lambda\_source\_function\_arn | 调用 Lambda 函数的 ARN | [lambda:SourceFunctionArn](reference_policies_condition-keys.md#condition-keys-lambda-source-function-arn) | arn:aws:lambda:us-east-1:123456789012:function:my-function | 
| glue\_credential\_issuing\_service | Glue 作业的 AWS Glue 服务标识符 | [glue:CredentialIssuingService](reference_policies_condition-keys.md#condition-keys-glue-credential-issuing) | glue.amazonaws.com | 

### 请求标签
<a name="request-tags"></a>

您可以通过在 [GetWebIdentityToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetWebIdentityToken.html) API 请求中指定标签将自定义声明添加到令牌。这些声明在令牌中的 request\_tags 字段下显示，使您能够传递可供外部服务用于精细授权决策的特定信息。每个请求最多可以指定 50 个标签。

请求示例：

```
response = sts_client.get_web_identity_token(
    Audience=['https://api.example.com'],
    SigningAlgorithm='ES384',
    Tags=[
        {'Key': 'team', 'Value': 'data-engineering'},
        {'Key': 'cost-center', 'Value': 'analytics'},
        {'Key': 'environment', 'Value': 'production'}
    ]
)
```

令牌中由此产生的声明：

```
{
  "request_tags": {
    "team": "data-engineering",
    "cost-center": "analytics",
    "environment": "production"
  }
}
```