How certificate automation works Prerequisites Install the provider Configure the provider Required permissions Verify the installation Configuration reference Logging

AWS Workload Credentials Provider

The AWS Workload Credentials Provider automates the use of public and private TLS certificates exported from ACM. The provider periodically retrieves certificates and their private keys, writes them to configured paths, and optionally runs a command to reload dependent services such as web servers.

You can use the Workload Credentials Provider with the following compute environments:

Amazon Elastic Compute Cloud (Amazon EC2)
On-premises servers with AWS credentials

The Workload Credentials Provider uses IAM role assumption to retrieve certificates. It runs natively as a system service on both Linux and Windows under a dedicated low-privilege user and writes certificate files with restricted permissions.

Important

Only exportable certificates can be used with this provider. For more information, see AWS Certificate Manager exportable public certificates and Exporting a private certificate.

The AWS Workload Credentials Provider is open source. For source code and contributions, see the GitHub repository.

How certificate automation works

The provider uses a scheduler that refreshes each configured certificate on a fixed interval:

The refresh interval is 24 hours.
On each cycle, the provider exports the certificate, compares it against the files on disk, and writes new files only if the content has changed.
When certificate files are updated, the configured refresh_command runs (for example, to reload NGINX or Apache).
If certificate content hasn't changed, the refresh command is skipped.

The provider performs an initial refresh on every system boot and shortly after service startup, with a small random jitter to avoid synchronized API calls when multiple providers start simultaneously across the fleet.

The provider also supports dynamic configuration reload, allowing you to add, remove, or modify certificates without reinstalling. For more information, see Dynamic configuration reload.

Prerequisites

Before you install the provider, ensure you have the following:

A Linux instance with systemd (Amazon Linux 2023, Ubuntu 20.04+, or RHEL 8+)
Or a Windows instance running Windows Server 2016 or later with PowerShell 5.1 or later
Administrator access to run the installer
An exportable certificate in ACM
An IAM role with ACM export permissions (see Required permissions)
AWS credentials available on the instance (instance profile, environment variables, or credential file)

Install the provider

Linux

Build the provider

Build the provider binary from source, or obtain the pre-built binary for your platform. Follow the instructions at Install Rust to install the Rust toolchain.
```
cargo build --release
```
The executable is at target/release/aws-workload-credentials-provider.
Create a configuration file

Create a TOML configuration file with your certificate details. For examples, see Configure the provider. The installer copies this file to /etc/aws-workload-credentials-provider/config.toml automatically when you use the --config option.

Run the installer

Run the install script as root:


cd aws_workload_credentials_provider_common/configuration
sudo ./install --config /path/to/your/config.toml

(Optional) Provide AWS credentials

On Amazon EC2 instances with an attached instance profile, the provider obtains credentials automatically. For other environments, create a systemd override file to inject credentials:


sudo mkdir -p /etc/systemd/system/aws-workload-credentials-provider-acm.service.d
sudo tee /etc/systemd/system/aws-workload-credentials-provider-acm.service.d/creds.conf > /dev/null <<EOF
[Service]
Environment="AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE"
Environment="AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
Environment="AWS_REGION=us-west-2"
EOF
sudo systemctl daemon-reload
sudo systemctl restart aws-workload-credentials-provider-acm

Windows

Build or obtain the provider

Build the provider binary from source for Windows, or obtain the pre-built binary. Follow the instructions at Install Rust to install the Rust toolchain.
```
cargo build --release
```
The executable is at target\release\aws-workload-credentials-provider.exe.
Create a configuration file

Create a TOML configuration file with your certificate details. For examples, see Configure the provider. The installer copies this file to C:\ProgramData\AWS\WorkloadCredentialsProvider\config.toml automatically when you use the -Config parameter.

Run the installer

Run the install script as Administrator:


cd aws_workload_credentials_provider_common\configuration
.\install.ps1 -Config C:\path\to\your\config.toml

To install without starting the service:


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

(Optional) Provide AWS credentials

On Amazon EC2 instances with an attached instance profile, the provider obtains credentials automatically through IMDS. For other environments, set environment variables for the service through the Windows Registry:


$regPath = "HKLM:\SYSTEM\CurrentControlSet\Services\AWSWorkloadCredentialsProvider-ACM"
$envVars = @(
    "AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE",
    "AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "AWS_REGION=us-west-2"
)
New-ItemProperty -Path $regPath -Name "Environment" -Value $envVars -PropertyType MultiString -Force
Restart-Service AWSWorkloadCredentialsProvider-ACM

Configure the provider

Create a TOML configuration file with your certificate details. The installer copies this file to /etc/aws-workload-credentials-provider/config.toml when you use the --config option.

Note

When chain_path is omitted, the certificate chain is appended to the file at certificate_path to produce a fullchain file. This is compatible with web servers that expect a single file containing the certificate and its chain.

Dynamic configuration reload

You can update the provider's configuration without reinstalling by running the acm reload command. This validates the new configuration, updates permissions to match the new certificate paths, and restarts the service.

Certificates removed from the configuration stop being refreshed. New certificates begin their first export immediately. Each certificate runs as an independent task, so a failure in one does not affect others.

Required permissions

Base credentials

The provider's base credentials (instance profile or environment) must be able to assume the role specified in each certificate's role_arn:


{
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Resource": "arn:aws:iam::123456789012:role/ACMExportRole"
}

Certificate export role

The role specified in role_arn requires the following permissions:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "acm:ExportCertificate",
            "Resource": "arn:aws:acm:us-west-2:123456789012:certificate/*"
        }
    ]
}

The role's trust policy must allow the provider's base identity to assume it:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::123456789012:role/EC2InstanceRole"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Refresh command permissions (Linux)

On Linux, the provider executes the configured refresh_command through sudo. The installer generates a sudoers entry at /etc/sudoers.d/aws-workload-credentials-provider that permits the provider user to run the exact configured command without a password prompt.

Important

Ensure /etc/sudoers includes the /etc/sudoers.d directory. The installer warns if this include directive is not present. Without it, the generated sudoers file has no effect and refresh commands will fail.

On Windows, the provider triggers the refresh_command as a SYSTEM scheduled task.

Verify the installation

After installation, verify the provider is running and certificates are being written:

Configuration reference

Field	Required	Default	Description
`logging.log_level`	No	`info`	Logging verbosity: `debug`, `info`, `warn`, `error`, `none`
`logging.log_to_file`	No	`true`	Write logs to file (`true`) or stdout/stderr (`false`)
`capabilities.acm.enabled`	No	`false`	Enable or disable the ACM capability
`certificates[].certificate_arn`	Yes	—	ARN of the ACM certificate to export
`certificates[].role_arn`	Yes	—	IAM role ARN to assume for the `ExportCertificate` call
`certificates[].certificate_path`	Yes	—	Absolute path to write the certificate file
`certificates[].private_key_path`	Yes	—	Absolute path to write the private key file
`certificates[].chain_path`	No	—	Absolute path to write the certificate chain. If omitted, chain is appended to `certificate_path`
`certificates[].refresh_command`	No	—	Command to run after certificate files are updated. Must be an absolute path
`certificates[].certificate_and_chain_permission`	No	`0600`	File permissions for cert and chain files (Linux `mode` format)
`certificates[].key_permission`	No	`0600`	File permissions for the private key file (Linux `mode` format)

Logging

On Linux, the provider logs to /opt/aws/workload-credentials-provider/logs/acm_provider.log.

On Windows, the provider logs to C:\ProgramData\AWS\WorkloadCredentialsProvider\logs\acm_provider.log. Service start and stop events are also recorded in the Windows Application Event Log under the source AWSWorkloadCredentialsProvider-ACM.

Log rotation — The provider creates a new log file when the current file reaches 10 MB, and stores up to five archived log files.

AWS service logging — When the provider calls ExportCertificate, that call is recorded in AWS CloudTrail with a user agent string containing aws-workload-credentials-provider. The provider's internal operations (scheduler cycles, file writes) appear only in the local log.

You can configure logging with the log_level and log_to_file settings. For more information, see Configuration reference.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Automation outside integrated services

Certificate management

AWS Workload Credentials Provider

Important

How certificate automation works

Prerequisites

Install the provider

Build the provider

Create a configuration file

Run the installer

(Optional) Provide AWS credentials

Build or obtain the provider

Create a configuration file

Run the installer

(Optional) Provide AWS credentials

Configure the provider

Note

Dynamic configuration reload

Required permissions

Base credentials

Certificate export role

Refresh command permissions (Linux)

Important

Verify the installation

Configuration reference

Logging