View a markdown version of this page

AWS워크로드 자격 증명 공급자 사용 - AWS Secrets Manager
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워크로드 자격 증명 공급자 빌드

시작하기 전에 플랫폼에 맞는 표준 개발 도구 및 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에AWS워크로드 자격 증명 공급자를 설치하려면
  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 STSAssumeRole.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 STSAssumeRole 호출 실패. 대상 역할의 신뢰 정책이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 또는 캐싱 솔루션 사용을 고려해야 합니다. 자세한 내용은 보안 암호 가져오기를 참조하세요.