本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 AWS Secrets Manager 代理程式
## Secrets Manager 代理程式的運作方式
AWS Secrets Manager 代理程式是一種用戶端 HTTP 服務，可協助您標準化在運算環境中從 Secrets Manager 取用秘密的方式。您可以搭配下列服務使用：
+ AWS Lambda
+ Amazon Elastic Container Service
+ Amazon Elastic Kubernetes Service
+ Amazon Elastic Compute Cloud
Secrets Manager 代理程式會擷取和快取記憶體中的秘密，讓您的應用程式從 localhost 取得秘密，而不是直接呼叫 Secrets Manager。Secrets Manager Agent 只能讀取秘密，無法修改秘密。
**重要**
Secrets Manager 代理程式會使用您環境中的 AWS 登入資料來呼叫 Secrets Manager。它包含對伺服器端請求偽造 (SSRF) 的保護，以協助改善秘密安全性。Secrets Manager 代理程式預設使用後量子 ML-KEM 金鑰交換作為最高優先順序金鑰交換。
## 了解 Secrets Manager 代理程式快取
Secrets Manager 代理程式使用記憶體內快取，會在 Secrets Manager 代理程式重新啟動時重設。它會根據下列項目定期重新整理快取的秘密值：
+ 預設重新整理頻率 (TTL) 為 300 秒
+ 您可以使用組態檔案修改 TTL
+ 當您在 TTL 過期後請求秘密時，會發生重新整理
**注意**
Secrets Manager 代理程式不包含快取失效。如果秘密在快取項目過期之前輪換，Secrets Manager Agent 可能會傳回過時的秘密值。
Secrets Manager Agent 會以與 回應相同的格式傳回秘密值`GetSecretValue`。不會在快取中加密秘密值。
**Topics**
+ [Secrets Manager 代理程式的運作方式](#agent-overview)
+ [了解 Secrets Manager 代理程式快取](#agent-caching)
+ [建置 Secrets Manager 代理程式](#secrets-manager-agent-build)
+ [安裝 Secrets Manager 代理程式](#secrets-manager-agent-install)
+ [使用 Secrets Manager Agent 擷取秘密](#secrets-manager-agent-call)
+ [了解 `refreshNow` 參數](#secrets-manager-agent-refresh)
+ [設定 Secrets Manager 代理程式](#secrets-manager-agent-config)
+ [選用功能](#secrets-manager-agent-features)
+ [日誌](#secrets-manager-agent-log)
+ [安全考量](#secrets-manager-agent-security)
## 建置 Secrets Manager 代理程式
開始之前，請確定您已為平台安裝標準開發工具和 Rust 工具。
**注意**
在 macOS 上建立已啟用 `fips`功能的代理程式，目前需要以下解決方法：
建立名為 的環境變數`SDKROOT`，其設定為執行的結果 `xcrun --show-sdk-path`
------
#### [ RPM-based systems ]
**在以 RPM 為基礎的系統上建置**
1. 使用 儲存庫中提供的`install`指令碼。
指令碼會在啟動時產生隨機 SSRF 字符，並將其存放在 檔案 中`/var/run/awssmatoken`。安裝指令碼建立的 `awssmatokenreader` 群組可讀取權杖。
1. 若要允許應用程式讀取權杖檔案，您需要將應用程式執行所在的使用者帳戶新增至 `awssmatokenreader`群組。例如，您可以使用下列 usermod 命令授予應用程式讀取權杖檔案的許可，其中 ** 是應用程式執行所在的使用者 ID。
```
sudo usermod -aG awssmatokenreader
```
**安裝開發工具**
在 AL2023 等以 RPM 為基礎的系統上，安裝 開發工具 群組：
```
sudo yum -y groupinstall "Development Tools"
```
1.
**安裝 Rust**
請遵循 [Rust 文件中的安裝](https://www.rust-lang.org/tools/install) *Rust* 說明：
```
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
. "$HOME/.cargo/env"
```
1.
**建置代理程式**
使用貨物建置命令建置 Secrets Manager 代理程式：
```
cargo build --release
```
您可以在 下找到可執行檔`target/release/aws_secretsmanager_agent`。
------
#### [ Debian-based systems ]
**在 Debian 型系統上建置**
1.
**安裝開發工具**
在 Ubuntu 等 Debian 系統上，安裝 build-essential 套件：
```
sudo apt install build-essential
```
1.
**安裝 Rust**
請遵循 [Rust 文件中的安裝](https://www.rust-lang.org/tools/install) *Rust* 說明：
```
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Follow the on-screen instructions
. "$HOME/.cargo/env"
```
1.
**建置代理程式**
使用貨物建置命令建置 Secrets Manager 代理程式：
```
cargo build --release
```
您可以在 下找到可執行檔`target/release/aws_secretsmanager_agent`。
------
#### [ Windows ]
**在 Windows 上建置**
1.
**設定開發環境**
遵循 *Microsoft* [Windows 文件中在 Windows for Rust 上設定開發環境](https://learn.microsoft.com/en-us/windows/dev-environment/rust/setup)的指示。
1.
**建置代理程式**
使用貨物建置命令建置 Secrets Manager 代理程式：
```
cargo build --release
```
您可以在 下找到可執行檔`target/release/aws_secretsmanager_agent.exe`。
------
#### [ Cross-compile natively ]
**以原生方式跨編譯**
1.
**安裝跨編譯工具**
在提供 mingw-w64 套件的分佈上，例如 Ubuntu，安裝跨編譯工具鏈：
```
# Install the cross compile tool chain
sudo add-apt-repository universe
sudo apt install -y mingw-w64
```
1.
**新增 Rust 建置目標**
安裝 Windows GNU 建置目標：
```
rustup target add x86_64-pc-windows-gnu
```
1.
**適用於 Windows 的建置**
跨編譯適用於 Windows 的代理程式：
```
cargo build --release --target x86_64-pc-windows-gnu
```
您可以在 找到可執行檔`target/x86_64-pc-windows-gnu/release/aws_secretsmanager_agent.exe`。
------
#### [ Cross compile with Rust cross ]
**使用 Rust cross 進行交叉編譯**
如果系統無法原生使用跨編譯工具，您可以使用 Rust 跨專案。如需詳細資訊，請參閱 https：//[https://github.com/cross-rs/cross](https://github.com/cross-rs/cross)。
**重要**
我們建議在建置環境中使用 32GB 的磁碟空間。
1.
**設定 Docker**
安裝和設定 Docker：
```
# Install and start docker
sudo yum -y install docker
sudo systemctl start docker
sudo systemctl enable docker # Make docker start after reboot
```
1.
**設定 Docker 許可**
將您的使用者新增至 Docker 群組：
```
# Give ourselves permission to run the docker images without sudo
sudo usermod -aG docker $USER
newgrp docker
```
1.
**適用於 Windows 的建置**
安裝 Cross 並建置可執行檔：
```
# Install cross and cross compile the executable
cargo install cross
cross build --release --target x86_64-pc-windows-gnu
```
------
## 安裝 Secrets Manager 代理程式
從下列安裝選項中選擇您的運算環境。
------
#### [ Amazon EC2 ]
**在 Amazon EC2 上安裝 Secrets Manager 代理程式**
1.
**導覽至組態目錄**
變更為組態目錄：
```
cd aws_secretsmanager_agent/configuration
```
1.
**執行安裝指令碼**
執行 儲存庫中提供的`install`指令碼。
指令碼會在啟動時產生隨機 SSRF 字符，並將其存放在 檔案 中`/var/run/awssmatoken`。安裝指令碼建立的 `awssmatokenreader` 群組可讀取權杖。
1.
**設定應用程式許可**
將應用程式執行所在的使用者帳戶新增至 `awssmatokenreader`群組：
```
sudo usermod -aG awssmatokenreader APP_USER
```
以應用程式執行所在的使用者 ID 取代 *APP\$1USER*。
------
#### [ Container Sidecar ]
您可以使用 Docker 將 Secrets Manager Agent 作為附屬容器與應用程式一起執行。然後，您的應用程式可以從 Secrets Manager Agent 提供的本機 HTTP 伺服器擷取秘密。如需 Docker 的相關資訊，請參閱 [Docker 文件](https://docs.docker.com)。
**為 Secrets Manager Agent 建立附屬容器**
1.
**建立代理程式 Dockerfile**
為 Secrets Manager Agent 附屬容器建立 Dockerfile：
```
# Use the latest Debian image as the base
FROM debian:latest
# Set the working directory inside the container
WORKDIR /app
# Copy the Secrets Manager Agent binary to the container
COPY secrets-manager-agent .
# Install any necessary dependencies
RUN apt-get update && apt-get install -y ca-certificates
# Set the entry point to run the Secrets Manager Agent binary
ENTRYPOINT ["./secrets-manager-agent"]
```
1.
**建立應用程式 Dockerfile**
為您的用戶端應用程式建立 Dockerfile。
1.
**建立 Docker Compose 檔案**
建立 Docker Compose 檔案，以使用共用網路介面執行兩個容器：
**重要**
您必須載入 AWS 登入資料和 SSRF 字符，應用程式才能使用 Secrets Manager Agent。如需 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
secrets-manager-agent:
container_name: secrets-manager-agent
build:
context: .
dockerfile: Dockerfile.agent
network_mode: "container:client-application" # Attach to the client-application container's network
depends_on:
- client-application
```
1.
**複製代理程式二進位**
將`secrets-manager-agent`二進位檔複製到包含 Dockerfiles 和 Docker Compose 檔案的相同目錄。
1.
**建置和執行容器**
使用 Docker Compose 建置和執行容器：
```
docker-compose up --build
```
1.
**後續步驟**
您現在可以使用 Secrets Manager Agent 從用戶端容器擷取秘密。如需詳細資訊，請參閱[使用 Secrets Manager Agent 擷取秘密](#secrets-manager-agent-call)。
------
#### [ Lambda ]
您可以將 [Secrets Manager 代理程式封裝為 Lambda 延伸](https://docs.aws.amazon.com/lambda/latest/dg/packaging-layers.html)模組。然後，您可以將[它做為 layer 新增至 Lambda 函數](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html)，並從 Lambda 函數呼叫 Secrets Manager Agent 以取得秘密。
下列指示說明如何使用 [https://github.com/aws/aws-secretsmanager-agent](https://github.com/aws/aws-secretsmanager-agent)：// `secrets-manager-agent-extension.sh`中的範例指令碼來安裝 Secrets Manager Agent 做為 Lambda 延伸模組，以取得名為 *MyTest* 的秘密。
**為 Secrets Manager Agent 建立 Lambda 擴充功能**
1.
**封裝代理程式層**
從 Secrets Manager Agent 程式碼套件的根目錄，執行下列命令：
```
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_secretsmanager_agent ./bin/secrets-manager-agent
# Copy the `secrets-manager-agent-extension.sh` example script into the `extensions` folder.
mkdir -p ./extensions
cp aws_secretsmanager_agent/examples/example-lambda-extension/secrets-manager-agent-extension.sh ./extensions
# Zip the extension shell script and the binary
zip secrets-manager-agent-extension.zip bin/* extensions/*
# Publish the layer version
LAYER_VERSION_ARN=$(aws lambda publish-layer-version \
--layer-name secrets-manager-agent-extension \
--zip-file "fileb://secrets-manager-agent-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.
**將 layer 連接至函數**
將 layer 版本連接至 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 函數來驗證是否正確擷取秘密。
------
## 使用 Secrets Manager Agent 擷取秘密
若要擷取秘密，請使用秘密名稱或 ARN 做為查詢參數來呼叫本機 Secrets Manager Agent 端點。根據預設，Secrets Manager Agent 會擷取秘密的`AWSCURRENT`版本。若要擷取不同的版本，請使用 versionStage 或 versionId 參數。
**重要**
為了協助保護 Secrets Manager Agent，您必須在每個請求中包含 SSRF 字符標頭：`X-Aws-Parameters-Secrets-Token`。Secrets Manager 代理程式拒絕沒有此標頭或具有無效 SSRF 字符的請求。您可以在 中自訂 SSRF 標頭名稱[設定 Secrets Manager 代理程式](#secrets-manager-agent-config)。
### 所需的許可
Secrets Manager 代理程式使用適用於 Rust 的 AWS SDK，它使用[AWS 登入資料提供者鏈結](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html)。這些 IAM 登入資料的身分決定 Secrets Manager Agent 擷取秘密的許可。
+ `secretsmanager:DescribeSecret`
+ `secretsmanager:GetSecretValue`
如需許可的詳細資訊，請參閱「[的許可參考 AWS Secrets Manager](auth-and-access.md#reference_iam-permissions)」。
**重要**
將秘密值提取至 Secrets Manager Agent 後，任何可存取運算環境和 SSRF 字符的使用者都可以從 Secrets Manager Agent 快取存取秘密。如需詳細資訊，請參閱[安全考量](#secrets-manager-agent-security)。
### 範例請求
------
#### [ curl ]
**Example 範例 – 使用 curl 取得秘密**
下列 curl 範例示範如何從 Secrets Manager Agent 取得秘密。此範例倚賴檔案中存在的 SSRF，也就是安裝指令碼存放的位置。
```
curl -v -H \\
"X-Aws-Parameters-Secrets-Token: $(/var/run/awssmatoken)" \\
'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID' \\
echo
```
------
#### [ Python ]
**Example 範例 – 使用 Python 取得秘密**
下列 Python 範例示範如何從 Secrets Manager Agent 取得秘密。此範例倚賴檔案中存在的 SSRF，也就是安裝指令碼存放的位置。
```
import requests
import json
# Function that fetches the secret from Secrets Manager Agent 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` 參數
Secrets Manager Agent 會使用記憶體內快取來存放秘密值，它會定期重新整理。根據預設，當您在存留時間 (TTL) 過期後請求秘密時，通常會每 300 秒重新整理一次。不過，這種方法有時會導致秘密值過時，特別是當秘密在快取項目過期之前輪換時。
為了解決此限制，Secrets Manager Agent 支援 URL `refreshNow`中稱為 的參數。您可以使用此參數強制立即重新整理秘密的值、略過快取，並確保您擁有up-to-date資訊。
**預設行為 （不含 `refreshNow`)**
+ 使用快取值，直到 TTL 過期
+ 僅在 TTL 之後重新整理秘密 （預設 300 秒）
+ 如果秘密在快取過期之前輪換，可能會傳回過時的值
**使用 的行為 `refreshNow=true`**
+ 完全略過快取
+ 直接從 Secrets Manager 擷取最新的秘密值
+ 使用新值更新快取並重設 TTL
+ 確保您一律取得最新的秘密值
### 強制重新整理秘密值
**重要**
`refreshNow` 的預設值為 `false`。設定為 時`true`，它會覆寫 Secrets Manager Agent 組態檔案中指定的 TTL，並對 Secrets Manager 進行 API 呼叫。
------
#### [ curl ]
**Example 範例 – 使用 curl 強制重新整理秘密**
下列 curl 範例顯示如何強制 Secrets Manager Agent 重新整理秘密。此範例倚賴檔案中存在的 SSRF，也就是安裝指令碼存放的位置。
```
curl -v -H \\
"X-Aws-Parameters-Secrets-Token: $(/var/run/awssmatoken)" \\
'http://localhost:2773/secretsmanager/get?secretId=YOUR_SECRET_ID&refreshNow=true' \\
echo
```
------
#### [ Python ]
**Example 範例 – 使用 Python 強制重新整理秘密**
下列 Python 範例示範如何從 Secrets Manager Agent 取得秘密。此範例倚賴檔案中存在的 SSRF，也就是安裝指令碼存放的位置。
```
import requests
import json
# Function that fetches the secret from Secrets Manager Agent 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}")
```
------
## 設定 Secrets Manager 代理程式
若要變更 Secrets Manager Agent 的組態，請建立 [TOML](https://toml.io/en/) 組態檔案，然後呼叫 `./aws_secretsmanager_agent --config config.toml`。組態選項
**`log_level`**
Secrets Manager 代理程式日誌中報告的詳細資訊層級：DEBUG、INFO、WARN、 ERROR 或 NONE。預設值為 INFO。
**`log_to_file`**
是否要登入檔案或 stdout/stderr： `true`或 `false`。預設值為 `true`。
**`http_port`**
本機 HTTP 伺服器的連接埠，範圍介於 1024 到 65535 之間。預設值為 2773。
**`region`**
AWS 用於請求的區域。如果未指定區域，Secrets Manager Agent 會從 SDK 判斷區域。如需詳細資訊，請參閱《適用於 *AWS Rust 的 SDK 開發人員指南*》中的[指定您的登入資料和預設區域](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/credentials.html)。
**`ttl_seconds`**
快取項目的 TTL，以秒為單位，範圍介於 0 到 3600。預設值為 300。0 表示沒有快取。
**`cache_size`**
快取中可存放的秘密數目上限，範圍介於 1 到 1000。預設為 1000。
**`ssrf_headers`**
Secrets Manager 代理程式會檢查 SSRF 字符的標頭名稱清單。預設值為「X-Aws-Parameters-Secrets-Token、X-Vault-Token」。
**`ssrf_env_variables`**
Secrets Manager 代理程式會依序檢查 SSRF 字符的環境變數名稱清單。環境變數可以包含權杖或權杖檔案的參考，如 所示`AWS_TOKEN=file:///var/run/awssmatoken`。預設值為「AWS\$1TOKEN、AWS\$1SESSION\$1TOKEN、AWS\$1CONTAINER\$1AUTHORIZATION\$1TOKEN」。
**`path_prefix`**
用來判斷請求是否為路徑型請求的 URI 字首。預設值為 "/v1/"。
**`max_conn`**
Secrets Manager Agent 允許的最大 HTTP 用戶端連線數，範圍介於 1 到 1000。預設值為 800。
## 選用功能
Secrets Manager Agent 可以透過將 `--features`旗標傳遞至 ，以選用功能建置`cargo build`。可用的功能包括：建構功能
**`prefer-post-quantum`**
建立最高優先順序`X25519MLKEM768`的金鑰交換演算法。否則，它可用，但不是最高優先順序。 `X25519MLKEM768` 是混合式、post-quantum-secure金鑰交換演算法。
**`fips`**
將代理程式使用的密碼套件限制為僅 FIPS 核准的密碼。
## 日誌
**本機記錄**
Secrets Manager Agent 會根據`log_to_file`組態變數，在本機將錯誤記錄到 檔案`logs/secrets_manager_agent.log`或 stdout/stderr。當您的應用程式呼叫 Secrets Manager 代理程式以取得秘密時，這些呼叫會出現在本機日誌中。它們不會出現在 CloudTrail 日誌中。
**日誌輪換**
Secrets Manager 代理程式會在檔案達到 10 MB 時建立新的日誌檔案，並總共存放最多五個日誌檔案。
**AWS 服務記錄**
日誌不會移至 Secrets Manager、CloudTrail 或 CloudWatch。從 Secrets Manager Agent 取得秘密的請求不會出現在這些日誌中。當 Secrets Manager 代理程式呼叫 Secrets Manager 以取得秘密時，該呼叫會以包含 的使用者代理程式字串記錄在 CloudTrail 中`aws-secrets-manager-agent`。
您可以在 中設定記錄選項[設定 Secrets Manager 代理程式](#secrets-manager-agent-config)。
## 安全考量
**信任網域**
對於代理程式架構，信任網域是可以存取代理程式端點和 SSRF 字符的地方，通常是整個主機。Secrets Manager 代理程式的信任網域應與可使用 Secrets Manager 登入資料的網域相符，以維持相同的安全狀態。例如，在 Amazon EC2 上，Secrets Manager Agent 的信任網域與使用 Amazon EC2 角色時的登入資料網域相同。
**重要**
尚未使用代理程式解決方案且已將 Secrets Manager 登入資料鎖定至應用程式的安全意識應用程式，應考慮使用語言特定的 AWS SDKs 或快取解決方案。如需詳細資訊，請參閱[取得秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html)。