Karan Vaghela 작성 | P P Savani University의 AWS Student Builder Groups 리더 | Cybersecurity & Cloud

AWS 프로젝트가 해킹당하는 가장 빠른 방법은 자격 증명(Credentials)을 어딘가에 하드코딩하는 것입니다. 실수로 GitHub에 푸시된 .env 파일 속의 AWS_ACCESS_KEY_ID는 전형적인 실수이며, 이는 초보자뿐만 아니라 숙련된 엔지니어들에게도 발생합니다.

프로젝트를 위해 Amazon Bedrock에서 Claude를 설정할 때, 저는 전체 흐름이 IAM 역할(Roles)과 프로필(Profiles)을 사용하도록 하여 어디에도 하드코딩된 키가 남지 않도록 했습니다. 이 포스트에서는 그 방법을 정확히 어떻게 수행하는지, 왜 그것이 중요한지, 그리고 제가 진행 과정에서 겪었던 구체적인 주의 사항(Gotchas)들을 살펴봅니다.

액세스 키(Access Keys) 대신 IAM 역할(IAM Roles)을 사용해야 하는 이유

액세스 키는 수명이 긴 자격 증명입니다. 만약 키가 유출되면, 공격자는 사용자가 수동으로 교체(Rotate)하거나 취소(Revoke)할 때까지 지속적인 접근 권한을 갖게 됩니다. 반면, IAM 역할(IAM Roles)은 자동으로 만료되는 임시 자격 증명을 발급합니다. 이는 AWS 인프라에서 실행되는 모든 애플리케이션에 대해 AWS가 권장하는 방식이며, 패턴을 이해하고 나면 로컬 개발 시에도 사용해야 하는 방식입니다.

여기에서의 보안 원칙은 간단합니다: 자격 증명은 가능한 한 수명이 짧고 범위(Scoped)가 제한적이어야 합니다. IAM을 올바르게 설정하면 이것이 기본값이 됩니다.

설정: IAM을 통한 Bedrock 상의 Claude Code CLI

제가 사용한 정확한 구성입니다. 목표는 어떤 설정 파일에도 키를 남기지 않고, 전적으로 IAM을 통해 인증하며 Bedrock을 백엔드로 사용하는 Claude Code CLI를 실행하는 것이었습니다.

1단계: 이름이 지정된 AWS 프로필 생성

기본(Default) 프로필을 사용하는 대신, 컨텍스트를 깔끔하게 전환할 수 있도록 이름이 지정된 프로필을 생성하세요.

~/.aws/credentials 수정:

[bedrock-dev]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY

그리고 ~/.aws/config 수정:

[profile bedrock-dev]
region = us-east-1
output = json

이 방식은 여전히 로컬에서 액세스 키를 사용하고 있지만, 이름이 지정된 프로필로 범위가 제한되어 있으며 절대 기기를 벗어나지 않습니다. 핵심적인 움직임은 그다음에 일어납니다.

2단계: IAM 정책(IAM Policy) 범위 지정

Bedrock에 필요한 권한만 부여하는 IAM 정책(IAM Policy)을 생성하세요. 그 이상은 안 됩니다.

{
  "Version": "2012-10-17",
  "Statement": [
...

이 정책을 IAM 사용자(User) 또는 역할(Role)에 연결(Attach)하세요. AdministratorAccess나 와일드카드 리소스(Wildcard resource)를 사용하지 마세요. 최소 권한 원칙(Least privilege)이 규칙입니다.

3단계: Bedrock을 사용하도록 Claude Code 설정하기

~/.claude/settings.json 파일에서:

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
...

여기서 주의해야 할 세 가지 사항이 있습니다:

AWS_REGION은 반드시 명시해야 합니다. AWS 설정(Config)에서 자동으로 가져올 것이라고 가정하지 마세요. 이 설정이 누락되면 Claude Code는 아무런 오류 메시지 없이 실패하거나, 모델을 사용할 수 없는 기본 리전(Default region)으로 돌아가 버립니다. 항상 직접 설정하세요.

AWS_PROFILE은 정확히 일치해야 합니다. 여기에 입력하는 문자열은 대소문자를 포함하여 ~/.aws/config에 있는 프로필 이름과 정확히 일치해야 합니다.

Bedrock 모드에서는 /login 및 /logout 명령어가 작동하지 않습니다. 이 명령어들은 API 키를 사용하는 Anthropic의 직접 API 전용입니다. Bedrock 모드에서는 인증이 전적으로 AWS 자격 증명(Credentials)에 의해 처리됩니다. 이 명령어들을 찾지 마세요.

4단계: 연결 확인하기

간단한 테스트를 실행하세요:

aws bedrock list-foundation-models --profile bedrock-dev --region us-east-1 | grep claude

Claude 모델 목록이 보인다면 IAM 설정이 올바르고 Bedrock에 접근할 수 있는 상태입니다. 만약 AccessDeniedException이 발생한다면 정책(Policy)을 확인하세요. 리전 관련 오류가 발생한다면, 선택한 리전에서 실제로 Bedrock을 사용할 수 있는지 확인하세요. 모든 리전에서 지원되는 것은 아닙니다.

프로덕션 패턴: 키를 전혀 사용하지 않는 방법

만약 EC2 인스턴스, Lambda, 또는 기타 AWS 컴퓨팅 리소스에서 이를 실행한다면, 그 어디에도 액세스 키(Access keys)를 두어서는 안 됩니다. 대신, 컴퓨팅 리소스에 IAM 역할(IAM role)을 직접 연결하세요.

EC2의 경우:

1. 위의 Bedrock 정책이 연결된 IAM 역할을 생성합니다.
2. Actions > Security > Modify IAM Role 메뉴를 통해 해당 역할을 EC2 인스턴스에 연결합니다.
3. 해당 머신의 자격 증명(Credentials) 파일에서 모든 aws_access_key_id 및 aws_secret_access_key를 제거합니다.

AWS SDK는 인스턴스 메타데이터 서비스 (Instance Metadata Service)로부터 자격 증명 (Credentials)을 자동으로 가져옵니다. 애플리케이션 코드는 변경할 필요가 없습니다. ~/.aws/config 파일에는 리전 (Region) 정보만 있으면 됩니다:

[default]
region = us-east-1

키도, 비밀 값도 필요 없습니다. 역할 (Role)이 모든 것을 처리합니다.

하지 말아야 할 것

사람들이 흔히 사용하지만 피해야 할 몇 가지 패턴이 있습니다:

.env 파일에 자격 증명을 넣고 .gitignore에 .env를 추가하지 마세요. 아무것도 안 하는 것보다는 낫지만 여전히 위험합니다. .gitignore 규칙에는 예외 상황이 존재하며, 만약 git add -f를 실행하거나 설정을 잘못하면 해당 키들은 영원히 Git 히스토리에 남게 됩니다. IAM 프로필 (IAM profiles)을 사용하세요.

루트 계정 (Root account) 자격 증명을 어떤 용도로도 사용하지 마세요. 절대로 말입니다. 필요한 권한만 가진 IAM 사용자 (IAM user)를 생성하세요. 루트 계정은 MFA (다요소 인증)가 활성화되어 있어야 하며, 그 외의 어떤 것도 해당 계정에 접근해서는 안 됩니다.

환경 간에 자격 증명을 공유하지 마세요. 개발용 IAM 사용자와 운영 환경의 IAM 역할은 서로 다른 정책을 가진 완전히 분리된 ID여야 합니다. 개발용 자격 증명이 유출되더라도 운영 환경은 영향을 받지 않아야 합니다.

보안 그 이상의 중요성

실무 운영 (Ops) 측면에서도 이점이 있습니다. IAM 프로필과 역할을 제대로 사용하면 자격 증명 교체 (Rotation)가 아무런 문제 없이 이루어집니다. 한 곳에서 IAM 사용자의 키를 업데이트하고 ~/.aws/credentials를 업데이트하면, 하위의 모든 시스템이 이를 반영합니다. 여러 프로젝트에 걸쳐 .env 파일을 뒤질 필요가 없습니다.

학생이나 커리어 초기에 있는 분들에게 지금 이러한 습관을 기르는 것은, 실수로 API 키를 커밋하는 엔지니어가 되지 않음을 의미합니다. 이는 생각보다 훨씬 중요한 문제입니다.

빠른 참조

Bedrock은 자체 인프라를 관리하지 않고도 파운데이션 모델 (Foundation models)을 실행할 수 있는 강력한 방법입니다. 처음부터 IAM을 통해 적절하게 설정하면, 수많은 초기 프로젝트를 좌절시키는 보안 부채 (Security debt) 없이 그 모든 강력한 기능을 누릴 수 있습니다.

이 설정을 진행하는 동안 특정 오류가 발생하면 댓글로 남겨주세요. 디버깅을 기꺼이 도와드리겠습니다.

Tags: #aws #bedrock #iam #security #cloud #beginners