locate_credentials {aws.signature}

Locate AWS Credentials

Description

Locate AWS credentials from likely sources

Usage

locate_credentials(
  key = NULL,
  secret = NULL,
  session_token = NULL,
  region = NULL,
  file = Sys.getenv("AWS_SHARED_CREDENTIALS_FILE", default_credentials_file()),
  profile = NULL,
  default_region = getOption("cloudyr.aws.default_region", "us-east-1"),
  verbose = getOption("verbose", FALSE)
)

Arguments

key

An AWS Access Key ID

secret

An AWS Secret Access Key

session_token

Optionally, an AWS Security Token Service (STS) temporary Session Token

region

A character string containing the AWS region for the request. If missing, “us-east-1” is assumed.

file

A character string containing a path to a centralized ‘⁠.aws/credentials⁠’ file.

profile

A character string specifying which profile to use from the file. By default, the profile named in AWS_PROFILE is used, otherwise the “default” profile is used.

default_region

A character string specifying a default string to use of no user-supplied value is found.

verbose

A logical indicating whether to be verbose.

Details

These functions locate values of AWS credentials (access key, secret access key, session token, and region) from likely sources. The order in which these are searched is as follows:

1. user-supplied values passed to the function

2. environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, and AWS_SESSION_TOKEN)

3. an instance role (on the running ECS task from which this function is called) as identified by metadata, if the aws.ec2metadata package is installed

4. an IAM instance role (on the running EC2 instance from which this function is called) as identified by metadata, if the aws.ec2metadata package is installed

5. a profile in a local credentials dot file in the current working directory, using the profile specified by AWS_PROFILE

6. the default profile in that local credentials file

7. a profile in a global credentials dot file in a location set by AWS_SHARED_CREDENTIALS_FILE or defaulting typically to ‘~/.aws/credentials’ (or another OS-specific location), using the profile specified by AWS_PROFILE

8. the default profile in that global credentials file

If AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables are not present when the package is loaded, then use_credentials is invoked using the file specified in AWS_SHARED_CREDENTIALS_FILE (or another default location) and the profile specified in AWS_PROFILE (or, if missing, the “default” profile).

To use this (and any cloudyr package) on AWS EC2 instances, users will also need to install the aws.ec2metadata package, which allows locate_credentials to know it is running in an instance and check for relevant values. If this package is not installed, instance metadata is not checked.

Because region is often handled slightly differently from credentials and is required for most requests (whereas some services allow anonymous requests without specifying credentials), the value of region is searched for in the same order as the above but lacking a value there fails safe with the following preference ranking of possible region values (regardless of location of other credentials):

1. a user-supplied value

2. the AWS_DEFAULT_REGION environment variable

3. (only on EC2 instances) a region declared in the instance metadata

4. (if a credentials file is being used) the value specified therein

5. the default value specified in default_region (i.e., “us-east-1” - this can be overriden with the option “cloudyr.aws.default_region”)

As such, user-supplied values of region always trump any other value.

See Also

signature_v4, signature_v2_auth, use_credentials