Configure the Amazon SDK for Ruby
Learn how to configure the Amazon SDK for Ruby. You must establish how your code authenticates with Amazon when you develop with Amazon Web Services. You must also set the Amazon Web Services Region you want to use.
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 Service. After valid credentials are found, the search is stopped. This systematic search is called the default credential provider chain.
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. For more information, see Precedence of
settings in the Amazon SDKs and Tools Reference Guide.
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 | |
Web identity token from Amazon Security Token Service (Amazon STS) | Assume
role credential provider Using |
Aws::AssumeRoleWebIdentityCredentials
|
Amazon IAM Identity Center. In this guide, see SDK authentication with Amazon. | 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 |
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.
If you followed the recommended approach for new users to get started, you set up Amazon IAM Identity Center authentication during SDK authentication with Amazon 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.
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.
Setting a Region
You need to set a Region when using most Amazon Web Services. The Amazon SDK for Ruby searches for a Region in the following order:
For more information on the region
setting, see Amazon Web Services Region in the
Amazon SDKs and Tools Reference Guide. The rest of this section describes how to
set a Region, starting with the most common approach.
Setting the Region using the
shared config
file
Set the region by setting the region
variable in the shared Amazon config
file.
For more information about the shared config
file, see Shared config and credentials files
in the Amazon SDKs and Tools Reference Guide.
Example of setting this value in the config
file:
[default] region = us-west-2
The shared config
file is not checked if the environment variable
AWS_SDK_CONFIG_OPT_OUT
is set.
Setting the Region using environment variables
Set the Region by setting the AWS_REGION
environment variable.
Use the export
command to set this variable on Unix-based systems, such
as Linux or macOS. The following example sets the Region to
us-west-2
.
export AWS_REGION=us-west-2
To set this variable on Windows, use the set
command. The following
example sets the Region to us-west-2
.
set AWS_REGION=us-west-2
Setting the Region with
Aws.config
Set the Region by adding a region
value to the Aws.config
hash. The following example updates the Aws.config
hash to use the
us-west-1
Region.
Aws.config.update({region: 'us-west-1'})
Any clients or resources that you create later are bound to this Region.
Setting the Region in a client or resource object
Set the Region when you create an Amazon client or resource. The following example
creates an Amazon S3 resource object in the us-west-1
Region. Choose the correct
Region for your Amazon resources. A service client object is immutable, so you must
create a new client for each service to which you make requests and for making requests
to the same service using a different configuration.
s3 = Aws::S3::Resource.new(region: 'us-west-1')
Setting a nonstandard endpoint
The region is used to construct an SSL endpoint to use for Amazon requests. If you need
to use a nonstandard endpoint in the Region you’ve selected, add an endpoint
entry to Aws.config
. Alternatively, set the endpoint:
when
creating a service client or resource object. The following example creates an Amazon S3
resource object in the other_endpoint
endpoint.
s3 = Aws::S3::Resource.new(endpoint: other_endpoint)
To use an endpoint of your choosing for API requests and to have that choice persist, see the Service-specific endpoints configuration option in the Amazon SDKs and Tools Reference Guide.