토큰 클레임 이해

토큰 클레임 이해 (Understanding token claims)

GetWebIdentityToken API를 호출하면 AWS Security Token Service가 IAM 프린시펄의 아이덴티티를 나타내는 클레임 집합을 담은 **서명된 JSON 웹 토큰(JWT)**을 반환해요. 이 토큰은 RFC 7519를 준수해요. 이 토큰의 구조와 내용을 이해하면 안전한 인증 흐름을 구현하고, 외부 서비스에서 적절한 클레임 검증을 구성하고, 세분화된 접근 제어에 커스텀 클레임을 효과적으로 사용할 수 있어요.

출처: 문서

본문

JWT는 주체("sub"), 오디언스("aud"), 발급자("iss") 같은 표준 OpenID Connect(OIDC) 클레임을 포함해 다양한 외부 서비스 간의 상호운용성을 촉진해요. AWS STS는 적용 가능할 때 AWS 자격 증명 특정 클레임(예: AWS 계정 ID와 프린시펄 태그)과 세션 컨텍스트 클레임(예: EC2 인스턴스 ARN)으로 토큰을 채워요. 또한 GetWebIdentityToken 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"
    }
  }
}

표준 클레임

토큰에 포함된 표준 OIDC 클레임은 다양한 외부 서비스와의 상호운용성을 촉진해요. 이 클레임은 대부분의 JWT 라이브러리로 검증할 수 있어요.

클레임 이름 설명 예시 값
iss Issuer(발급자) — 계정별 발급자 URL. 외부 서비스는 이 클레임을 검증해 신뢰하는 발급자와 일치하는지 확인해요. https://abc123-def456-ghi789-jkl012.tokens.sts.global.api.aws
aud Audience(오디언스) — GetWebIdentityToken 요청에서 지정된 토큰의 의도된 수신자. https://api.example.com
sub Subject(주체) — 토큰을 요청한 IAM 프린시펄의 ARN. arn:aws:iam::123456789012:role/DataProcessingRole
iat Issued At(발급 시각) — JWT가 발급된 시각을 식별하는 NumericDate 값. 1700000000
exp Expiration(만료) — JWT가 처리를 위해 받아들여지지 않아야 하는 만료 시각을 식별하는 NumericDate 값. 1700000900
jti JWT ID — 이 토큰 인스턴스의 고유 식별자. xyz123-def456-ghi789-jkl012

커스텀 클레임

표준 OIDC 클레임 외에도 AWS STS는 적용 가능할 때 아이덴티티와 세션 컨텍스트에 대한 클레임을 추가해요. 또한 요청 태그로 전달해 자신만의 클레임을 토큰에 추가할 수 있어요. 커스텀 클레임은 https://sts.amazonaws.com/ 네임스페이스 아래에 중첩돼요.

AWS 자격 증명 클레임

이 클레임은 AWS 계정, 조직 구조, IAM 프린시펄에 대한 상세 정보를 제공해요.

클레임 설명 매핑되는 조건 키 예시 값
aws_account AWS 계정 ID aws:PrincipalAccount 123456789012
source_region 토큰이 요청된 AWS 리전 aws:RequestedRegion us-east-1
org_id AWS Organizations ID (계정이 조직의 일부인 경우) aws:PrincipalOrgID o-abc1234567
ou_path 조직 단위 경로 (해당되는 경우) aws:PrincipalOrgPaths o-a1b2c3d4e5/r-ab12/ou-ab12-11111111/ou-ab12-22222222/
principal_tags IAM 프린시펄 또는 수임 역할 세션에 붙은 태그. 요청하는 IAM 프린시펄이 프린시펄 태그와 세션 태그를 모두 가질 때 토큰 요청 중 세션 태그가 JWT에 존재해요. aws:PrincipalTag/ {"environment": "production", "team": "data-engineering", "cost-center":"engineering"}

세션 컨텍스트 클레임

이 클레임은 토큰 요청이 발생한 컴퓨팅 환경과 세션에 대한 정보를 제공해요. AWS STS는 요청하는 프린시펄의 세션 컨텍스트에 기반해 적용 가능할 때 이 클레임을 자동으로 포함해요.

클레임 설명 매핑되는 조건 키 예시 값
original_session_exp 원래 역할 세션 자격 증명이 만료되는 시각 (수임 역할용) N/A 2024-01-15T10:00:00Z
federated_provider 페더레이션 세션의 아이덴티티 프로바이더 이름 aws:FederatedProvider arn:aws:iam::111122223333:oidc-provider/your_oidc_provider
identity_store_user_id IAM Identity Center 사용자 ID identitystore:UserId user-abc123def456
identity_store_arn Identity Center 아이덴티티 스토어의 ARN identitystore:IdentityStoreArn arn:aws:identitystore::123456789012:identitystore/d-abc1234567
ec2_source_instance_arn 요청하는 EC2 인스턴스의 ARN ec2:SourceInstanceArn arn:aws:ec2:us-east-1:123456789012:instance/i-abc123def456
ec2_instance_source_vpc EC2 역할 자격 증명이 전달된 VPC ID aws:Ec2InstanceSourceVpc vpc-abc123def456
ec2_instance_source_private_ipv4 EC2 인스턴스의 프라이빗 IPv4 주소 aws:Ec2InstanceSourcePrivateIPv4 10.0.1.25
ec2_role_delivery 인스턴스 메타데이터 서비스 버전 ec2:RoleDelivery 2
source_identity 프린시펄이 설정한 소스 아이덴티티 aws:SourceIdentity admin-user
lambda_source_function_arn 호출하는 Lambda 함수의 ARN lambda:SourceFunctionArn arn:aws:lambda:us-east-1:123456789012:function:my-function
glue_credential_issuing_service Glue 작업용 AWS Glue 서비스 식별자 glue:CredentialIssuingService glue.amazonaws.com

요청 태그

GetWebIdentityToken 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"
  }
}

더 알아보기 (Learn more)