# 토큰 클레임 이해
<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는 IAM 위탁자의 ID를 나타내는 클레임 세트가 포함된 서명된 JSON 웹 토큰(JWT)을 반환합니다. 이러한 토큰은 [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)와 호환됩니다. 이러한 토큰의 구조와 내용을 이해하면 보안 인증 흐름을 구현하고, 외부 서비스에서 적절한 클레임 검증을 구성하고, 세분화된 액세스 제어를 위해 사용자 지정 클레임을 효과적으로 사용할 수 있습니다.

JWT에는 주제(‘sub’), 대상(‘aud’), 발급자(‘iss’)와 같은 표준 OpenID Connect(OIDC) 클레임이 포함되어 있어 다양한 외부 서비스 간의 상호 운용성을 지원합니다. 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 라이브러리를 사용하여 검증할 수 있습니다.


| Claim | 이름 | 설명 | 예제 값 | 
| --- | --- | --- | --- | 
| iss | Issuer | 계정별 발급자 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 | Issued At | JWT가 발급된 시간을 식별하는 NumericDate 값입니다. | 1700000000 | 
| exp | Expiration | NumericDate 값은 JWT가 처리에 허용되지 않아야 하는 만료 시간을 식별합니다. | 1700000900 | 
| jti | JWT ID | 이 토큰 인스턴스의 고유 식별자입니다. | xyz123-def456-ghi789-jkl012 | 

## 사용자 지정 클레임
<a name="custom-claims"></a>

AWS STS는 표준 OIDC 클레임 외에도 해당하는 경우 ID 및 세션 컨텍스트에 대한 클레임을 추가합니다. 요청 태그로 토큰을 전달하여 토큰에 자체 클레임을 추가할 수도 있습니다. 사용자 지정 클레임은 https://sts.amazonaws.com/ 네임스페이스 아래에 중첩됩니다.

### AWS ID 클레임
<a name="aws-identity-claims"></a>

이러한 클레임은 AWS 계정, 조직 구조 및 IAM 위탁자에 대한 자세한 정보를 제공합니다.


| Claim | 설명 | 조건 키에 매핑 | 예제 값 | 
| --- | --- | --- | --- | 
| 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는 요청 주체의 세션 컨텍스트에 따라 해당하는 경우 이러한 클레임을 자동으로 포함합니다.


| Claim | 설명 | 조건 키에 매핑 | 예제 값 | 
| --- | --- | --- | --- | 
| original\_session\_exp | 원래 역할 세션 자격 증명이 만료되는 시기(위임된 역할의 경우) | 해당 사항 없음 | 2024-01-15T10:00:00Z | 
| federated\_provider | 페더레이션 세션의 ID 공급자 이름 | [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 ID 스토어의 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 | 위탁자가 설정한 소스 ID | [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"
  }
}
```