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

# AWS워크로드 자격 증명 공급자 사용
<a name="workload-credentials-provider"></a>

## AWS워크로드 자격 증명 공급자의 작동 방식
<a name="provider-overview"></a>

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](https://github.com/aws/aws-workload-credentials-provider)에서 확인할 수 있습니다.

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

## AWS워크로드 자격 증명 공급자 캐싱 이해
<a name="provider-caching"></a>

AWS워크로드 자격 증명 공급자는AWS워크로드 자격 증명 공급자가 다시 시작될 때 재설정되는 인 메모리 캐시를 사용합니다. 캐시된 보안 암호 값은 다음 기준으로 주기적으로 갱신됩니다.
+ 기본 갱신 주기(TTL)는 300초
+ 구성 파일을 통해 TTL을 수정할 수 있음
+ TTL이 만료된 후 보안 암호를 요청하면 갱신이 발생

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

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

**Topics**
+ [AWS워크로드 자격 증명 공급자의 작동 방식](#provider-overview)
+ [AWS워크로드 자격 증명 공급자 캐싱 이해](#provider-caching)
+ [AWS워크로드 자격 증명 공급자 빌드](#workload-credentials-provider-build)
+ [AWS워크로드 자격 증명 공급자 설치](#workload-credentials-provider-install)
+ [AWS워크로드 자격 증명 공급자를 사용하여 보안 암호 검색](#workload-credentials-provider-call)
+ [`refreshNow` 파라미터 이해](#workload-credentials-provider-refresh)
+ [역할 체인을 사용하여 계정 간 보안 암호 검색](#workload-credentials-provider-role-chaining)
+ [시작 시 보안 암호 미리 가져오기](#workload-credentials-provider-prefetch)
+ [AWS워크로드 자격 증명 공급자 구성](#workload-credentials-provider-config)
+ [선택적 기능](#workload-credentials-provider-features)
+ [로깅](#workload-credentials-provider-log)
+ [보안 고려 사항](#workload-credentials-provider-security)

## AWS워크로드 자격 증명 공급자 빌드
<a name="workload-credentials-provider-build"></a>

시작하기 전에 플랫폼에 맞는 표준 개발 도구 및 Rust 도구가 설치되어 있는지 확인합니다.

**참고**  
macOS에서 활성화된 `fips` 기능을 사용하여 공급자를 빌드하려면 현재 다음 해결 방법이 필요합니다.  
`xcrun --show-sdk-path` 실행의 결과로 설정된 `SDKROOT`라는 환경 변수를 생성합니다.

------
#### [ RPM-based systems ]

**RPM 기반 시스템에서 빌드하는 방법**

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

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

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

   ```
   sudo usermod -aG aws-wcp-token {{<APP_USER>}}
   ```

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

   ```
   sudo yum -y groupinstall "Development Tools"
   ```

1. 

**Rust 설치**  
*Rust 설명서*의 [Rust 설치](https://www.rust-lang.org/tools/install) 지침에 따라 설치합니다.

   ```
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
   . "$HOME/.cargo/env"
   ```

1. 

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

   ```
   cargo build --release
   ```

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

------
#### [ Debian-based systems ]

**Debian 기반 시스템에서 빌드하는 방법**

1. 

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

   ```
   sudo apt install build-essential
   ```

1. 

**Rust 설치**  
*Rust 설명서*의 [Rust 설치](https://www.rust-lang.org/tools/install) 지침에 따라 설치합니다.

   ```
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
   . "$HOME/.cargo/env"
   ```

1. 

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

   ```
   cargo build --release
   ```

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

------
#### [ Windows ]

**Windows에서 빌드하는 방법**

1. 

**개발 환경 설정**  
*Microsoft Windows 설명서*의 [Windows용 Rust 개발 환경 설정](https://learn.microsoft.com/en-us/windows/dev-environment/rust/setup) 지침에 따라 개발 환경을 설정합니다.

1. 

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

   ```
   cargo build --release
   ```

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

------
#### [ Cross-compile natively ]

**기본적으로 교차 컴파일하는 방법**

1. 

**교차 컴파일 도구 설치**  
`cargo-xwin`을 설치합니다.

   ```
   cargo install cargo-xwin
   ```

1. 

**Rust 빌드 대상 추가**  
Windows MSVC 빌드 대상을 설치합니다.

   ```
   rustup target add x86_64-pc-windows-msvc
   ```

1. 

**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워크로드 자격 증명 공급자 설치
<a name="workload-credentials-provider-install"></a>

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

------
#### [ Amazon EC2 ]

**Amazon EC2에AWS워크로드 자격 증명 공급자를 설치하려면**

1. 

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

   ```
   cd aws_workload_credentials_provider_common/configuration
   ```

1. 

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

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

1. 

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

   ```
   sudo usermod -aG aws-wcp-token {{APP_USER}}
   ```

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

------
#### [ Container Sidecar ]

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

**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"]
   ```

1. 

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

1. 

**Docker Compose 파일 생성**  
두 컨테이너를 공유 네트워크 인터페이스로 실행하기 위한 Docker Compose 파일을 생성합니다.
**중요**  
애플리케이션이AWS워크로드AWS자격 증명 공급자를 사용하려면 자격 증명과 SSRF 토큰을 로드해야 합니다. Amazon EKS 및 Amazon ECS의 경우 다음 문서를 참조하세요.  
*Amazon EKS 사용 설명서*의 [액세스 관리](https://docs.aws.amazon.com/eks/latest/userguide/cluster-auth.html)
*Amazon ECS 개발자 가이드*의 [Amazon ECS 작업 IAM 역할](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)

   ```
   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
   ```

1. 

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

1. 

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

   ```
   docker-compose up --build
   ```

1. 

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

------
#### [ Lambda ]

[AWS워크로드 자격 증명 공급자를 Lambda 확장으로 패키징할 수 있습니다](https://docs.aws.amazon.com/lambda/latest/dg/packaging-layers.html). 그런 다음 [Lambda 함수에 계층으로 추가](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html)하고 Lambda 함수에서AWS워크로드 자격 증명 공급자를 호출하여 암호를 가져올 수 있습니다.

다음 지침은 [aws-workload-credentials-provider](https://github.com/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')
   ```

1. 

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

1. 

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

   ```
   # Attach the layer version to the Lambda function
   aws lambda update-function-configuration \
       --function-name $LAMBDA_ARN \
       --layers "$LAYER_VERSION_ARN"
   ```

1. 

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

1. 

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

------

## AWS워크로드 자격 증명 공급자를 사용하여 보안 암호 검색
<a name="workload-credentials-provider-call"></a>

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

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

### 필수 권한
<a name="provider-call-permissions"></a>

AWS워크로드 자격 증명 공급자는 [AWS자격 증명 공급자 체인](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html)을 사용하는AWS SDK for Rust를 사용합니다. 이러한 IAM 자격 증명의 자격 증명은AWS워크로드 자격 증명 공급자가 보안 암호를 검색하는 데 필요한 권한을 결정합니다.
+ `secretsmanager:DescribeSecret`
+ `secretsmanager:GetSecretValue`

권한에 대한 자세한 내용은 [에 대한 권한 참조 AWS Secrets Manager](auth-and-access.md#reference_iam-permissions) 섹션을 참조하세요.

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

### 요청 예시
<a name="provider-call-examples"></a>

------
#### [ curl ]

**Example 예 - 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 ]

**Example 예 - 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` 파라미터 이해
<a name="workload-credentials-provider-refresh"></a>

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

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

**기본 동작(`refreshNow` 미사용)**  
+ TTL이 만료될 때까지 캐시된 값을 사용
+ TTL(기본 300초) 이후에만 보안 암호 갱신
+ TTL 만료 전에 보안 암호가 교체되면 오래된 값을 반환할 수 있음

**`refreshNow=true` 사용 시 동작**  
+ 캐시를 완전히 우회
+ Secrets Manager에서 최신 보안 암호 값을 직접 가져옴
+ 캐시를 최신 값으로 업데이트하고 TTL 재설정
+ 항상 가장 최신 보안 암호 값을 확보

### 보안 암호 값 강제 갱신
<a name="refreshnow-examples"></a>

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

------
#### [ curl ]

**Example 예 - 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 ]

**Example 예 - 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}")
```

------

## 역할 체인을 사용하여 계정 간 보안 암호 검색
<a name="workload-credentials-provider-role-chaining"></a>

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

### 필수 권한
<a name="provider-role-chaining-permissions"></a>

역할 체인을 사용하려면 다음이 필요합니다.
+ AWS워크로드 자격 증명 공급자의 환경 자격 증명에는 대상 역할 ARN에 대한 `sts:AssumeRole` 권한이 있어야 합니다.
+ 대상 역할에는 액세스하려는 보안 암호에 대한 `secretsmanager:GetSecretValue` 및 `secretsmanager:DescribeSecret` 권한이 있어야 합니다.
+ 대상 역할의 신뢰 정책은AWS워크로드 자격 증명 공급자의 자격 증명이 이를 수임하도록 허용해야 합니다.

### 교차 계정 보안 암호 검색
<a name="provider-role-chaining-usage"></a>

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

------
#### [ curl ]

**Example 예 - 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 ]

**Example 예 - 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}")
```

------

### 역할 체인 구성 및 제한
<a name="provider-role-chaining-config"></a>

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

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

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

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

## 시작 시 보안 암호 미리 가져오기
<a name="workload-credentials-provider-prefetch"></a>

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

두 가지 방법으로 미리 가져올 보안 암호를 지정할 수 있습니다.
+ **명시적 보안 암호** - 특정 보안 암호 IDs 또는 ARNs.
+ **태그 기반 검색 -** 태그 키로 보안 암호를 검색합니다.AWS워크로드 자격 증명 공급자는 지정된 태그가 있는 모든 보안 암호를 가져옵니다.

### 필수 권한
<a name="provider-prefetch-permissions"></a>

보안 암호를 검색하기 위한 표준 권한 외에도 사전 가져오기에는 다음이 필요합니다.
+ `secretsmanager:BatchGetSecretValue` - 모든 미리 가져오기 작업에 필요합니다.
+ `secretsmanager:ListSecrets` - 태그 기반 검색을 사용하는 경우에만 필요합니다.

### 미리 가져오기 구성
<a name="provider-prefetch-config"></a>

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

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

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

**Example 명시적 보안 암호로 구성 미리 가져오기**  

```
[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" },
]
```

**Example 태그 기반 검색을 사용하여 구성 미리 가져오기**  

```
[capabilities.secrets_manager.prefetch]
cache_buffer_ratio = 0.8
filter_tags = [
    { key = "Environment" },
    { key = "Team" },
]
```

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

**Example 교차 계정 액세스 권한이 있는 미리 가져오기 구성**  

```
[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워크로드 자격 증명 공급자 구성
<a name="workload-credentials-provider-config"></a>

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

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

**Example 중첩된 구성 파일의 예**  

```
[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](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html) 섹션을 참조하세요.

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

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

**`max_roles`**  
1\~20 범위의 교차 계정 액세스를 위한 최대 동시 IAM 역할 수입니다. 기본값은 20입니다. 자세한 내용은 [역할 체인을 사용하여 계정 간 보안 암호 검색](#workload-credentials-provider-role-chaining) 단원을 참조하십시오.캐시 옵션(`[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`입니다.

## 선택적 기능
<a name="workload-credentials-provider-features"></a>

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

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

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

## 로깅
<a name="workload-credentials-provider-log"></a>

**로컬 로깅**  
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워크로드 자격 증명 공급자 구성](#workload-credentials-provider-config)에서 로깅 옵션을 구성할 수 있습니다.

## 보안 고려 사항
<a name="workload-credentials-provider-security"></a>

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

**중요**  
Secrets Manager 자격 증명이 애플리케이션에 고정된 공급자 기반 솔루션을 아직 사용하지 않는 보안 인식 애플리케이션은 언어별AWS SDKs 또는 캐싱 솔루션 사용을 고려해야 합니다. 자세한 내용은 [보안 암호 가져오기](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html)를 참조하세요.