AWS Workload Credentials Provider

The AWS Workload Credentials Provider (formerly the AWS Secrets Manager Agent) is a client-side solution that helps you standardize how you consume credentials from AWS services across your compute environments. It includes the following capabilities:

• Secrets Manager — An HTTP interface for retrieving and caching secrets from AWS Secrets Manager. Supported on AWS Lambda, Amazon ECS, Amazon EKS, and Amazon EC2. Enabled by default.
• Certificate Management — Automatic export and refresh of certificates from AWS Certificate Manager to the local filesystem. Supported on Amazon EC2 and on-premise hosts. Opt-in via configuration.

Secrets Manager capability

The Workload Credentials Provider retrieves and caches secrets in memory so that your applications can consume secrets from localhost instead of making direct calls to Secrets Manager. It can only read secrets - it can't modify them.

The Workload Credentials Provider uses the AWS credentials you provide in your environment to make calls to Secrets Manager. The Workload Credentials Provider offers protection against Server Side Request Forgery (SSRF) to help improve secret security. It also uses the post-quantum ML-KEM key exchange as the highest-priority key exchange by default. You can configure the Workload Credentials Provider by setting the maximum number of connections, the time to live (TTL), the localhost HTTP port, and the cache size.

Because the Workload Credentials Provider uses an in-memory cache, it resets when the Workload Credentials Provider restarts. The Workload Credentials Provider periodically refreshes the cached secret value. The refresh happens when you try to read a secret from the Workload Credentials Provider after the TTL has expired. The default refresh frequency (TTL) is 300 seconds, and you can change it by using a Configuration file which you pass to the Workload Credentials Provider using the sm start --config /path/to/config.toml command line argument. The Workload Credentials Provider does not include cache invalidation. For example, if a secret rotates before the cache entry expires, the Workload Credentials Provider might return a stale secret value.

The Workload Credentials Provider returns secret values in the same format as the response of GetSecretValue. Secret values are not encrypted in the cache.

Certificate Management capability

The Workload Credentials Provider exports certificates from AWS Certificate Manager (ACM) and writes them as PEM files to the local filesystem. It automatically checks for updated certificates every 24 hours and optionally runs a user-configured command after each successful refresh (for example, to reload a web server). You can configure up to 50 certificates. Each certificate is managed by an independent background task, providing fault isolation so that one certificate's failure does not affect others.

The Certificate Management capability supports Linux and Windows, and works with web servers such as NGINX and Apache.

The Workload Credentials Provider uses the AWS credentials you provide in your environment to assume the role you have configured for each certificate, and then calls ACM to export the certificate. The install script sets up the necessary permissions for the provider process to write certificate files to customer-specified directories and execute refresh commands.

You can provide a custom configuration by passing --config /path/to/config.toml on startup or on reload while the provider is running. On Windows, use -Config C:\path\to\config.toml when invoking the PowerShell scripts and --Config C:\path\to\config.toml when executing the binary command. The reload re-applies permissions and restarts the ACM service.

For full configuration details, see Configure the Workload Credentials Provider.

To download the source code, see https://github.com/aws/aws-workload-credentials-provider on GitHub.

Topics - AWS Workload Credentials Provider - Secrets Manager capability - Certificate Management capability - Step 1: Build the Workload Credentials Provider binary - [ RPM-based systems ] - [ Debian-based systems ] - [ Windows ] - [ Cross-compile natively ] - Step 2: Install the Workload Credentials Provider - [ Amazon EC2 (Linux) ] - [ Windows EC2 ] - [ Running as a Container Sidecar ] - [ AWS Lambda ] - Step 3: Retrieve secrets with the Workload Credentials Provider - [ curl ] - [ Python ] - refreshNow parameter behavior - Using the refreshNow parameter - Example - GET request with refreshNow parameter - [ curl ] - [ Python ] - Role chaining (cross-account access) - Pre-fetching - Step 4: Retrieve certificates with the Workload Credentials Provider - Configure the Workload Credentials Provider - Optional features - Logging - Security considerations - Running Integration Tests Locally - Prerequisites - Required AWS Permissions - Required IAM Roles (for role chaining tests) - Running Tests - Option 1: Using the test script - Option 2: Manual execution - Test Organization

Step 1: Build the Workload Credentials Provider binary

To build the Workload Credentials Provider binary natively, you need the standard development tools and the Rust tools. Alternatively, you can cross-compile for systems that support it, or you can use Rust cross to cross-compile.

NOTE: To ensure a stable experience, use a specific git tag when building from source code. You can find a list of version tags here. Tags are in the pattern /v\d+\.\d+\.\d+/ and follow SemVer 2.0.0.

Example: git clone --branch <git tag> https://github.com/aws/aws-workload-credentials-provider.git

NOTE: Building the provider with the fips feature enabled on macOS currently requires the following workaround:

• Create an environment variable called SDKROOT which is set to the result of running xcrun --show-sdk-path

[ RPM-based systems ]

1. On RPM-based systems such as AL2023, you can install the development tools by using the Development Tools group.

sh sudo yum -y groupinstall "Development Tools"

1. Follow the instructions at Install Rust in the Rust documentation.

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

1. Build the provider using the cargo build command:

sh cargo build --release

You will find the executable under target/release/aws-workload-credentials-provider.

[ Debian-based systems ]

1. On Debian-based systems such as Ubuntu, you can install the developer tools using the build-essential package.

sh sudo apt install build-essential

1. Follow the instructions at Install Rust in the Rust documentation.

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

1. Build the provider using the cargo build command:

sh cargo build --release

You will find the executable under target/release/aws-workload-credentials-provider.

[ Windows ]

To build on Windows, follow the instructions at Set up your dev environment on Windows for Rust in the Microsoft Windows documentation.

1. Build the provider using the cargo build command:

sh cargo build --release

You will find the executable under target/release/aws-workload-credentials-provider.exe.

[ Cross-compile natively ]

You can cross-compile for Windows from Linux using cargo-xwin.

# Install clang
sudo yum install -y clang

# Install cargo-xwin
cargo install cargo-xwin

# Install the Rust build target
rustup target add x86_64-pc-windows-msvc

# Cross compile for Windows
cargo xwin build --release --target x86_64-pc-windows-msvc

You will find the executable at target/x86_64-pc-windows-msvc/release/aws-workload-credentials-provider.exe.

Step 2: Install the Workload Credentials Provider

Based on the type of compute, you have several options for installing the Workload Credentials Provider. The install script sets up both the Secrets Manager and Certificate Management capabilities.

[ Amazon EC2 (Linux) ]

To install the Workload Credentials Provider

1. cd aws_workload_credentials_provider_common/configuration
2. Run the install script provided in the repository.

sh sudo ./install --config /path/to/config.toml

The script accepts the following options: - --config <file> — (Optional) Bootstrap config to copy to the configuration directory - --no-start — (Optional) Install but don't start services - --no-privileges — (Optional) Skip Linux capabilities on ACM service - --no-sudoers — (Optional) Skip sudoers generation

The script generates a random SSRF token on startup and stores it in the file /var/run/awssmatoken. The token is readable by the aws-wcp-token group that the install script creates.

1. To allow your application to read the token file, you need to add the user account that your application runs under to the aws-wcp-token group. For example, you can grant permissions for your application to read the token file with the following usermod command, where is the user ID under which your application runs.

sh sudo usermod -aG aws-wcp-token <APP_USER>

[ Windows EC2 ]

To install the Workload Credentials Provider

1. cd aws_workload_credentials_provider_common\configuration
2. Run the install.ps1 script as Administrator.

powershell .\install.ps1 -Config C:\path\to\config.toml

The script accepts the following parameters: - -Config <file> — (Optional) Bootstrap config to use - -NoStart — (Optional) Install but don't start services

The script generates a random SSRF token on startup and stores it in the file C:\ProgramData\AWS\WorkloadCredentialsProvider\awssmatoken. The token is readable by the Secrets Manager service account (NT SERVICE\AWSWorkloadCredentialsProvider-SecretsManager) that the install script configures.

1. To allow your application to read the token file, you need to grant read access to the user account that your application runs under. For example, you can grant permissions for your application to read the token file with the following icacls command, where is the user account under which your application runs.

powershell icacls "C:\ProgramData\AWS\WorkloadCredentialsProvider\awssmatoken" /grant "<APP_USER>:(R)"

Note: When using the install script, the provider reads the SSRF token from file via AWS_TOKEN=file://C:\ProgramData\AWS\WorkloadCredentialsProvider\awssmatoken set on the service. Your application must also read the token from this path and pass it in the X-Aws-Parameters-Secrets-Token header. If you were previously setting AWS_TOKEN as an environment variable with a literal token value or a custom file path, update your application to read from the new token file path instead.

[ Running as a Container Sidecar ]

You can run the Workload Credentials Provider as a sidecar container alongside your application by using Docker. Then your application can retrieve secrets from the local HTTP server the Workload Credentials Provider provides. For information about Docker, see the Docker documentation.

Note: The Certificate Management capability is not supported in container environments.

To create a sidecar container for the Workload Credentials Provider with Docker

1. Create a Dockerfile for the Workload Credentials Provider sidecar container. The following example creates a Docker container with the Workload Credentials Provider binary.

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