아웃바운드 아이덴티티 페더레이션 시작하기

아웃바운드 아이덴티티 페더레이션 시작하기 (Getting started with outbound identity federation)

이 가이드는 AWS 계정에 아웃바운드 아이덴티티 페더레이션을 활성화하고 첫 번째 JSON 웹 토큰(JWT)을 얻는 방법(GetWebIdentityToken API 사용)을 보여줘요. 기능을 활성화하고, 외부 서비스와 신뢰 관계를 확립하고, IAM 권한을 구성하고, AWS CLI 또는 AWS SDK for Python(Boto3)으로 토큰을 요청하게 됩니다.

출처: 문서

본문

사전 요구 사항

시작하기 전에 다음이 있어야 해요.

최신 버전의 AWS CLI 또는 Python 3.8(이후)과 Boto3 설치(AWS SDK 예시용)
신뢰 관계를 구성할 수 있는 외부 서비스 계정(예: 외부 클라우드 프로바이더, SaaS 프로바이더, 테스트 애플리케이션)

참고

GetWebIdentityToken API는 STS 전역 엔드포인트에서는 사용할 수 없어요.
GetWebIdentityToken API가 생성하는 JSON 웹 토큰(JWT)은 AWS로의 OpenID Connect(OIDC) 페더레이션(AssumeRoleWithWebIdentity API 경유)에는 사용할 수 없어요.

계정에 아웃바운드 아이덴티티 페더레이션 활성화

토큰을 요청하려면 먼저 아웃바운드 아이덴티티 페더레이션을 활성화해야 해요. 이 기능은 AWS Management Console 또는 EnableOutboundWebIdentityFederation API로 프로그래밍 방식으로 활성화할 수 있어요.

AWS CLI 사용

aws iam enable-outbound-web-identity-federation

AWS SDK for Python 사용

import boto3

# Create IAM client
iam_client = boto3.client('iam')

# Enable outbound identity federation
response = iam_client.enable_outbound_web_identity_federation()
print(f"Feature enabled. Issuer URL: {response['IssuerUrl']}")
print(f"Status: {response['Status']}")

AWS 콘솔 사용

IAM으로 이동해 왼쪽 탐색 메뉴의 Access Management 섹션 아래 Account Settings를 선택해요.

기능을 활성화한 뒤 **계정별 발급자 URL(issuer URL)**을 기록해 두세요. 이 URL은 외부 서비스에서 신뢰 관계를 구성할 때 사용해요. 필요할 때 GetOutboundWebIdentityFederationInfo API로 이 발급자 URL을 검색할 수도 있어요.

외부 서비스에 신뢰 관계 확립

외부 서비스가 AWS 계정이 발급한 토큰을 신뢰하고 받아들이도록 구성해요. 구체적인 단계는 서비스마다 다르지만 일반적으로 다음을 포함해요.

AWS 계정 발급자 URL을 신뢰할 수 있는 아이덴티티 프로바이더로 등록
검증할 클레임 구성(오디언스, 주체 패턴)
토큰 클레임을 외부 서비스의 권한에 매핑

자세한 구성 지침은 외부 서비스 문서를 참고하세요.

IAM 권한 구성

GetWebIdentityToken API 호출 권한을 부여하는 IAM 정책을 만들고, 토큰을 생성해야 하는 IAM 역할에 그 정책을 연결해요.

이 예시 정책은 특정 제한과 함께 토큰 생성에 접근을 부여해요. 오디언스로 "https://api.example.com"에만 토큰을 요청하도록 허용하고 최대 토큰 수명을 5분(300초)으로 강제해요. 토큰 속성을 강제하는 데 사용할 수 있는 조건 키 목록은 IAM과 AWS STS 조건 컨텍스트 키를 참고하세요.

예시 IAM 정책

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "sts:GetWebIdentityToken",
            "Resource": "*",
            "Condition": {
                "ForAllValues:StringEquals": {
                    "sts:IdentityTokenAudience": "https://api.example.com"
                },
                "NumericLessThanEquals": {
                    "sts:DurationSeconds": 300
                }
            }
        }
    ]
}

첫 번째 JSON 웹 토큰(JWT) 요청

GetWebIdentityToken API로 JSON 웹 토큰을 요청할 수 있어요. API를 호출할 때 다음 파라미터를 지정할 수 있어요.

Audience (필수) — 토큰의 의도된 수신자. 이 값은 JWT의 "aud" 클레임을 채워요. 외부 서비스는 이 클레임을 검증해 토큰이 자기에게 의도된 것인지 확인해요.
SigningAlgorithm (필수) — 토큰을 서명하는 데 사용할 암호화 알고리즘. 유효한 값은 ES384와 RS256이에요. 최적의 보안·성능을 위해 ES384를, ECDSA를 지원하지 않는 시스템과의 더 넓은 호환성을 위해 RS256을 사용하세요.
DurationSeconds (선택) — 토큰 수명(초). 유효한 값은 60~3600이에요. 기본값은 300(5분)이에요. 보안 강화를 위해 더 짧은 토큰 수명을 권장해요.
Tags (선택) — 토큰에 커스텀 클레임으로 포함할 키-값 쌍 목록. 외부 서비스가 세분화된 인가에 이 클레임을 사용할 수 있어요.

API는 다음 필드를 반환해요.

IdentityToken — base64url 인코딩 문자열로 된 서명된 JWT. 이 토큰을 외부 서비스에 대한 요청에 포함해요.
Expiration — 토큰이 만료되는 UTC 타임스탬프.

AWS CLI 사용

aws sts get-web-identity-token \
    --audience "https://api.example.com" \
    --signing-algorithm ES384 \
    --duration-seconds 300 \
    --tags Key=team,Value=data-engineering \
           Key=environment,Value=production \
           Key=cost-center,Value=analytics

AWS SDK for Python 사용

import boto3

sts_client = boto3.client('sts')

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

token = response['WebIdentityToken']

PyJWT, Python-jose(파이썬), Nimbus JOSE+JWT(자바) 같은 표준 JWT 라이브러리나 jwt.io 같은 디버거로 JWT를 디코딩해 내용을 검사할 수도 있어요. 토큰에 포함된 클레임에 대한 자세한 내용은 토큰 클레임 이해를 참고하세요.

외부 서비스와 함께 토큰 사용

토큰을 받은 뒤에는 외부 서비스에 대한 요청에 포함해요. 방법은 서비스마다 다르지만 대부분의 서비스는 Authorization 헤더에 토큰을 받아요. 외부 서비스는 발급자의 잘 알려진 엔드포인트에서 JWKS 키를 가져와 토큰의 서명을 검증하고 필수 클레임을 검증한 뒤 AWS 워크로드에 접근을 부여하는 토큰 검증 로직을 구현해야 해요.

OIDC(OpenID Connect) 엔드포인트에서 검증 키와 메타데이터 가져오기

AWS 계정의 고유 발급자 URL은 토큰 검증에 필요한 검증 키와 메타데이터를 담은 OIDC(OpenID Connect) 디스커버리 엔드포인트를 호스팅해요.

OIDC 디스커버리 엔드포인트 URL은 일부 프로바이더가 토큰을 검증하는 데 사용하는 메타데이터를 담고 있어요. 다음 위치에 있어요.

{issuer_url}/.well-known/openid-configuration

JWKS(JSON Web Key Set) 엔드포인트는 토큰 서명을 검증하는 데 사용되는 키를 담고 있어요. 다음 위치에 있어요.

{issuer_url}/.well-known/jwks.json

curl로 JWKS 가져오기

curl https://{issuer_url}/.well-known/jwks.json

응답:

{
  "keys": [
    {
      "kty": "EC",
      "use": "sig",
      "kid": "key-id-1",
      "alg": "ES384",
      "crv": "P-384",
      "x": "base64-encoded-x-coordinate",
      "y": "base64-encoded-y-coordinate"
    },
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "key-id-2",
      "n": "base64-encoded-modulus",
      "e": "AQAB"
    }
  ]
}

AWS SDK for Python 사용

import requests

# Fetch Openid Configuration
open_id_config_response = requests.get("https://{issuer_url}/.well-known/openid-configuration")
open_id_config = open_id_config_response.json()

# Fetch JWKS
jwks_response = requests.get("https://{issuer_url}/.well-known/jwks.json")
jwks = jwks_response.json()

매 토큰 검증마다 가져오는 것을 피하기 위해 이 키들을 캐시하길 권장해요.

필수 클레임 검증

Subject (sub) — 주체 클레임이 예상하는 IAM 프린시펄 ARN 패턴을 포함하는지 검증해요.
Expiration (exp) — 토큰이 만료되지 않았는지 확인해요. JWT 라이브러리가 보통 자동으로 처리해요.
Audience (aud) — 오디언스가 예상 값과 일치하는지 검증해요. 다른 서비스용으로 의도된 토큰이 우리 것에 사용되는 것을 방지해요.
Issuer (iss) — 발급자가 우리가 신뢰하는 AWS 계정과 일치하는지 검증해요. 신뢰하는 발급자 URL 목록을 유지하세요.

가능하면 AWS 특정 클레임을 추가로 검증해 외부 서비스에서 세분화된 접근 제어를 구현하세요. 예를 들어 org_id 클레임을 검증해 AWS Organization의 IAM 프린시펄만 접근하게 제한하거나, principal_tags를 확인해 속성 기반 접근 제어(프로덕션 환경이나 특정 팀만 허용하는 등)를 강제하거나, lambda_source_function_arn이나 ec2_instance_source_vpc 같은 세션 컨텍스트 클레임을 검증해 컴퓨팅 리소스를 기준으로 접근을 제한할 수 있어요. 토큰에 포함된 클레임의 전체 목록은 토큰 클레임 이해를 참고하세요.

더 알아보기 (Learn more)

토큰 클레임 이해 — JWT에 포함된 클레임을 확인해 보세요.
IAM 정책으로 접근 제어 — 토큰 생성을 제어하는 방법을 살펴보세요.
AWS 아이덴티티를 외부 서비스로 페더레이션 — 아웃바운드 페더레이션의 개요를 참고하세요.