Using Amazon SDK for Ruby credential providers - Amazon SDK for Ruby
The credential provider chainCredential provider chainCreating an Amazon STS access token
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using Amazon SDK for Ruby credential providers

All requests to Amazon must be cryptographically signed by using credentials issued by Amazon. At runtime, the SDK retrieves configuration values for credentials by checking several locations.

Authentication with Amazon can be handled outside of your codebase. Many authentication methods can be automatically detected, used, and refreshed by the SDK using the credential provider chain.

For guided options for getting started on Amazon authentication for your project, see Authentication and access in the Amazon SDKs and Tools Reference Guide.

The credential provider chain

If you don't explicitly specify a credential provider when constructing a client, the Amazon SDK for Ruby uses a credential provider chain that checks a series of places where you can supply credentials. Once the SDK finds credentials in one of these locations, the search stops.

Credential provider chain

All SDKs have a series of places (or sources) that they check in order to get valid credentials to use to make a request to an Amazon Web Services service. After valid credentials are found, the search is stopped. This systematic search is called the default credential provider chain.

Note

If you followed the recommended approach for new users to get started, you set up Amazon IAM Identity Center authentication during Authenticating with Amazon using Amazon SDK for Ruby of the Getting started topic. Other authentication methods are useful for different situations. To avoid security risks, we recommend always using short-term credentials. For other authentication method procedures, see Authentication and access in the Amazon SDKs and Tools Reference Guide.

For each step in the chain, there are different ways to set the values. Setting values directly in code always takes precedence, followed by setting as environment variables, and then in the shared Amazon config file.

The Amazon SDKs and Tools Reference Guide has information on SDK configuration settings used by all Amazon SDKs and the Amazon CLI. To learn more about how to configure the SDK through the shared Amazon config file, see Shared config and credentials files. To learn more about how to configure the SDK through setting environment variables, see Environment variables support.

To authenticate with Amazon, the Amazon SDK for Ruby checks the credential providers in the order listed in the following table.

Credential provider by precedence Amazon SDKs and Tools Reference Guide Amazon SDK for Ruby API Reference
Amazon access keys (temporary and long-term credentials) Amazon access keys

Aws::Credentials

Aws::SharedCredentials
Web identity token from Amazon Security Token Service (Amazon STS) Assume role credential provider

Using role_arn, role_session_name, and web_identity_token_file

 Aws::AssumeRoleWebIdentityCredentials
Amazon IAM Identity Center. In this guide, see Authenticating with Amazon using Amazon SDK for Ruby. IAM Identity Center credential provider Aws::SSOCredentials
Trusted entity provider (such as AWS_ROLE_ARN). In this guide, see Creating an Amazon STS access token. Assume role credential provider

Using role_arn and role_session_name

 Aws::AssumeRoleCredentials
Process credential provider Process credential provider Aws::ProcessCredentials
Amazon Elastic Container Service (Amazon ECS) credentials Container credential provider Aws::ECSCredentials
Amazon Elastic Compute Cloud (Amazon EC2) instance profile credentials (IMDS credential provider) IMDS credential provider Aws::InstanceProfileCredentials

If the Amazon SDK for Ruby environment variable AWS_SDK_CONFIG_OPT_OUT is set, the shared Amazon config file, typically at ~/.aws/config, will not be parsed for credentials.

Creating an Amazon STS access token

Assuming a role involves using a set of temporary security credentials that you can use to access Amazon resources that you might not normally have access to. These temporary credentials consist of an access key ID, a secret access key, and a security token. You can use the Aws::AssumeRoleCredentials method to create an Amazon Security Token Service (Amazon STS) access token.

The following example uses an access token to create an Amazon S3 client object, where linked::account::arn is the Amazon Resource Name (ARN) of the role to assume and session-name is an identifier for the assumed role session.

role_credentials = Aws::AssumeRoleCredentials.new(
  client: Aws::STS::Client.new,
  role_arn: "linked::account::arn",
  role_session_name: "session-name"
)

s3 = Aws::S3::Client.new(credentials: role_credentials)

For more information about setting role_arn or role_session_name, or about setting these using the shared Amazon config file instead, see Assume role credential provider in the Amazon SDKs and Tools Reference Guide.