에 API 키 저장 AWS Secrets Manager 암호화 구성 API 키 자동 교체 보안 암호를 효율적으로 검색 민감한 워크로드에 대한 보안 강화 자주 묻는 질문(FAQ)

보안에 민감한 워크로드를 위한 API 키 관리

AWS Secrets Manager 를 사용하면 수명 주기 동안 데이터베이스 자격 증명, 애플리케이션 자격 증명, OAuth 토큰, API 키 및 기타 보안 암호를 관리, 검색 및 교체할 수 있습니다. 이 페이지에서는 보안에 민감한 워크로드에서 API 키 및 타사 자격 증명을 관리하기 위한 규범적 지침을 제공합니다. 자동 교체를 고객 관리형 AWS KMS 키 및 최소 권한 IAM 정책과 결합합니다. 또한 손상된 자격 증명의 노출 기간과 블래스트 반경을 최소화하도록 VPC 엔드포인트 액세스를 구성합니다.

에 API 키 저장 AWS Secrets Manager

이 섹션에서는 최적의 교체 및 검색을 위해 API 키 보안 암호를 구성하는 방법을 설명합니다. 각 API 키를 구조화된 JSON 값을 가진 별도의 보안 암호로 저장합니다. 이 구조를 사용하면 애플리케이션이 개별 필드를 검색할 수 있고 Secrets Manager가 올바른 값을 교체 함수에 전달할 수 있습니다.

다음 예제에서는 타사 API 키 보안 암호에 대한 일반적인 JSON 구조를 보여줍니다. 실제 필드는 공급자의 요구 사항에 따라 다릅니다. 저장해야 하는 특정 자격 증명 및 메타데이터는 공급자의 설명서를 참조하세요.


{
  "apiKey": "your-api-key-value",
  "apiKeyId": "key-identifier",
  "endpoint": "https://api.example.com/v1",
  "provider": "example-service"
}

API 키의 보안 암호 구조 예제
Field	예시 값	용도
`apiKey`	`sk_live_abc123...`	애플리케이션이 타사 API로 인증하는 데 사용하는 자격 증명 값입니다.
`apiKeyId`	`key_001`	공급자 측 키의 식별자입니다. 교체 중에 새 키를 생성하고 이전 키를 삭제하는 데 사용됩니다.
`endpoint`	`https://api.example.com/v1`	API 엔드포인트 URL. 검색에서 애플리케이션이 연결하는 데 필요한 모든 것을 반환하도록 키와 함께 저장합니다.
`provider`	`stripe`	공급자 이름입니다. 여러 공급자를 처리하는 태그 지정, 필터링 및 교체 함수 로직에 유용합니다.

각 보안 암호에 메타데이터를 지정하여 IAM 정책 조건 및 조직 필터링을 지원합니다. 예를 들어 AWS CLI 또는 콘솔을 사용하여 소유 팀, 환경 및 규정 준수 범위로 보안 암호에 태그를 지정할 수 있습니다.


aws secretsmanager tag-resource \
    --secret-id prod/payments/stripe-api-key \
    --tags Key=Team,Value=payments Key=Environment,Value=production \
           Key=Provider,Value=stripe Key=Compliance,Value=pci-dss

보안 암호 생성에 대한 자세한 내용은 섹션을 참조하세요AWS Secrets Manager 보안 암호 생성.

암호화 구성

Secrets Manager는 AWS KMS 키를 사용하여 저장된 모든 보안 암호 값을 암호화합니다. 보안에 민감한 워크로드의 경우 규정 준수 및 액세스 제어 요구 사항에 따라 암호화 키를 선택합니다.

API 키 보안 암호에 대한 KMS 키 옵션
키 유형	사용해야 하는 경우	보안 고려 사항
AWS 관리형 키(`aws/secretsmanager`)	대부분의 워크로드에 대해 기본값입니다. 추가 비용이나 키 관리 오버헤드가 없습니다.	키 정책은 Secrets Manager 작업으로만 제한되며 수정할 수 없습니다. 교차 계정 액세스에는 사용할 수 없습니다.
고객 관리형 키	규정 준수 요구 사항(예: PCI DSS, HIPAA, SOC 2 또는 기타 적용 가능한 표준). 교차 계정 보안 암호 공유. 키 사용 감사 요구 사항.	키 정책을 제어합니다. 복호화할 수 있는 보안 주체를 제한할 수 있습니다. 보안 암호와 독립적으로 키 삭제를 비활성화하거나 예약할 수 있습니다. 를 통해 독립적인 감사 추적을 제공합니다.

보안에 민감한 워크로드의 경우 다음 키 정책 조건과 함께 고객 관리형 키를 사용합니다.

kms:ViaService - 키 사용을 Secrets Manager()에서 시작된 요청으로 제한합니다secretsmanager.<region>.amazonaws.com.
kms:EncryptionContext:SecretARN - ARNs으로 제한합니다.
규정 준수 경계당 별도의 키 - 규정 준수 범위가 다른 보안 암호에 대해 다른 AWS KMS 키를 사용합니다(예: PCI와 비 PCI 비교).

암호화 및 복호화 프로세스에 대한 자세한 설명은 섹션을 참조하세요의 보안 암호 암호화 및 복호화 AWS Secrets Manager.

API 키 자동 교체

자동 교체는 손상된 자격 증명의 노출 기간을 줄입니다. Secrets Manager는 일정에 따라 Lambda 함수를 호출합니다. 함수는 공급자에 새 API 키를 생성하고, 보안 암호 값을 업데이트하고, 이전 키를 삭제합니다.

Secrets Manager는 관리형 외부 보안 암호를 통해 일부 타사 공급자를 위한 관리형 교체 기능을 제공합니다. 이 기능 및 지원되는 공급자 목록에 대한 자세한 내용은 섹션을 참조하세요관리형 외부 보안 암호 파트너. 관리형 교체 지원이 없는 공급자의 경우 공급자의 API를 호출하여 키를 생성하고 삭제하는 사용자 지정 Lambda 교체 함수를 구현합니다.

교체 함수 수명 주기

교체 Lambda 함수는 4단계를 구현합니다. Secrets Manager는 각 단계에 대해 함수를 한 번 호출하여 Step 파라미터를 전달합니다. 단계가 실패하면 Secrets Manager는 자동으로 전체 교체를 재시도합니다.

API 키의 교체 단계
단계	API 키에 대한 작업	장애 처리
`createSecret`	공급자 API를 호출하여 새 키를 생성합니다. `AWSPENDING` 스테이징 레이블을 사용하여 Secrets Manager에 새 키 값을 저장합니다.	키 생성에 실패하면 교체가 다음 단계로 진행되지 않습니다. 기존 키는 로 활성 상태로 유지됩니다`AWSCURRENT`.
`setSecret`	공급자에서 생성된 API 키의 경우이 단계는 일반적으로 no-op입니다. 이 단계는 Secrets Manager에서 임의 키가 생성되고 일반적인 API 키 흐름이 아닌 공급자에서 설정해야 하는 경우에 사용됩니다.	이 단계가 실패하면 교체가 로 진행되지 않습니다`testSecret`.
`testSecret`	Secrets Manager에서 `AWSPENDING` 값을 검색하고 공급자에게 테스트 API를 호출하여 새 키가 작동하는지 확인합니다.	테스트가 실패하면 공급자에서 보류 중인 키를 삭제하고 예외를 발생시킵니다.
`finishSecret`	새 키`AWSCURRENT`로 이동합니다. 이전 키가 로 이동합니다`AWSPREVIOUS`. 선택적으로 공급자에서 이전 키를 삭제합니다.	레이블 업데이트가 실패하면 교체가 완료되지 않습니다. 새 키가 존재하지만 아직 레이블이 지정되지 않았습니다`AWSCURRENT`.

전체 교체 함수 템플릿 및 구현 지침은 섹션을 참조하세요Lambda 교체 함수.

교체 일정 구성

규정 준수 요구 사항 및 내부 보안 정책에 따라 교체 간격을 설정합니다. 적절한 교체 빈도를 결정하려면 워크로드에 해당하는 규정 준수 표준을 참조하세요.

교체 창을 사용하여 교체 시기를 제어합니다. 이렇게 하면 피크 트래픽 또는 유지 관리 기간 동안 교체가 실행되지 않습니다.


aws secretsmanager rotate-secret \
    --secret-id prod/payments/stripe-api-key \
    --rotation-rules '{
        "ScheduleExpression": "cron(0 4 ? * SUN *)",
        "Duration": "2h"
    }'

일정 표현식 구문은 섹션을 참조하세요교체 일정.

보안 암호를 효율적으로 검색

Secrets Manager는 GetSecretValue 호출 시 초당 10,000개의 트랜잭션을 지원합니다. 대부분의 애플리케이션에서는 제한이 발생하지 않습니다. 호출 볼륨 또는 지연 시간에 민감한 경로가 매우 높은 애플리케이션의 경우 캐싱 솔루션을 사용하여 API 호출을 줄이고 응답 시간을 개선합니다.

Secrets Manager는 여러 언어에 대한 캐싱 클라이언트와 실행 환경 내에서 로컬로 암호를 캐싱하는 Lambda 확장을 제공합니다. 캐싱 옵션에 대한 자세한 내용은 클라이언트 측 캐싱과 함께 Java를 사용하여 Secrets Manager 보안 암호 값 가져오기, 클라이언트 측 캐싱과 함께 Python을 사용하여 Secrets Manager 보안 암호 값 가져오기및 단원을 참조하십시오클라이언트 측 캐싱과 함께 Go를 사용하여 Secrets Manager 보안 암호 값 가져오기.

모든 액세스 패턴에 대해 각 애플리케이션에 필요한 특정 보안 암호secretsmanager:GetSecretValue로 제한하는 IAM 정책을 구성합니다.


{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "secretsmanager:GetSecretValue",
    "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/payments/*",
    "Condition": {
      "StringEquals": {
        "aws:ResourceTag/Environment": "production"
      }
    }
  }]
}

민감한 워크로드에 대한 보안 강화

다음 관행은 엄격한 보안 요구 사항이 있는 환경(예: PCI DSS, SOC 2, HIPAA 또는 기타 적용 가능한 규정 준수 프레임워크)에서 API 키를 심층적으로 방어합니다.

VPC 엔드포인트를 사용하여 네트워크 액세스 제한: 보안 암호 검색이 퍼블릭 인터넷을 통과하지 않도록 Secrets Manager용 인터페이스 VPC 엔드포인트를 생성합니다. 엔드포인트를 통해 액세스할 수 있는 보안 암호를 제한하는 엔드포인트 정책을 적용합니다. 자세한 내용은 AWS Secrets Manager VPC 엔드포인트 사용 단원을 참조하십시오.
보안 암호에 리소스 정책 적용: 계정 외부 또는 특정 VPC 엔드포인트 외부의 보안 주체로부터의 액세스를 명시적으로 거부하는 각 보안 암호에 리소스 정책을 연결합니다. 이는 IAM 자격 증명 정책과 독립적인 두 번째 권한 부여 경계를 제공합니다.
를 사용하여 보안 암호 액세스 모니터링: 는 , GetSecretValue PutSecretValue및를 포함하여 모든 Secrets Manager API 호출을 자동으로 기록합니다RotateSecret. 보안에 민감한 보안 암호의 경우 인식할 수 없는 소스 IP 주소 또는 IAM 보안 주체의 GetSecretValue 호출과 같은 예상치 못한 호출에서 트리거되는 Amazon CloudWatch 경보를 생성합니다.
정상적인 교체AWSPREVIOUS에 사용: 교체 중에 Secrets Manager는 AWSPREVIOUS 스테이징 레이블과 함께 이전 키 값을 유지합니다. 새 키가 생성될 때 공급자가 이전 키를 무효화하는 경우에서 인증 오류를 AWSCURRENT 반환AWSPREVIOUS하면 로 돌아가도록 애플리케이션을 구성합니다. 이렇게 하면 키 생성과 레이블 업데이트 사이의 짧은 기간 동안 가동 중지가 방지됩니다.
연결하기 전에 리소스 정책 검증: 리소스 정책이 없는 보안 암호는 이미 퍼블릭 액세스를 차단하고 있습니다. 보안 암호에 리소스 정책을 연결할 때 ValidateResourcePolicy API를 사용하여 정책이 광범위한 퍼블릭 액세스 권한을 부여하지 않도록 합니다. BlockPublicPolicy 파라미터를와 함께 사용하여 퍼블릭 액세스 권한을 부여하는 정책이 연결되지 않도록 PutResourcePolicy할 수도 있습니다. 리소스 정책에서 aws:PrincipalOrgID 조건 키를 사용하여 조직 외부의 보안 주체로부터의 액세스를 방지합니다.

자주 묻는 질문(FAQ)

이 섹션에서는의 API 키 교체 및 보안 암호 관리에 대한 일반적인 질문에 답변합니다 AWS Secrets Manager.

교체 중에 중복 기간을 처리하려면 어떻게 해야 합니까?

이는 새 키가 생성될 때 공급자가 기존 키를 무효화하는 경우에만 필요합니다. 공급자가 여러 활성 키를 동시에 지원하는 경우 두 키 모두 교체 기간 동안 애플리케이션 측 폴백 로직 없이 작동합니다. 이전 키를 무효화하는 공급자의 경우 현재 키가 401 또는 403 오류를 반환하는 AWSPREVIOUS 경우 로 재시도하도록 애플리케이션을 구성합니다. 새 키가 작동하는지 확인한 후에만 finishSecret 단계에서 공급자의 이전 키를 삭제합니다.

공급자가 프로그래밍 방식 키 생성을 지원하지 않는 경우 어떻게 되나요?

공급자가 수동 키 생성(예: 웹 콘솔을 통해)을 요구하는 경우 교체를 완전히 자동화할 수 없습니다. 대신 교체 기한이 되면 (Amazon Simple Notification Service를 통해) 알림을 보내는 교체 함수를 사용하여 운영자에게 키를 수동으로 생성하고 보안 암호 값을 업데이트하라는 메시지를 표시합니다. 규정 준수 교체 요구 사항에 맞게 교체 일정을 설정하고에서 Amazon CloudWatch 경보days_since_last_rotation를 사용하여 누락된 교체를 감지합니다.

보안 암호를 검색할 때 API 제한을 방지하려면 어떻게 해야 합니까?

Secrets Manager는에서 초당 10,000개의 트랜잭션을 지원합니다GetSecretValue. 대부분의 애플리케이션에서는 제한이 발생하지 않습니다. 애플리케이션이 매우 많은 양의 호출을 수행하는 경우 캐싱 클라이언트 또는 Lambda 파라미터 및 보안 암호 확장을 사용합니다. 이들은 보안 암호 값을 메모리에 캐싱하고 주기적으로 새로 고쳐 API 호출 수를 줄입니다. 애플리케이션이 교체 후 새 키를 선택하도록 캐시 TTL을 교체 간격보다 짧은 값으로 설정합니다.

환경당 하나의 보안 암호를 사용해야 합니까? 아니면 버전과 함께 하나의 보안 암호를 사용해야 합니까?

각 환경에 대해 별도의 보안 암호를 사용합니다(예: prod/payments/stripe 및 dev/payments/stripe). 이렇게 하면 환경별로 다양한 IAM 정책, 교체 일정 및 암호화 키가 허용됩니다. 보안 암호 버전(스테이징 레이블)은 환경 분리가 아닌 교체 상태 관리를 위한 것입니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

모범 사례

자습서