Skip to content

Latest commit

 

History

History
630 lines (443 loc) · 20.8 KB

credentials.md

File metadata and controls

630 lines (443 loc) · 20.8 KB
Raw

Setting Credentials and Region

Set credentials

In order to use AWS APIs, you must provide your credentials.

Below are examples of how to set your credentials for common scenarios. For a reference to all available options, see the reference section.

Set credentials for all services with environment variables

You can set credentials for all services using environment variables. Paws will look for credentials in both OS or R environment variables.

You can use R to set credentials with the following command:

Sys.setenv(
    AWS_ACCESS_KEY_ID = "your AWS access key",
    AWS_SECRET_ACCESS_KEY = "your AWS secret key"
)

If you have a session token from temporary security credentials, you can set it and its expiration time in environment variables AWS_SESSION_TOKEN and AWS_CREDENTIAL_EXPIRATION (optional):

Sys.setenv(
    AWS_ACCESS_KEY_ID = "your AWS access key",
    AWS_SECRET_ACCESS_KEY = "your AWS secret key",
    AWS_SESSION_TOKEN = "your session token",
    AWS_CREDENTIAL_EXPIRATION = "ISO 8601 expiration time"
)

AWS_CREDENTIAL_EXPIRATION must be an ISO 8601 formatted date string. If AWS_CREDENTIAL_EXPIRATION is not provided (i.e., only the temporary values for AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN are provided), then the expiration time is assumed to be Inf.

Get credentials from the AWS shared credentials file

You can set credentials for all services using the AWS shared credentials file in ~/.aws/credentials.

The credentials file should be in INI format and should look like:

[my-profile]
aws_access_key_id=your AWS access key
aws_secret_access_key=your AWS secret key

If you put these settings in a profile other than default, you will need to specify which profile to use; see set profile.

You can specify another location for the AWS shared credentials file using environment variable AWS_SHARED_CREDENTIALS_FILE.

Set credentials for an individual service

You can set credentials for an individual service by specifying them as arguments when you create the service object. These take precedence over credentials set using any other method.

svc <- paws::svc(
    config = list(
        credentials = list(
            creds = list(
                access_key_id = "your AWS access key",
                secret_access_key = "your AWS secret key"
            )
        )
    )
)

As of paws.common (>= 0.5.8) 3 new helper functions have been added to help set credentials for an individual service (config, credentials and creds). These new helper functions aim to provide auto-complete functionality to aid the construction of config list.

# paws.common (>= 0.5.8)
library(paws.common)
svc <- paws::svc(
  config(
    credentials(
      creds(
        access_key_id = "your AWS access key",
        secret_access_key = "your AWS secret key"
      )
    )
  )
)

In this example, paws::svc is a placeholder for an AWS service. Use a specific service instead, for example, paws::s3. Paws supports having multiple service objects with different credentials.

If you have a session token from temporary security credentials, you can provide it and its expiration time to session_token and expiration:

svc <- paws::svc(
    config = list(
        credentials = list(
            creds = list(
                access_key_id = "your AWS access key",
                secret_access_key = "your AWS secret key",
                session_token = "your session token",
                expiration = as.POSIXct("2001-02-03 04:05:06")
            )
        )
    )
)

Alternatively:

# paws.common (>= 0.5.8)
library(paws.common)
svc <- paws::svc(
  config(
    credentials(
      creds(
        access_key_id = "your AWS access key",
        secret_access_key = "your AWS secret key",
        session_token = "your session token",
        expiration = as.POSIXct("2001-02-03 04:05:06")
      )
    )
  )
)

expiration must be a POSIXct date-time or able to be compared with them.

Additionally, anonymous credentials may be used (e.g., before calling assume_role_with_web_identity() on an STS service)

svc <- paws::svc(config = list(credentials = list(anonymous = TRUE)))

Alternatively:

# paws.common (>= 0.5.8)
library(paws.common)
svc <- paws::svc(config(credentials(anonymous = TRUE)))

Get credentials from an EC2 instance or container role

If you are running R on an EC2 instance or in a container on AWS (ECS or EKS) with an attached IAM role, Paws will automatically use the credentials from the attached role.

Get credentials from a command line process

You can get credentials from a command line process by specifying the process to run in credential_process in the AWS config file.

[profile my-profile]
credential_process=/opt/aws/get_credentials

The credential process is a command that must return JSON output that looks like the following:

{
  "Version": 1,
  "AccessKeyId": "your AWS access key",
  "SecretAccessKey": "your AWS secret access key",
  "SessionToken": "your session token",
  "Expiration": "ISO8601 expiration time"
}

If you put this setting in a config profile other than default, you will need to specify which profile to use; see set profile.

The default location for the AWS config file is ~/.aws/config. You can specify another location using environment variable AWS_CONFIG_FILE.

Assume a role with credentials from the environment or an instance/container role

You can assume a role, using initial credentials provided by environment variables or by an EC2 instance or container role. To do this, specify in the AWS config file the role to assume in role_arn and the source of the credentials in credential_source.

[profile my-profile]
role_arn=arn:aws:iam::123456789012:role/my-role-name
credential_source=Environment

credential_source can have one of three values:

  • Environment – Specifies that the SDK is to retrieve source credentials from environment variables.

  • Ec2InstanceMetadata – Specifies that the SDK is to use the IAM role attached to the EC2 instance profile to get source credentials.

  • EcsContainer – Specifies that the SDK is to use the IAM role attached to the ECS container as source credentials.

If you put these settings in a config profile other than default, you will need to specify which profile to use; see set profile.

The default location for the AWS config file is ~/.aws/config. You can specify another location using environment variable AWS_CONFIG_FILE.

Assume a role with credentials from another profile

You can assume a role, using initial credentials provided by another profile. To do this, specify in the AWS config file the role to assume in role_arn and the name of the other profile in source_profile.

[profile my-profile]
role_arn=arn:aws:iam::123456789012:role/my-role-name
source_profile=my-other-profile

Paws will look in both the AWS shared credentials file and the AWS config file for the source profile. The source profile can use any method to provide credentials.

If you put these settings in a config profile other than default, you will need to specify which profile to use; see set profile.

The default location for the AWS config file is ~/.aws/config. You can specify another location using environment variable AWS_CONFIG_FILE.

Use multifactor authentication when assuming a role

To use multifactor authentication (MFA) when assuming a role, specify in the AWS config file the MFA serial number in mfa_serial. When assuming the role, Paws will prompt you to enter your MFA token code.

An example specifying MFA along with source_profile is below.

[profile my-profile]
role_arn=arn:aws:iam::123456789012:role/my-role-name
source_profile=my-other-profile
mfa_serial=arn:aws:iam::123456789012:mfa/my-user-name

With multifactor authentication, Paws will ask you to re-enter your MFA token code whenever it has to refresh your credentials (currently, after one hour).

If you put these settings in a config profile other than default, you will need to specify which profile to use; see set profile.

The default location for the AWS config file is ~/.aws/config. You can specify another location using environment variable AWS_CONFIG_FILE.

Use AWS Single Sign-On (SSO)

NOTE: Currently, you must have the AWS CLI installed to use AWS SSO with Paws.

To use AWS SSO to provide credentials for accessing AWS, you will need to specify the SSO settings to use in the AWS config file, log in to SSO using the AWS CLI, then tell Paws to use the profile.

  1. Specify the SSO settings to use in the AWS config file in ~/.aws/config, e.g.

    [profile my-dev-profile]
sso_start_url = https://my-sso-portal.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789011
sso_role_name = readOnly
region = us-west-2
output = json

  2. Log in to SSO using the AWS CLI.

    aws sso login --profile my-dev-profile

  3. Tell Paws to use the SSO profile. For alternate ways of specifying your profile, see the set profile section.

    Sys.setenv(AWS_PROFILE = "my-dev-profile")

See also AWS's documentation about using the AWS CLI with SSO.

Set region

To use AWS, you must also set your AWS region. See below for common scenarios. For a reference to all available options, see the reference section.

Set region for all services with an environment variable

You can set the region for all services using an environment variable. Paws will look for region in both OS or R environment variables using either AWS_REGION or AWS_DEFAULT_REGION.

You can use R to set region with the following command:

Sys.setenv(
    AWS_REGION = "us-east-2"
)
# or
Sys.setenv(
    AWS_DEFAULT_REGION = "us-east-2"
)

Get region from the AWS config file

You can set the region using the AWS config file in ~/.aws/config.

[profile my-profile]
region=us-east-2

If you put these settings in a config profile other than default, you will need to specify which profile to use; see set profile.

The default location for the AWS config file is ~/.aws/config. You can specify another location using environment variable AWS_CONFIG_FILE.

Set region for an individual service

You can set region for an individual service by specifying it as an argument when you create the service object. This take precedence over region set using any other method.

svc <- paws::svc(
    config = list(
        region = "us-east-2"
    )
)

In this example, paws::svc is a placeholder for an AWS service. Use a specific service instead, for example, paws::s3. Paws supports having multiple service objects with different regions.

Set profile

You can store different settings together under different profiles in the AWS shared credentials and config files.

If you do not specify a profile to use, Paws will use the default profile.

You can specify a different profile to use using the AWS_PROFILE environment variable:

Sys.setenv(
    AWS_PROFILE = "my-profile"
)

Or using the profile parameter to an individual service:

svc <- paws::svc(
    config = list(
        credentials = list(
            profile = "your profile"
        )
    )
)

In the AWS shared credentials, a separate profile looks like the following:

[default]
aws_access_key_id=default AWS access key
aws_secret_access_key=default AWS secret key

[my-profile]
aws_access_key_id=my-profile AWS access key
aws_secret_access_key=my-profile AWS secret key

And in the AWS config file, it looks like the following. Note that in the config file, profile names other than default begin with profile.

[default]
region=us-east-1

[profile my-profile]
region=us-east-2

Reference

Credential and option locations and priority

Credentials and options can be set in the following locations. Paws will check them in this order:

  1. In settings provided to an individual service
  2. In environment variables
  3. In the AWS shared credentials file and AWS config file
  4. In an EC2 instance or container IAM role

This means that, for example, a service setting will take precedence over an environment variable, and an environment variable will take precedence over a setting in a config file.

Service settings

Paws supports the following settings provided as arguments to a service:

  • access_key_id - Specifies the AWS access key used as part of the credentials to authenticate the request.

  • secret_access_key - Specifies the AWS secret key used as part of the credentials to authenticate the request.

  • session_token - Specifies the session token value that is required if you are using temporary security credentials that you retrieved directly from AWS STS operations.

  • expiration - The expiration time of the credentials contained in the parameters access_key_id, secret_access_key, and session_token. The expiration time must be a date-time, e.g. as.POSIXct("2001-02-03 04:05:06").

  • profile - Specifies the name of the profile with the credentials and options to use.

  • region - Specifies the AWS region to send the request to.

They must be provided to the service in the following structure. It is allowable to specify only some of the settings, e.g. only region.

svc <- paws::svc(
    config = list(
        credentials = list(
            creds = list(
                access_key_id = "your AWS access key",
                secret_access_key = "your AWS secret key",
                session_token = "your session token",
                expiration = as.POSIXct("2001-02-03 04:05:06")
            ),
            profile = "your profile"
        ),
        region = "your region"
    )
)

Environment variables

Paws supports the following settings in environment variables.

  • AWS_ACCESS_KEY_ID - Specifies the AWS access key used as part of the credentials to authenticate the request.

  • AWS_CONFIG_FILE - Specifies the location of the file used to store configuration profiles. The default path is ~/.aws/config.

  • AWS_CREDENTIAL_EXPIRATION - The expiration time of the credentials contained in the environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN. The expiration time must be specified in ISO 8601 format, e.g. "2021-02-19T04:42:29Z".

  • AWS_EC2_METADATA_DISABLED - Disables the use of the Amazon EC2 instance metadata service (IMDS) when set to "true" (case insensitive) or "1".

  • AWS_PROFILE - Specifies the name of the profile with the credentials and options to use.

  • AWS_REGION/AWS_DEFAULT_REGION - Specifies the AWS region to send the request to.

  • AWS_SECRET_ACCESS_KEY - Specifies the AWS secret key used as part of the credentials to authenticate the request.

  • AWS_SESSION_TOKEN - Specifies the session token value that is required if you are using temporary security credentials that you retrieved directly from AWS STS operations.

  • AWS_SHARED_CREDENTIALS_FILES - Specifies the location of the file used to store access keys. The default path is ~/.aws/credentials.

  • AWS_ENDPOINT_URL- Set global endpoint URL.

  • AWS_ENDPOINT_URL_<SERVICE> - Service-specific endpoints: List of service-specific identifiers

Shared credentials file

The default location for the AWS shared credentials file is ~/.aws/credentials. You can specify another location using environment variable AWS_SHARED_CREDENTIALS_FILE.

Paws supports the following settings in the AWS shared credentials file.

  • aws_access_key_id - Specifies the AWS access key used as part of the credentials to authenticate the request.

  • aws_secret_access_key - Specifies the AWS secret key used as part of the credentials to authenticate the request.

Config file

The default location for the AWS config file is ~/.aws/config. You can specify another location using environment variable AWS_CONFIG_FILE.

Paws supports the following settings in the AWS config file.

  • credential_process - Specifies an external command to be run to generate or retrieve authentication credentials. The command must return the credentials in a specific format. For more information about how to use this setting, see Sourcing credentials with an external process.

  • credential_source - Used within Amazon EC2 instances or EC2 containers to specify where the SDK can find credentials to use to assume the role you specified with the role_arn parameter. You cannot specify both source_profile and credential_source in the same profile.

    This parameter can have one of three values:

    • Environment – Specifies that the SDK is to retrieve source credentials from environment variables.

    • Ec2InstanceMetadata – Specifies that the SDK is to use the IAM role attached to the EC2 instance profile to get source credentials.

    • EcsContainer – Specifies that the SDK is to use the IAM role attached to the ECS container as source credentials.

  • mfa_serial - The identification number of an MFA device to use when assuming a role. This is mandatory only if the trust policy of the role being assumed includes a condition that requires MFA authentication. The value can be either a serial number for a hardware device (such as GAHT12345678) or an Amazon Resource Name (ARN) for a virtual MFA device (such as arn:aws:iam::123456789012:mfa/user).

  • region - Specifies the AWS Region to send requests to for commands requested using this profile.

  • role_arn - Specifies the Amazon Resource Name (ARN) of an IAM role that you want to use to run SDK commands. You must also specify one of the following parameters to identify the credentials that have permission to assume this role: source_profile, credential_source.

  • source_profile - Specifies a named profile with long-term credentials that the SDK can use to assume a role that you specified with the role_arn parameter. You cannot specify both source_profile and credential_source in the same profile.

  • endpoint_url - Global endpoint for all AWS Services Use endpoints

  • services - Service-specific endpoint configuration provides the option to use a persistent endpoint of your choosing set service-specific endpoints. Service-specific endpoints: List of service-specific identifiers.