本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 了解字符宣告
<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 Token (JWT)，其中包含一組代表 IAM 主體身分的宣告。這些字符符合 [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)。了解這些字符的結構和內容可協助您實作安全身分驗證流程、在外部服務中設定適當的宣告驗證，以及有效地使用自訂宣告進行精細存取控制。

JWT 包含標準 OpenID Connect (OIDC) 宣告，例如主體 ("sub")、對象 ("aud")、發行者 ("iss")，以促進不同外部服務的互通性。 會在適用時將 AWS 身分特定宣告 （例如 AWS 帳戶 ID 和主體標籤） 和工作階段內容宣告 （例如 EC2 執行個體 ARNs) AWS STS 填入字符。您也可以將自訂宣告做為請求標籤傳遞至 [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 值。 | 1700000000 | 
| exp | Expiration | 識別過期時間的 NumericDate 值，在此時間之後，JWT 不得接受處理。 | 1700000900 | 
| 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 主體的詳細資訊。


| 取得 | Description | 條件索引鍵的映射 | 範例值 | 
| --- | --- | --- | --- | 
| 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) | {"環境"： "生產"、"團隊"： "資料工程"、"成本中心"："工程"} | 

### 工作階段內容宣告
<a name="session-context-claims"></a>

這些宣告提供有關字符請求發起的運算環境和工作階段的資訊。根據請求主體的工作階段內容，當適用時， AWS STS 會自動包含這些宣告。


| 取得 | Description | 條件索引鍵的映射 | 範例值 | 
| --- | --- | --- | --- | 
| original\_session\_exp | 原始角色工作階段憑證何時過期 （適用於擔任的角色） | N/A | 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 | AWS Glue 任務的 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"
  }
}
```