All requests to AWS must be cryptographically signed by using credentials issued by AWS. At runtime, the SDK retrieves configuration values for credentials by checking several locations.
Authentication with AWS 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 AWS authentication for your project, see Authentication and access in the AWS SDKs and Tools Reference Guide.
The credential provider
chain
If you don't explicitly specify a credential provider when constructing a client, the AWS 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 AWS 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 AWS IAM Identity Center authentication during Authenticating the AWS SDK for Ruby with AWS 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 AWS 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 AWS config file.
The AWS SDKs and Tools Reference Guide has information on SDK configuration
settings used by all AWS SDKs and the AWS CLI. To learn more about how to configure the SDK
through the shared AWS 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 AWS, the AWS SDK for Ruby checks the credential providers in the order listed in the following table.
| Credential provider by precedence | AWS SDKs and Tools Reference Guide | AWS SDK for Ruby API Reference |
|---|---|---|
| AWS access keys (temporary and long-term credentials) | AWS access keys | |
| Web identity token from AWS Security Token Service (AWS STS) | Assume role
credential provider Using |
Aws::AssumeRoleWebIdentityCredentials
|
| AWS IAM Identity Center. In this guide, see Authenticating the AWS SDK for Ruby with AWS. | IAM Identity Center credential provider | Aws::SSOCredentials |
Trusted entity provider (such as AWS_ROLE_ARN). In this guide, see
Creating an AWS STS access token. |
Assume role
credential provider Using |
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 AWS SDK for Ruby environment variable AWS_SDK_CONFIG_OPT_OUT is set, the
shared AWS config file, typically at ~/.aws/config, will not be parsed for
credentials.
Creating an AWS STS access token
Assuming a role involves using a set of temporary security credentials that you can use to
access AWS 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 AWS Security Token Service (AWS 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 AWS config file instead,
see Assume role
credential provider in the AWS SDKs and Tools Reference Guide.
