View a markdown version of this page

AWS 워크로드 자격 증명 공급자 사용 - AWS Secrets Manager
AWS 워크로드 자격 증명 공급자의 작동 방식AWS 워크로드 자격 증명 공급자 캐싱 이해AWS 워크로드 자격 증명 공급자 다운로드소스에서 AWS 워크로드 자격 증명 공급자 빌드AWS 워크로드 자격 증명 공급자 설치AWS 워크로드 자격 증명 공급자를 사용하여 보안 암호 검색refreshNow 파라미터 이해역할 체인을 사용하여 계정 간 보안 암호 검색시작 시 보안 암호 미리 가져오기구성 옵션선택적 기능로깅보안 고려 사항

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

AWS 워크로드 자격 증명 공급자 사용

AWS 워크로드 자격 증명 공급자의 작동 방식

AWS 워크로드 자격 증명 공급자(이전 AWS Secrets Manager 에이전트)는 컴퓨팅 환경에서 Secrets Manager의 보안 암호를 사용하는 방법을 표준화하는 데 도움이 되는 클라이언트 측 HTTP 서비스를 제공합니다. 다음 서비스와 함께 사용할 수 있습니다.

  • AWS Lambda

  • Amazon Elastic Container Service

  • Amazon Elastic Kubernetes Service:

  • - Amazon Elastic Compute Cloud

AWS 워크로드 자격 증명 공급자는 보안 암호를 검색하고 메모리에 캐시하므로 애플리케이션이 Secrets Manager를 직접 호출하는 대신 localhost에서 보안 암호를 가져올 수 있습니다. AWS 워크로드 자격 증명 공급자는 보안 암호만 읽을 수 있으며 수정할 수는 없습니다.

AWS 워크로드 자격 증명 공급자는 오픈 소스입니다. 소스 코드, 설치 지침 및 최신 릴리스 정보는 GitHub에서 확인할 수 있습니다.

중요

AWS 워크로드 자격 증명 공급자는 환경의 AWS 자격 증명을 사용하여 Secrets Manager를 호출합니다. 또한 서버 측 요청 위조(SSRF)로부터 보호 기능을 제공하여 보안 암호의 안전성을 높입니다. AWS 워크로드 자격 증명 공급자는 기본적으로 포스트 퀀텀 ML-KEM 키 교환을 우선순위가 가장 높은 키 교환으로 사용합니다.

AWS 워크로드 자격 증명 공급자 캐싱 이해

AWS 워크로드 자격 증명 공급자는 AWS 워크로드 자격 증명 공급자가 다시 시작될 때 재설정되는 인 메모리 캐시를 사용합니다. 캐시된 보안 암호 값은 다음 기준으로 주기적으로 갱신됩니다.

  • 기본 갱신 주기(TTL)는 300초

  • 구성 파일을 통해 TTL을 수정할 수 있음

  • TTL이 만료된 후 보안 암호를 요청하면 갱신이 발생

참고

AWS 워크로드 자격 증명 공급자에는 캐시 무효화가 포함되지 않습니다. 캐시 항목이 만료되기 전에 보안 암호가 교체되면 AWS 워크로드 자격 증명 공급자가 오래된 보안 암호 값을 반환할 수 있습니다.

AWS 워크로드 자격 증명 공급자는의 응답과 동일한 형식으로 보안 암호 값을 반환합니다GetSecretValue. 보안 암호 값은 캐시에서 암호화되지 않습니다.

AWS 워크로드 자격 증명 공급자 다운로드

AWS 워크로드 자격 증명 공급자의 사전 구축된 바이너리를 다운로드하려면 다음 링크를 사용합니다. Windows용 릴리스가 서명됩니다.

플랫폼 아키텍처 다운로드 URL 체크섬(SHA-256)

Linux

x86-64

Linux x86-64용 다운로드(3.1.1)

471c1978f8bf63a0aeefb425e974ac3c816c7e04feb302236512eea375160de4

Linux

AArch64

Linux AArch64용 다운로드(3.1.1)

8b09dc4e58b84379f580a9ae179940bcb3de0338421f638a43376bf73380ffb6

Windows

x86-64

Windows x86-64용 다운로드(3.1.1)

5fbdac4017e630556b94b90e5ed9ed11be69ac7a47e67655e20181ce990dbe12

소스에서 AWS 워크로드 자격 증명 공급자 빌드

또는 소스에서 AWS 워크로드 자격 증명 공급자를 빌드할 수 있습니다. 시작하기 전에 플랫폼에 표준 개발 도구 및 Rust 도구가 설치되어 있는지 확인합니다.

참고

macOS에서 활성화된 fips 기능을 사용하여 공급자를 빌드하려면 현재 다음 해결 방법이 필요합니다.

  • xcrun --show-sdk-path 실행의 결과로 설정된 SDKROOT라는 환경 변수를 생성합니다.

RPM-based systems
RPM 기반 시스템에서 빌드하는 방법

  1. 리포지토리에 제공된 install 스크립트를 실행합니다.

    스크립트는 시작 시 무작위 SSRF 토큰을 생성한 후 이를 /var/run/awssmatoken 파일에 저장합니다. 설치 스크립트가 생성하는 aws-wcp-token 그룹에서 토큰을 읽을 수 있습니다.

  2. 애플리케이션이 토큰 파일을 읽을 수 있도록 하려면 애플리케이션을 실행하는 사용자 계정을 aws-wcp-token 그룹에 추가해야 합니다. 예를 들어 다음 usermod 명령을 사용하여 토큰 파일을 읽을 수 있는 권한을 애플리케이션에 부여할 수 있습니다. 여기서 <APP_USER>는 애플리케이션을 실행하는 사용자 ID입니다.

    sudo usermod -aG aws-wcp-token <APP_USER>
    개발 도구 설치

    AL2023과 같은 RPM 기반 시스템에서는 개발 도구 그룹을 설치합니다.

    sudo yum -y groupinstall "Development Tools"
  3. Rust 설치

    Rust 설명서의 Rust 설치 지침에 따라 설치합니다.

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
. "$HOME/.cargo/env"
  4. 공급자 빌드

    화물 빌드 명령을 사용하여 AWS 워크로드 자격 증명 공급자를 빌드합니다.

    cargo build --release

    target/release/aws-workload-credentials-provider에서 실행 파일을 찾을 수 있습니다.

Debian-based systems
Debian 기반 시스템에서 빌드하는 방법
  1. 개발 도구 설치

    Ubuntu와 같은 Debian 기반 시스템에서는 build-essential 패키지를 설치합니다.

    sudo apt install build-essential
  2. Rust 설치

    Rust 설명서의 Rust 설치 지침에 따라 설치합니다.

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
. "$HOME/.cargo/env"
  3. 공급자 빌드

    화물 빌드 명령을 사용하여 AWS 워크로드 자격 증명 공급자를 빌드합니다.

    cargo build --release

    target/release/aws-workload-credentials-provider에서 실행 파일을 찾을 수 있습니다.

Windows
Windows에서 빌드하는 방법
  1. 개발 환경 설정

    Microsoft Windows 설명서의 Windows용 Rust 개발 환경 설정 지침에 따라 개발 환경을 설정합니다.

  2. 공급자 빌드

    화물 빌드 명령을 사용하여 AWS 워크로드 자격 증명 공급자를 빌드합니다.

    cargo build --release

    target/release/aws-workload-credentials-provider.exe에서 실행 파일을 찾을 수 있습니다.

Cross-compile natively
기본적으로 교차 컴파일하는 방법
  1. 교차 컴파일 도구 설치

    cargo-xwin을 설치합니다.

    cargo install cargo-xwin
  2. Rust 빌드 대상 추가

    Windows MSVC 빌드 대상을 설치합니다.

    rustup target add x86_64-pc-windows-msvc
  3. Windows용으로 빌드

    Windows용 공급자를 교차 컴파일합니다.

    cargo xwin build --release --target x86_64-pc-windows-msvc

    target/x86_64-pc-windows-msvc/release/aws-workload-credentials-provider.exe에서 실행 파일을 찾을 수 있습니다.

AWS 워크로드 자격 증명 공급자 설치

다음 설치 옵션 중에서 사용할 컴퓨팅 환경을 선택합니다.

Amazon EC2

Amazon EC2 Linux 인스턴스에서는 RPM 패키지(AL2023에 사용 가능) 또는 수동 설치 스크립트를 사용하여 AWS 워크로드 자격 증명 공급자를 설치할 수 있습니다.

옵션 A: RPM 패키지 설치(AL2023)
  1. 패키지 설치

    RPM 패키지를 설치합니다. 패키지 관리자가 최신 버전을 찾습니다.

    sudo dnf install aws-workload-credentials-provider

    RPM 패키지는 다음을 자동으로 설정합니다.

    • awscreds 및 aws-wcp-token 그룹과 함께 aws-wcp 서비스 사용자입니다.

    • 의 바이너리 및 헬퍼 스크립트입니다/opt/aws/workload-credentials-provider/.

    • 자동으로 시작되는 AWS Secrets Manager 및 토큰 systemd 서비스입니다.

    • 의 무작위 SSRF 토큰입니다/var/run/awssmatoken.

    Secrets Manager 기능은 설치 직후 사용할 수 있습니다. RPM 패키지로를 설치하면 AWS 워크로드 자격 증명 공급자가 기본 경로에서 구성 옵션을 읽습니다/etc/aws-workload-credentials-provider/config.toml. 구성을 사용자 지정하려면 해당 파일을 생성하거나 편집합니다.

  2. (선택 사항) 인증서 관리 기능 활성화

    에서 인증서를 검색하고 새로 고치려면 AWS Certificate Manager 사용 설명서의 인증서 자동화를 AWS Certificate Manager참조하세요.

  3. 애플리케이션 권한 구성

    애플리케이션이 SSRF 토큰 파일을 읽을 수 있도록 하려면 애플리케이션의 사용자 계정을 aws-wcp-token 그룹에 추가합니다.

    sudo usermod -aG aws-wcp-token APP_USER

    APP_USER를 애플리케이션이 실행되는 사용자 ID로 바꿔 입력합니다.

  4. (선택 사항) 공급자 로그에 대한 액세스 권한 부여

    공급자 로그를 읽으려면 awscreds 그룹에 사용자를 추가한 다음 로그아웃했다가 다시 로그인(또는 실행newgrp awscreds)하면 변경 사항이 적용됩니다.

    sudo usermod -aG awscreds APP_USER
AWS 워크로드 자격 증명 공급자 제거

AWS 워크로드 자격 증명 공급자를 제거하려면를 실행합니다sudo dnf remove aws-workload-credentials-provider. 제거하면 모든 서비스가 중지되고 바이너리 및 서비스 단위가 제거됩니다. 제거 프로세스는 aws-wcp 사용자, 그룹 및 로그 디렉터리를 보존합니다.

옵션 B: 설치 스크립트 실행(모든 Linux)
  1. 구성 디렉터리로 이동

    구성 디렉터리로 변경합니다.

    cd aws_workload_credentials_provider_common/configuration
  2. 설치 스크립트 실행

    리포지토리에 제공된 install 스크립트를 실행합니다.

    스크립트는 시작 시 무작위 SSRF 토큰을 생성한 후 이를 /var/run/awssmatoken 파일에 저장합니다. 설치 스크립트가 생성하는 aws-wcp-token 그룹에서 토큰을 읽을 수 있습니다.

  3. 애플리케이션 권한 구성

    애플리케이션이 실행되는 사용자 계정을 aws-wcp-token 그룹에 추가합니다.

    sudo usermod -aG aws-wcp-token APP_USER

    APP_USER를 애플리케이션이 실행되는 사용자 ID로 바꿔 입력합니다.

Container Sidecar

Docker를 사용하여 AWS 워크로드 자격 증명 공급자를 애플리케이션과 함께 사이드카 컨테이너로 실행할 수 있습니다. 그런 다음 애플리케이션은 AWS 워크로드 자격 증명 공급자가 제공하는 로컬 HTTP 서버에서 보안 암호를 검색할 수 있습니다. Docker에 대한 자세한 내용은 Docker 설명서를 참조하세요.

AWS 워크로드 자격 증명 공급자를 위한 사이드카 컨테이너를 생성하려면
  1. 공급자 Dockerfile 생성

    AWS 워크로드 자격 증명 공급자 사이드카 컨테이너에 대한 Dockerfile을 생성합니다.

    # Use the latest Debian image as the base
FROM debian:latest

# Set the working directory inside the container
WORKDIR /app 

# Copy the Workload Credentials Provider binary to the container
COPY aws-workload-credentials-provider . 

# Install any necessary dependencies
RUN apt-get update && apt-get install -y ca-certificates 

# Set the entry point to run the provider
ENTRYPOINT ["./aws-workload-credentials-provider", "sm", "start"]
  2. 애플리케이션 Dockerfile 생성

    클라이언트 애플리케이션용 Dockerfile을 생성합니다.

  3. Docker Compose 파일 생성

    두 컨테이너를 공유 네트워크 인터페이스로 실행하기 위한 Docker Compose 파일을 생성합니다.

    중요

    애플리케이션이 AWS 워크로드 AWS 자격 증명 공급자를 사용할 수 있으려면 자격 증명과 SSRF 토큰을 로드해야 합니다. Amazon EKS 및 Amazon ECS의 경우 다음 문서를 참조하세요.

    version: '3'
services:
    client-application:
    container_name: client-application
    build:
        context: .
        dockerfile: Dockerfile.client
    command: tail -f /dev/null  # Keep the container running
    

    workload-credentials-provider:
    container_name: workload-credentials-provider
    build:
        context: .
        dockerfile: Dockerfile.provider
    network_mode: "container:client-application"  # Attach to the client-application container's network
    depends_on:
        - client-application
  4. 공급자 바이너리 복사

    Dockerfiles 및 Docker Compose 파일이 포함된 동일한 디렉터리에 aws-workload-credentials-provider 바이너리를 복사합니다.

  5. 컨테이너 빌드 및 실행

    Docker Compose를 사용하여 컨테이너를 빌드하고 실행합니다.

    docker-compose up --build
  6. 다음 단계

    이제 AWS 워크로드 자격 증명 공급자를 사용하여 클라이언트 컨테이너에서 보안 암호를 검색할 수 있습니다. 자세한 내용은 AWS 워크로드 자격 증명 공급자를 사용하여 보안 암호 검색 단원을 참조하십시오.

Lambda

AWS 워크로드 자격 증명 공급자를 Lambda 확장으로 패키징할 수 있습니다. 그런 다음 Lambda 함수에 계층으로 추가하고 Lambda 함수에서 AWS 워크로드 자격 증명 공급자를 호출하여 암호를 가져올 수 있습니다.

다음 지침은 aws-workload-credentials-provider GitHub 리포지토리secrets-manager-provider-extension.sh의 예제 스크립트를 사용하여 AWS 워크로드 자격 증명 공급자를 Lambda 확장으로 설치하여 MyTest라는 보안 암호를 가져오는 방법을 보여줍니다.

AWS 워크로드 자격 증명 공급자에 대한 Lambda 확장을 생성하려면
  1. 공급자 계층 패키징

    AWS 워크로드 자격 증명 공급자 코드 패키지의 루트에서 다음 명령을 실행합니다.

    AWS_ACCOUNT_ID=AWS_ACCOUNT_ID
LAMBDA_ARN=LAMBDA_ARN

# Build the release binary 
cargo build --release --target=x86_64-unknown-linux-gnu

# Copy the release binary into the `bin` folder
mkdir -p ./bin
cp ./target/x86_64-unknown-linux-gnu/release/aws-workload-credentials-provider ./bin/aws-workload-credentials-provider

# Copy the `secrets-manager-provider-extension.sh` example script into the `extensions` folder.
mkdir -p ./extensions
cp aws_secretsmanager_provider/examples/example-lambda-extension/secrets-manager-provider-extension.sh ./extensions

# Zip the extension shell script and the binary 
zip secrets-manager-provider-extension.zip bin/* extensions/*

# Publish the layer version
LAYER_VERSION_ARN=$(aws lambda publish-layer-version \
    --layer-name secrets-manager-provider-extension \
    --zip-file "fileb://secrets-manager-provider-extension.zip" | jq -r '.LayerVersionArn')
  2. SSRF 토큰 구성

    공급자의 기본 구성은 SSRF 토큰을 사전 설정 AWS_SESSION_TOKEN 또는 AWS_CONTAINER_AUTHORIZATION_TOKEN 환경 변수(SnapStart가 활성화된 Lambda 함수의 후자 변수)에 설정된 값으로 자동으로 설정합니다. 또는 Lambda 함수에서 임의 값으로 AWS_TOKEN 환경 변수를 정의할 수 있으며, 이 경우 위 두 변수보다 우선 적용됩니다. AWS_TOKEN 환경 변수를 사용하기로 선택하면, 반드시 lambda:UpdateFunctionConfiguration 호출을 통해 해당 환경 변수를 설정해야 합니다.

  3. 계층을 함수에 연결

    계층을 Lambda 함수에 연결합니다.

    # Attach the layer version to the Lambda function
aws lambda update-function-configuration \
    --function-name $LAMBDA_ARN \
    --layers "$LAYER_VERSION_ARN"
  4. 함수 코드 업데이트

    Lambda 함수가 http://localhost:2773/secretsmanager/get?secretId=MyTest를 호출하도록 코드를 업데이트하고, 요청 헤더 X-Aws-codes-Secrets-Token에는 위에서 설정한 SSRF 토큰 값을 넣어 보안 암호를 가져옵니다. 애플리케이션 코드에 재시도 로직을 구현하여 Lambda 확장의 초기화 및 등록 지연을 수용할 수 있도록 해야 합니다.

  5. 함수 테스트

    Lambda 함수를 간접적으로 호출하여 보안 암호를 올바르게 가져오는지 확인합니다.

AWS 워크로드 자격 증명 공급자를 사용하여 보안 암호 검색

보안 암호를 검색하려면 보안 암호 이름 또는 ARN을 쿼리 파라미터로 사용하여 로컬 AWS 워크로드 자격 증명 공급자 엔드포인트를 호출합니다. 기본적으로 AWS 워크로드 자격 증명 공급자는 보안 암호의 AWSCURRENT 버전을 검색합니다. 다른 버전을 가져오려면 versionStage 또는 versionId 파라미터를 사용합니다.

중요

AWS 워크로드 자격 증명 공급자를 보호하려면 각 요청의 일부로 SSRF 토큰 헤더를 포함해야 합니다X-Aws-Parameters-Secrets-Token. AWS 워크로드 자격 증명 공급자는이 헤더가 없거나 잘못된 SSRF 토큰이 있는 요청을 거부합니다. AWS 워크로드 자격 증명 공급자 구성에 있는 SSRF 헤더 이름을 사용자 지정할 수 있습니다.

필수 권한

AWS 워크로드 자격 증명 공급자는 AWS 자격 증명 공급자 체인을 사용하는 AWS SDK for Rust를 사용합니다. 이러한 IAM 자격 증명의 자격 증명은 AWS 워크로드 자격 증명 공급자가 보안 암호를 검색하는 데 필요한 권한을 결정합니다.

  • secretsmanager:DescribeSecret

  • secretsmanager:GetSecretValue

권한에 대한 자세한 내용은 에 대한 권한 참조 AWS Secrets Manager 섹션을 참조하세요.

중요

보안 암호 값을 AWS 워크로드 자격 증명 공급자로 가져오면 컴퓨팅 환경 및 SSRF 토큰에 액세스할 수 있는 모든 사용자가 AWS 워크로드 자격 증명 공급자 캐시에서 보안 암호에 액세스할 수 있습니다. 자세한 내용은 보안 고려 사항 단원을 참조하십시오.

요청 예시

curl
예예 - curl을 사용하여 보안 암호 가져오기

다음 curl 예제에서는 AWS 워크로드 자격 증명 공급자로부터 보안 암호를 가져오는 방법을 보여줍니다. 이 예제는 파일에 있는 SSRF를 기반으로 하며, SSRF는 설치 스크립트에 저장됩니다.

curl -v -H \
    "X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \
    'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID'
Python
예예 - Python을 사용하여 보안 암호 가져오기

다음 Python 예제에서는 AWS 워크로드 자격 증명 공급자로부터 보안 암호를 가져오는 방법을 보여줍니다. 이 예제는 파일에 있는 SSRF를 기반으로 하며, SSRF는 설치 스크립트에 저장됩니다.

import requests
import json

# Function that fetches the secret from AWS Workload Credentials Provider for the provided secret id. 
def get_secret():
    # Construct the URL for the GET request
    url = f"http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID"

    # Get the SSRF token from the token file
    with open('/var/run/awssmatoken') as fp:
        token = fp.read() 

    headers = {
        "X-Aws-Parameters-Secrets-Token": token.strip()
    }

    try:
        # Send the GET request with headers
        response = requests.get(url, headers=headers)

        # Check if the request was successful
        if response.status_code == 200:
            # Return the secret value
            return response.text
        else:
            # Handle error cases
            raise Exception(f"Status code {response.status_code} - {response.text}")

    except Exception as e:
        # Handle network errors
        raise Exception(f"Error: {e}")

refreshNow 파라미터 이해

AWS 워크로드 자격 증명 공급자는 인 메모리 캐시를 사용하여 보안 암호 값을 저장하며, 보안 암호 값은 주기적으로 새로 고쳐집니다. 기본적으로 이 갱신은 TTL(Time to Live)이 만료된 후 보안 암호를 요청할 때 발생하며, TTL은 보통 300초입니다. 하지만 이 방식은 보안 암호가 캐시 만료 전에 교체되면 오래된 보안 암호 값을 반환할 수 있다는 한계가 있습니다.

이 제한을 해결하기 위해 AWS 워크로드 자격 증명 공급자는 URLrefreshNow에서 라는 파라미터를 지원합니다. 이 파라미터를 사용하면 캐시를 무시하고 즉시 보안 암호 값을 갱신하여 항상 최신 정보를 가져올 수 있습니다.

기본 동작(refreshNow 미사용)

  • TTL이 만료될 때까지 캐시된 값을 사용

  • TTL(기본 300초) 이후에만 보안 암호 갱신

  • TTL 만료 전에 보안 암호가 교체되면 오래된 값을 반환할 수 있음

refreshNow=true 사용 시 동작

  • 캐시를 완전히 우회

  • Secrets Manager에서 최신 보안 암호 값을 직접 가져옴

  • 캐시를 최신 값으로 업데이트하고 TTL 재설정

  • 항상 가장 최신 보안 암호 값을 확보

보안 암호 값 강제 갱신

중요

refreshNow의 기본값은 false입니다. 로 설정하면 AWS 워크로드 자격 증명 공급자 구성 파일에 지정된 TTL을 true재정의하고 Secrets Manager에 API를 호출합니다.

curl
예예 - curl을 사용하여 보안 암호 강제 갱신

다음 curl 예제에서는 AWS 워크로드 자격 증명 공급자가 보안 암호를 새로 고치도록 하는 방법을 보여줍니다. 이 예제는 파일에 있는 SSRF를 기반으로 하며, SSRF는 설치 스크립트에 저장됩니다.

curl -v -H \
"X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \
'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID&refreshNow=true'
Python
예예 - Python을 사용하여 보안 암호 강제 갱신

다음 Python 예제에서는 AWS 워크로드 자격 증명 공급자로부터 보안 암호를 가져오는 방법을 보여줍니다. 이 예제는 파일에 있는 SSRF를 기반으로 하며, SSRF는 설치 스크립트에 저장됩니다.

import requests
import json

# Function that fetches the secret from AWS Workload Credentials Provider for the provided secret id. 
def get_secret():
    # Construct the URL for the GET request
    url = f"http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID&refreshNow=true"

    # Get the SSRF token from the token file
    with open('/var/run/awssmatoken') as fp:
        token = fp.read() 

    headers = {
        "X-Aws-Parameters-Secrets-Token": token.strip()
    }

    try:
        # Send the GET request with headers
        response = requests.get(url, headers=headers)

        # Check if the request was successful
        if response.status_code == 200:
            # Return the secret value
            return response.text
        else:
            # Handle error cases
            raise Exception(f"Status code {response.status_code} - {response.text}")

    except Exception as e:
        # Handle network errors
        raise Exception(f"Error: {e}")

역할 체인을 사용하여 계정 간 보안 암호 검색

역할 체인을 사용하면 AWS 워크로드 자격 증명 공급자가를 사용하여 IAM 역할을 수임하여 다른 AWS 계정에서 보안 암호를 검색할 수 있습니다 AWS STS AssumeRole. AWS 워크로드 자격 증명 공급자는 각 고유한 역할 ARN에 대해 별도의 캐싱 클라이언트를 생성하고 캐싱합니다. 각 역할 클라이언트는 자체 독립 캐시를 유지하므로 서로 다른 역할로 가져온 동일한 보안 암호에 별도의 캐시 항목이 있습니다.

필수 권한

역할 체인을 사용하려면 다음이 필요합니다.

  • AWS 워크로드 자격 증명 공급자의 환경 자격 증명에는 대상 역할 ARN에 대한 sts:AssumeRole 권한이 있어야 합니다.

  • 대상 역할에는 액세스하려는 보안 암호에 대한 secretsmanager:GetSecretValue 및 secretsmanager:DescribeSecret 권한이 있어야 합니다.

  • 대상 역할의 신뢰 정책은 AWS 워크로드 자격 증명 공급자의 자격 증명이 이를 수임하도록 허용해야 합니다.

교차 계정 보안 암호 검색

AWS 워크로드 자격 증명 공급자에 대한 요청에 roleArn 쿼리 파라미터를 포함하여 보안 암호 검색을 위해 맡을 역할을 지정합니다.

curl
예예 - curl을 사용한 교차 계정 보안 암호
curl -v -H \
    "X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \
    'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID&roleArn=arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME'
Python
예예 - Python을 사용한 교차 계정 보안 암호
import requests

def get_secret_cross_account():
    secret_id = "YOUR_SECRET_ID"
    role_arn = "arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME"
    url = f"http://localhost:2773/secretsmanager/get?secretId={secret_id}&roleArn={role_arn}"

    with open('/var/run/awssmatoken') as fp:
        token = fp.read()

    headers = {
        "X-Aws-Parameters-Secrets-Token": token.strip()
    }

    try:
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.text
        else:
            raise Exception(f"Status code {response.status_code} - {response.text}")

    except Exception as e:
        raise Exception(f"Error: {e}")

역할 체인 구성 및 제한

TOML 구성 파일의 max_roles 옵션을 사용하여 역할 체인을 구성합니다. 이렇게 하면 1~20 범위의 동시 수임된 역할의 최대 수가 설정됩니다. 기본값은 20입니다.

중요

가정된 역할은 AWS 워크로드 자격 증명 공급자의 역할 캐시에서 제거되지 않습니다. 최대 역할 수에 도달하면 AWS 워크로드 자격 증명 공급자가 다시 시작될 때까지 새 역할 ARNs이 있는 요청이 400 오류와 함께 거부됩니다.

역할 체인에 대한 오류 응답
400

roleArn 형식이 잘못되었거나 수임된 역할의 최대 수에 도달했습니다.

403

AWS STS AssumeRole 호출 실패. 대상 역할의 신뢰 정책이 AWS 워크로드 자격 증명 공급자의 자격 증명이 이를 수임하도록 허용하는지 확인합니다.

시작 시 보안 암호 미리 가져오기

기본적으로 AWS 워크로드 자격 증명 공급자는 애플리케이션이 보안 암호를 요청할 때 온디맨드로 보안 암호를 가져옵니다. 미리 가져오기를 사용하면 AWS 워크로드 자격 증명 공급자가 시작 시 지정된 보안 암호를 캐시에 로드하므로 애플리케이션이 첫 번째 API 호출을 기다리지 않고 즉시 액세스할 수 있습니다. 사전 가져오기는 백그라운드 작업으로 실행됩니다. AWS 워크로드 자격 증명 공급자는 요청을 즉시 수락하기 시작하고 사전 가져오기 완료 시 차단되지 않습니다.

두 가지 방법으로 미리 가져올 보안 암호를 지정할 수 있습니다.

  • 명시적 보안 암호 - 특정 보안 암호 IDs 또는 ARNs.

  • 태그 기반 검색 - 태그 키로 보안 암호를 검색합니다. AWS 워크로드 자격 증명 공급자는 지정된 태그가 있는 모든 보안 암호를 가져옵니다.

필수 권한

보안 암호를 검색하기 위한 표준 권한 외에도 미리 가져오기에는 다음이 필요합니다.

  • secretsmanager:BatchGetSecretValue - 모든 미리 가져오기 작업에 필요합니다.

  • secretsmanager:ListSecrets - 태그 기반 검색을 사용하는 경우에만 필요합니다.

미리 가져오기 구성

TOML 구성 파일에 [capabilities.secrets_manager.prefetch] 섹션을 추가합니다. 다음 옵션을 사용할 수 있습니다.

cache_buffer_ratio

미리 가져오는 동안 클라이언트당 채울 캐시의 최대 비율이며 범위는 0.1~1.0입니다. 기본값은 0.8입니다. 버퍼 한도에 도달하면 AWS 워크로드 자격 증명 공급자는 기존 캐시 항목을 제거하지 않고 나머지 보안 암호의 사전 가져오기를 중지합니다. 사전 가져오기 중에 로드되지 않은 보안 암호는 온디맨드로 계속 사용할 수 있습니다.

max_jitter_seconds

0~10 범위의 사전 가져오기가 시작되기 전 초 단위의 임의 지연입니다. 기본값은 0입니다. 여러 공급자가 동시에 시작할 때 동기화된 플릿 전체 API 호출을 방지하려면이 옵션을 사용합니다.

예명시적 보안 암호로 구성 미리 가져오기
[capabilities.secrets_manager.prefetch]
cache_buffer_ratio = 0.6
max_jitter_seconds = 5
secrets = [
    { secret_id = "arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-AbCdEf" },
    { secret_id = "MyOtherSecret" },
]
예태그 기반 검색을 사용하여 구성 미리 가져오기
[capabilities.secrets_manager.prefetch]
cache_buffer_ratio = 0.8
filter_tags = [
    { key = "Environment" },
    { key = "Team" },
]

동일한 구성에서 명시적 보안 암호와 태그 기반 검색을 결합할 수도 있습니다. 교차 계정 사전 가져오기의 경우 role_arn 필드를 추가합니다. 자세한 내용은 역할 체인을 사용하여 계정 간 보안 암호 검색 단원을 참조하십시오.

예교차 계정 액세스를 사용한 사전 가져오기 구성
[capabilities.secrets_manager.prefetch]
cache_buffer_ratio = 0.6
max_jitter_seconds = 5
secrets = [
    { secret_id = "arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-AbCdEf" },
    { secret_id = "cross-account-secret", role_arn = "arn:aws:iam::987654321098:role/SecretAccessRole" },
]
filter_tags = [
    { key = "Environment" },
    { key = "Team", role_arn = "arn:aws:iam::987654321098:role/SecretAccessRole" },
]

AWS 워크로드 자격 증명 공급자 구성

AWS 워크로드 자격 증명 공급자의 구성을 변경하려면 TOML 구성 파일을 생성한 다음를 호출합니다./aws-workload-credentials-provider sm start --config config.toml.

구성 파일은 중첩 형식을 지원합니다. Secrets Manager 옵션은 캐시 및 보안 설정에 대한 하위 섹션과 [capabilities.secrets_manager]함께 아래에 배치됩니다. 로깅 옵션은 아래에 배치됩니다[logging].

예중첩된 구성 파일의 예
[logging]
log_level = "INFO"
log_to_file = true

[capabilities.secrets_manager]
enabled = true
http_port = 2773
region = "us-east-1"
path_prefix = "/v1/"
max_conn = 800
max_roles = 20

[capabilities.secrets_manager.cache]
ttl_seconds = 300
cache_size = 1000

[capabilities.secrets_manager.security]
ssrf_headers = ["X-Aws-Parameters-Secrets-Token", "X-Vault-Token"]
ssrf_env_variables = ["AWS_TOKEN", "AWS_SESSION_TOKEN", "AWS_CONTAINER_AUTHORIZATION_TOKEN"]
참고

루트 수준의 플랫 키(예: http_port = 2773)는 기존 구성 파일과의 이전 버전과의 호환성을 위해 계속 지원됩니다.

Secrets Manager 구성 옵션
enabled

Secrets Manager 기능이 활성 상태인지 여부: true 또는 false. 기본값은 true입니다.

http_port

로컬 HTTP 서버의 포트로, 포트 범위는 1024~65535입니다. 기본값은 2773입니다.

region

요청에 사용할 AWS 리전입니다. 리전을 지정하지 않으면 AWS 워크로드 자격 증명 공급자가 SDK에서 리전을 결정합니다. 자세한 내용은 AWS SDK for Rust 개발자 가이드의 Specify your credentials and default Region 섹션을 참조하세요.

path_prefix

요청이 경로 기반 요청인지 여부를 결정하는 데 사용되는 URI 접두사입니다. 기본값은 ‘/v1/’입니다.

max_conn

AWS 워크로드 자격 증명 공급자가 허용하는 HTTP 클라이언트의 최대 연결 수로, 범위는 1~1000입니다. 기본값은 800입니다.

max_roles

1~20 범위의 교차 계정 액세스를 위한 최대 동시 IAM 역할 수입니다. 기본값은 20입니다. 자세한 내용은 역할 체인을 사용하여 계정 간 보안 암호 검색 단원을 참조하십시오.

캐시 옵션([capabilities.secrets_manager.cache])
ttl_seconds

캐시된 항목의 TTL(초 단위)로, 범위는 0~3600입니다. 기본값은 300입니다. 0은 캐싱이 없음을 나타냅니다.

cache_size

캐시에 저장할 수 있는 보안 암호의 최대 개수로, 범위는 1~1000입니다. 기본값은 1000입니다.

보안 옵션([capabilities.secrets_manager.security])
ssrf_headers

AWS 워크로드 자격 증명 공급자가 SSRF 토큰을 확인하는 헤더 이름 목록입니다. 기본값은 ‘X-Aws-Parameters-Secrets-Token, X-Vault-Token’입니다.

ssrf_env_variables

AWS 워크로드 자격 증명 공급자가 SSRF 토큰에 대해 순차적으로 확인하는 환경 변수 이름 목록입니다. 환경 변수에는 토큰 또는 AWS_TOKEN=file:///var/run/awssmatoken에서와 같이 토큰 파일에 대한 참조가 포함될 수 있습니다. 기본값은 "AWS_TOKEN, AWS_SESSION_TOKEN, AWS_CONTAINER_AUTHORIZATION_TOKEN"입니다.

로깅 옵션([logging])
log_level

AWS 워크로드 자격 증명 공급자의 로그에 보고된 세부 정보 수준: DEBUG, INFO, WARN, ERROR 또는 NONE. 기본값은 INFO입니다.

log_to_file

로그를 파일 또는 stdout/stderr로 출력할지 여부(true 또는 false)를 설정합니다. 기본값은 true입니다.

선택적 기능

AWS 워크로드 자격 증명 공급자는 --features 플래그를에 전달하여 선택적 기능을 사용하여 빌드할 수 있습니다cargo build. 사용 가능한 기능은 다음과 같습니다.

빌드 기능
prefer-post-quantum

X25519MLKEM768 알고리즘을 가장 우선 순위의 키 교환 알고리즘으로 설정합니다. 기본적으로는 사용 가능하지만 최우선으로 설정되지는 않습니다. X25519MLKEM768은 하이브리드, 포스트 양자 보안 키 교환 알고리즘입니다.

fips

공급자가 사용하는 암호 그룹을 FIPS 승인 암호로만 제한합니다.

로깅

로컬 로깅

AWS 워크로드 자격 증명 공급자는 log_to_file 구성 변수에 따라 로컬로 파일 logs/secrets_manager_provider.log 또는 stdout/stderr에 오류를 기록합니다. 애플리케이션이 AWS 워크로드 자격 증명 공급자를 호출하여 보안 암호를 가져오면 해당 호출이 로컬 로그에 표시됩니다. CloudTrail 로그에는 표시되지 않습니다.

로그 교체

AWS 워크로드 자격 증명 공급자는 파일이 10MB에 도달하면 새 로그 파일을 생성하고 총 5개의 로그 파일을 저장합니다.

AWS 서비스 로깅

로그는 Secrets Manager, CloudTrail 또는 CloudWatch로 이동하지 않습니다. AWS 워크로드 자격 증명 공급자의 보안 암호 가져오기 요청은 해당 로그에 표시되지 않습니다. AWS 워크로드 자격 증명 공급자가 Secrets Manager를 호출하여 보안 암호를 가져오면 해당 호출은가 포함된 사용자 에이전트 문자열과 함께 CloudTrail에 기록됩니다aws-workload-credentials-provider.

AWS 워크로드 자격 증명 공급자 구성에서 로깅 옵션을 구성할 수 있습니다.

보안 고려 사항

신뢰 도메인

로컬 공급자 아키텍처의 경우 신뢰 도메인은 일반적으로 전체 호스트인 공급자 엔드포인트 및 SSRF 토큰에 액세스할 수 있는 곳입니다. AWS 워크로드 자격 증명 공급자에 대한 신뢰 도메인은 동일한 보안 태세를 유지하기 위해 Secrets Manager 자격 증명을 사용할 수 있는 도메인과 일치해야 합니다. 예를 들어 Amazon EC2에서 AWS 워크로드 자격 증명 공급자에 대한 신뢰 도메인은 Amazon EC2에 대한 역할을 사용할 때 자격 증명의 도메인과 동일합니다.

중요

Secrets Manager 자격 증명이 애플리케이션에 고정된 공급자 기반 솔루션을 아직 사용하지 않는 보안 인식 애플리케이션은 언어별 AWS SDKs 또는 캐싱 솔루션 사용을 고려해야 합니다. 자세한 내용은 보안 암호 가져오기를 참조하세요.