翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# 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
+ アマゾン エラスティックKubernetesサービス
+ Amazon Elastic Compute Cloud

AWSワークロード認証情報プロバイダーはシークレットを取得してメモリにキャッシュするため、アプリケーションは Secrets Manager を直接呼び出す代わりに localhost からシークレットを取得できます。AWSワークロード認証情報プロバイダーはシークレットのみを読み取ることができ、変更することはできません。

AWSワークロード認証情報プロバイダーはオープンソースです。ソースコード、インストール手順、最新のリリース情報は、[GitHub](https://github.com/aws/aws-workload-credentials-provider) で入手できます。

**重要**  
AWSワークロード認証情報プロバイダーは、環境のAWS認証情報を使用して Secrets Manager を呼び出します。これには、シークレットセキュリティの向上に役立つ Server Side Request Forgery (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 for 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. 

**プロバイダーバイナリをコピーする**  
`aws-workload-credentials-provider` バイナリを Dockerfiles および Docker Compose ファイルと同じディレクトリにコピーします。

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` 環境変数を定義することもできます。これは、この変数が他の 2 つよりも優先されるためです。`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. 

**関数コードの更新**  
`X-Aws-codes-Secrets-Token` ヘッダー値を上記の環境変数から取得した SSRF トークンの値に設定して `http://localhost:2773/secretsmanager/get?secretId=MyTest` のクエリを実行するように Lambda 関数を更新し、シークレットを取得します。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 認証情報の ID によって、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 がインストールスクリプトによって保存されるファイルに存在するかどうかに依存します。  

```
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 がインストールスクリプトによって保存されるファイルに存在するかどうかに依存します。  

```
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) が切れた後、通常 300 秒ごとにシークレットをリクエストしたときに発生します。ただし、このアプローチでは、特にキャッシュエントリの有効期限が切れる前にシークレットがローテーションした場合、シークレット値が古くなることがあります。

この制限に対応するため、AWSワークロード認証情報プロバイダーは URL `refreshNow`で というパラメータをサポートしています。このパラメータを使用して、シークレットの値の即時更新を強制し、キャッシュをバイパスして最新の情報を取得できます。

**デフォルトの動作 (`refreshNow` なし)**  
+ TTL の有効期限が切れるまでキャッシュされた値を使用します
+ TTL の後にのみシークレットを更新します (デフォルトは 300 秒)
+ キャッシュの有効期限が切れる前にシークレットがローテーションすると、古い値を返す可能性があります

**`refreshNow=true` での動作**  
+ キャッシュを完全にバイパスします
+ Secrets Manager から直接、最新のシークレット値を取得します
+ キャッシュを新しい値で更新し、TTL をリセットします
+ 常に最新のシークレット値を取得するようにします

### シークレット値を強制更新する
<a name="refreshnow-examples"></a>

**重要**  
`refreshNow` の初期値は `false` です。に設定すると`true`、AWSワークロード認証情報プロバイダー設定ファイルで指定された TTL が上書きされ、Secrets Manager に API コールが実行されます。

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

**Example 例 – curl を使用してシークレットを強制更新する**  
次の curl の例は、AWSワークロード認証情報プロバイダーにシークレットの更新を強制する方法を示しています。この例では、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 がインストールスクリプトによって保存されるファイルに存在するかどうかに依存します。  

```
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ワークロード認証情報プロバイダーの ID がそれを引き受けることを許可する必要があります。

### クロスアカウントシークレットを取得する
<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、ワークロード認証情報プロバイダーの ID がそれを引き受けることが許可されていることを確認します。

## 起動時のシークレットのプリフェッチ
<a name="workload-credentials-provider-prefetch"></a>

デフォルトでは、AWSワークロード認証情報プロバイダーは、アプリケーションがシークレットをリクエストしたときに、オンデマンドでシークレットを取得します。プリフェッチでは、AWSワークロード認証情報プロバイダーは起動時に指定されたシークレットをキャッシュにロードするため、アプリケーションは最初の API コールを待たずにすぐにアクセスできます。プリフェッチはバックグラウンドタスクとして実行されます。AWSワークロード認証情報プロバイダーはリクエストの受け入れをすぐに開始し、プリフェッチの完了時にブロックしません。

シークレットを指定すると、次の 2 つの方法でプリフェッチできます。
+ **明示的なシークレット** – 特定のシークレット 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 Developer Guide*」の「[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`**  
クロスアカウントアクセスの同時 IAM ロールの最大数。範囲は 1～20 です。デフォルトは 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ワークロード認証情報プロバイダーは、設定変数に応じて、エラーをローカルで ファイル`logs/secrets_manager_provider.log`または stdout/stderr `log_to_file` に記録します。アプリケーションがAWSワークロード認証情報プロバイダーを呼び出してシークレットを取得すると、それらの呼び出しはローカルログに表示されます。CloudTrail ログには表示されません。

**ログローテーション**  
AWSワークロード認証情報プロバイダーは、ファイルが 10 MB に達すると新しいログファイルを作成し、合計で最大 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)」を参照してください。