本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用AWS工作负载凭证提供程序
<a name="workload-credentials-provider"></a>

## 怎么样AWS工作负载凭证提供程序起作用
<a name="provider-overview"></a>

AWS工作负载凭证提供程序（前身为AWS Secrets Manager代理）提供客户端 HTTP 服务，可帮助您标准化在计算环境中使用 Secrets Manager 中的密钥的方式。您可以将以下服务与该密钥一起使用：
+ AWS Lambda
+ Amazon Elastic Container Service
+ Amazon Elastic Kubernetes Service
+ Amazon Elastic Compute Cloud

AWS工作负载凭证提供程序在内存中检索和缓存机密，允许您的应用程序从本地主机获取密钥，而不必直接调用 Secrets Manager。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)
+ [了解 refresh `Now 参数`](#workload-credentials-provider-refresh)
+ [使用角色链跨账户检索机密](#workload-credentials-provider-role-chaining)
+ [Pre-fetch 启动时的秘密](#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`功能的情况下构建提供程序需要以下解决方法：  
创建名为 `SDKROOT` 的环境变量，该变量设置为运行 `xcrun --show-sdk-path` 的结果

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

**在 RPM-based 系统基础上构建**

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-based 系统上，安装开发工具组：AL2023

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

**构建提供商**  
使用 cargo build 命令构建AWS工作负载凭证提供程序：

   ```
   cargo build --release
   ```

   您将在 `target/release/aws-workload-credentials-provider` 下找到可执行文件。

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

**在 Debian-based 系统基础上构建**

1. 

**安装开发工具**  
在诸如 Ubuntu 之类的 Debian-based 系统上，安装构建必备软件包：

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

**构建提供商**  
使用 cargo build 命令构建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. 

**构建提供商**  
使用 cargo build 命令构建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 构建**  
Cross-compile 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 ]

**要安装  AWS Amazon EC2 上的工作负载凭证提供商**

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工作负载凭证提供程序 sidecar 容器创建 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凭据和 SSRF 令牌，应用程序才能使用AWS工作负载凭证提供程序。对于 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` 二进制文件复制到包含您的 Dockerfile 和 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 GitHub 存储库`secrets-manager-provider-extension.sh`中的示例脚本获取名*MyTest*为的密钥，将工作负载凭证提供程序](https://github.com/aws/aws-workload-credentials-provider)安装为 Lambda 扩展。AWS

**为创建 Lambda 扩展AWS工作负载凭证提供程序**

1. 

**Package 提供者层**  
在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`环境变量（后一个变量适用于启用的 Lambda 函数）中设置的值。 SnapStart 或者，您可以改用自己的 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 函数以使用 `X-Aws-codes-Secrets-Token` 标头值（设置为来自上述环境变量之一的 SSRF 令牌值）查询 `http://localhost:2773/secretsmanager/get?secretId=MyTest`，从而检索密钥。务必在应用程序代码中实现重试逻辑，以适应 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适用于 Rust 的 SDK，它使用[AWS凭证提供程序链](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html)。这些 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，该文件是安装脚本存储示例的位置。  

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

------

## 了解 refresh `Now 参数`
<a name="workload-credentials-provider-refresh"></a>

AWS工作负载凭证提供程序使用内存中的缓存来存储机密值，并定期刷新这些值。默认情况下，当您在生存时间（TTL）到期后请求密钥时，就会发生此刷新，通常每 300 秒刷新一次。但是，这种方法有时会导致密钥值过时，特别是如果密钥在缓存条目过期之前轮换。

为了解决此限制，AWS工作负载凭证提供程序支持在 URL `refreshNow` 中调用的参数。您可以使用此参数强制立即刷新密钥的值，从而绕过缓存并确保您拥有最新的信息。

**默认行为（没有 `refreshNow`）**  
+ 在 TTL 过期之前使用缓存值
+ 仅在 TTL 之后刷新密钥（默认为 300 秒）
+ 如果密钥在缓存过期之前轮换，则可能会返回旧值

**使用 `refreshNow=true` 的行为**  
+ 完全绕过缓存
+ 直接从 Secrets Manager 中检索最新的密钥值
+ 使用新值更新缓存并重置 TTL
+ 确保您始终获得最新的密钥值

### Force-refresh 一个秘密的价值
<a name="refreshnow-examples"></a>

**重要**  
`refreshNow` 的默认值为 `false`。设置为时`true`，它将覆盖AWS工作负载凭证提供程序配置文件中指定的 TTL，并对 Secrets Manager 进行 API 调用。

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

**Example 示例 — 使用 curl Force-refresh 的秘密**  
以下 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 示例 — Force-refresh 使用 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工作负载凭证提供者能够使用AWS STS`AssumeRole`代替 IAM 角色从其他AWS账户检索机密。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 的 Cross-account 秘密**  

```
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 进行 Cross-account 秘密**  

```
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工作负载凭证提供程序的角色缓存中移出。达到最大角色数量后，具有新角色 ARN 的请求将被拒绝并`400`显示错误，直到AWS工作负载凭证提供程序重新启动。角色链接的错误响应

**`400`**  
`roleArn`格式无效或已达到担任角色的最大数量。

**`403`**  
AWS STS`AssumeRole` 调用失败。验证目标角色的信任策略是否允许AWS工作负载凭证提供者的身份代入该策略。

## Pre-fetch 启动时的秘密
<a name="workload-credentials-provider-prefetch"></a>

默认情况下，当您的应用程序请求密钥时，AWS工作负载凭证提供程序会按需获取密钥。通过预取，AWS工作负载凭证提供程序在启动时将指定的密钥加载到缓存中，因此您的应用程序无需等待第一个 API 调用即可立即访问它们。 Pre-fetching 作为后台任务运行 —AWS工作负载凭证提供程序立即开始接受请求，并且在预取完成时不会阻塞。

您可以通过两种方式指定要预取的机密：
+ **显式密钥**-列出特定的密钥 ID 或 ARN。
+ **Tag-based 发现**-通过标签密钥发现秘密。工作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 Pre-fetch 带有显式机密的配置**  

```
[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 Pre-fetch 使用基于标签的发现进行配置**  

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

您还可以在同一个配置中组合显式密钥和基于标签的发现。要进行跨账户预提取，请添加字段。`role_arn`有关更多信息，请参阅 [使用角色链跨账户检索机密](#workload-credentials-provider-role-chaining)。

**Example Pre-fetch 具有跨账户访问权限的配置**  

```
[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工作负载凭证提供程序将根据软件开发工具包确定区域。有关更多信息，请参阅《*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`**  
同时进行跨账户访问的 IAM 角色的最大数量，范围在 1 到 20 之间。默认值为 20。有关更多信息，请参阅 [使用角色链跨账户检索机密](#workload-credentials-provider-role-chaining)。缓存选项（`[capabil` ities.secrets\_manager.cache]）

**`ttl_seconds`**  
缓存项目的 TTL（以秒为单位），范围在 1 到 3600 之间。默认值为 300。0 表示没有缓存。

**`cache_size`**  
缓存中可以存储的最大密钥数，范围为 1 至 1000。默认值为 1000。安全选项（`[capabil` ities.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”。日志选项（`[记录]`）

**`log_level`**  
AWS工作负载凭证提供程序日志中报告的详细程度：调试、信息、警告、错误或无。默认值为 INFO。

**`log_to_file`**  
是登录文件还 stdout/stderr是：`true`或`false`。默认值为 `true`。

## 可选功能
<a name="workload-credentials-provider-features"></a>

通过将`--features`标志传递给，即可使用可选功能构建AWS工作负载凭证提供程序`cargo build`。可用功能如下：生成功能

**`prefer-post-quantum`**  
使 `X25519MLKEM768` 成为最高优先级的密钥交换算法。否则，该算法可用，但不是最高优先级。`X25519MLKEM768` 是一种混合的、后量子安全的密钥交换算法。

**`fips`**  
将提供者使用的密码套件仅限于密码。 FIPS-approved

## 日志记录
<a name="workload-credentials-provider-log"></a>

**本地日志记录**  
工作AWS负载凭证提供程序 stdout/stderr根据`log_to_file`配置变量将错误记录到本地文件`logs/secrets_manager_provider.log`或文件中。当您的应用程序调用AWS工作负载凭证提供程序以获取密钥时，这些调用会显示在本地日志中。它们不会出现在 CloudTrail 日志中。

**日志轮换**  
当文件达到 10 MB 时，AWS工作负载凭证提供程序会创建一个新的日志文件，它最多可存储五个日志文件。

**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 SDK 或缓存解决方案。有关更多信息，请参阅[获取密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html)。