AWS Credentials

Four plugins call AWS services and therefore need valid AWS credentials:

Plugin	Calls	Gem to add
IAM Authentication (iam)	RDS, to generate an authentication token	aws-sdk-rds
AWS Secrets Manager (secrets_manager)	Secrets Manager, to retrieve credentials	aws-sdk-secretsmanager
KMS Encryption (kms_encryption)	KMS, to unwrap data keys	aws-sdk-kms
Custom Endpoint (custom_endpoint)	RDS, to fetch the custom endpoint's members	aws-sdk-rds

The AWS Advanced Ruby Driver Wrapper does not implement its own credential handling. It uses the AWS SDK for Ruby's default credential provider chain, so anything that works for the SDK works here.

Where credentials are looked for

The SDK searches these sources in order, and the first one that yields credentials wins:

1. Environment variables — AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
2. Web identity token credentials — AWS_WEB_IDENTITY_TOKEN_FILE
3. Shared credentials file — ~/.aws/credentials
4. Shared configuration file — ~/.aws/config
5. IAM Identity Center (SSO) credentials
6. Container credentials — ECS task roles
7. EC2 instance profile credentials

Supplying a provider directly

To bypass the chain, pass a provider through the aws_credentials_provider connection property:

aws_credentials_provider: Aws::AssumeRoleCredentials.new(
  client: Aws::STS::Client.new(region: 'us-east-1'),
  role_arn: 'arn:aws:iam::123456789012:role/my-role',
  role_session_name: 'my-app'
)

This is a single property shared by the IAM, Secrets Manager, and KMS plugins, not one property each, so setting it once covers token generation, secret retrieval, and data-key unwrapping alike. When it is not set, each plugin falls back to the default chain above.

Long-term and temporary credentials

Long-term credentials — IAM user access keys — never expire and need no refresh. They are convenient for local development and are not recommended for production.

Temporary credentials — from IAM roles, STS, SSO, or a credential process — carry a session token and an expiration. They are the right choice for production, with one condition attached: the SDK only refreshes them automatically for some sources.

Automatic refresh is not universal

This is the distinction worth internalising, because getting it wrong produces an outage at the moment your credentials expire rather than at deploy time.

Refreshed automatically

• IAM roles — EC2 instance profiles and Lambda execution roles; the SDK fetches fresh credentials from the instance metadata service
• ECS task roles — fetched from the container metadata endpoint
• Assume role — configured in ~/.aws/config with role_arn and source_profile, or constructed as Aws::AssumeRoleCredentials; the SDK calls STS again as needed
• SSO — configured in ~/.aws/config
• Web identity tokens — from an OIDC provider
• Credential process — configured in ~/.aws/config; the SDK re-runs the process

Not refreshed

• Environment variables — even when they hold temporary credentials complete with a session token, they are static values and nothing will refresh them
• Credentials pasted into ~/.aws/credentials or ~/.aws/config — likewise static, even though they carry an expiration

Operations fail with authentication errors the moment temporary credentials expire without having been refreshed.

Common pitfalls

Putting temporary credentials in environment variables. Exporting the output of aws sts assume-role as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN works until they expire, and then stops working. Configure assume-role in ~/.aws/config, or use an IAM role, so the SDK can refresh.

Mixing credential sources. Environment variables sit at the top of the chain, so setting them alongside a credential process or assume-role configuration silently bypasses that configuration entirely.

Hardcoding the result of aws sso login. Copying those credentials into ~/.aws/credentials turns refreshable credentials into static ones. Configure SSO in ~/.aws/config instead.

Omitting the session token. Temporary credentials need all three values; the access key and secret alone will fail authentication even when both are correct.

Recommendation

For production, use IAM roles — EC2 instance profiles, ECS task roles, or Lambda execution roles — rather than long-term access keys or temporary credentials you place by hand. They refresh without any configuration on your part, and there is no secret to leak.

For more detail, see the AWS SDK for Ruby developer guide and the AWS credentials reference.