# Using Amazon SDK for Ruby credential providers
<a name="credential-providers"></a>

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](https://docs.amazonaws.cn/sdkref/latest/guide/access.html) in the *Amazon SDKs and Tools Reference Guide*.

## Credential provider chain
<a name="credchain"></a>

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 authenticated using login with console credentials during [Authenticating with Amazon using Amazon SDK for Ruby](credentials.md). 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](https://docs.amazonaws.cn/sdkref/latest/guide/access.html) 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](https://docs.amazonaws.cn/sdkref/latest/guide/file-format.html). To learn more about how to configure the SDK through setting environment variables, see [Environment variables support](https://docs.amazonaws.cn/sdkref/latest/guide/environment-variables.html).

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](https://docs.amazonaws.cn/sdkref/latest/guide/feature-static-credentials.html) | [https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/Credentials.html](https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/Credentials.html)[https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/SharedCredentials.html](https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/SharedCredentials.html) | 
| Web identity token from Amazon Security Token Service (Amazon STS)  | [Assume role credential provider](https://docs.amazonaws.cn/sdkref/latest/guide/feature-assume-role-credentials.html)Using `role_arn`, `role_session_name`, and `web_identity_token_file` | [https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/AssumeRoleWebIdentityCredentials.html](https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/AssumeRoleWebIdentityCredentials.html)  | 
| Amazon IAM Identity Center. In this guide, see [Authenticating with Amazon using Amazon SDK for Ruby](credentials.md). | [IAM Identity Center credential provider](https://docs.amazonaws.cn/sdkref/latest/guide/feature-sso-credentials.html) | [https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/SSOCredentials.html](https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/SSOCredentials.html) | 
| Trusted entity provider (such as AWS\$1ROLE\$1ARN). In this guide, see [Creating an Amazon STS access token](#aws-ruby-sdk-credentials-access-token). | [Assume role credential provider](https://docs.amazonaws.cn/sdkref/latest/guide/feature-assume-role-credentials.html)Using `role_arn` and `role_session_name` | [https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/AssumeRoleCredentials.html](https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/AssumeRoleCredentials.html) | 
| Login credential provider | [Login credential provider](https://docs.amazonaws.cn/sdkref/latest/guide/feature-login-credentials.html) | [https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/LoginCredentials.html](https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/LoginCredentials.html) | 
| Process credential provider | [Process credential provider](https://docs.amazonaws.cn/sdkref/latest/guide/feature-process-credentials.html) | [https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/ProcessCredentials.html](https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/ProcessCredentials.html) | 
| Amazon Elastic Container Service (Amazon ECS) credentials | [Container credential provider](https://docs.amazonaws.cn/sdkref/latest/guide/feature-container-credentials.html) | [https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/ECSCredentials.html](https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/ECSCredentials.html) | 
| Amazon Elastic Compute Cloud (Amazon EC2) instance profile credentials (IMDS credential provider) | [IMDS credential provider](https://docs.amazonaws.cn/sdkref/latest/guide/feature-imds-credentials.html) | [https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/InstanceProfileCredentials.html](https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/InstanceProfileCredentials.html) | 

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
<a name="aws-ruby-sdk-credentials-access-token"></a>

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 [https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/AssumeRoleCredentials.html](https://docs.amazonaws.cn/sdk-for-ruby/v3/api/Aws/AssumeRoleCredentials.html) 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](https://docs.amazonaws.cn/sdkref/latest/guide/feature-assume-role-credentials.html) in the *Amazon SDKs and Tools Reference Guide*.