Using the AWS Credentials File and Credential Profiles - AWS SDK for PHP
Assume Role with Profile

Using the AWS Credentials File and Credential Profiles

A credentials file is a plaintext file that contains your access keys. The file must:

  • Be on the same machine on which you’re running your application.

  • Be named credentials.

  • Be located in the .aws/ folder in your home directory.

The home directory can vary by operating system. On Windows, you can refer to your home directory by using the environment variable %UserProfile%. On Unix-like systems, you can use the environment variable $HOME or ~ (tilde).

If you already use this file for other SDKs and tools (like the AWS CLI), you don’t need to change anything to use the files in this SDK. If you use different credentials for different tools or applications, you can use profiles to configure multiple access keys in the same configuration file.

We use this method in all our PHP code examples.

Using an AWS credentials file offers the following benefits:

  • Your projects’ credentials are stored outside of your projects, so there is no chance of accidentally committing them into version control.

  • You can define and name multiple sets of credentials in one place.

  • You can easily reuse the same credentials among projects.

  • Other AWS SDKs and tools support, this same credentials file. This allows you to reuse your credentials with other tools.

The format of the AWS credentials file should look something like the following.

[default]
aws_access_key_id = YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = YOUR_AWS_SECRET_ACCESS_KEY

[project1]
aws_access_key_id = ANOTHER_AWS_ACCESS_KEY_ID
aws_secret_access_key = ANOTHER_AWS_SECRET_ACCESS_KEY

Each section (e.g., [default], [project1]), represents a separate credential profile. You can reference profiles from an SDK configuration file, or when you are instantiating a client, by using the profile option.

use Aws\DynamoDb\DynamoDbClient;

// Instantiate a client with the credentials from the project1 profile
$client = new DynamoDbClient([
    'profile' => 'project1',
    'region'  => 'us-west-2',
    'version' => 'latest'
]);

If no credentials or profiles were explicitly provided to the SDK and no credentials were defined in environment variables, but a credentials file is defined, the SDK uses the “default” profile. You can change the default profile by specifying an alternate profile name in the AWS_PROFILE environment variable.

Assume Role with Profile

You can configure the AWS SDK for PHP to use an IAM role by defining a profile for the role in ~/.aws/credentials.

Create a new profile with the role_arn for the role you will assume. Also include the source_profile of a profile with credentials that have permissions to assume the IAM role.

Profile in ~/.aws/credentials:

[default]
aws_access_key_id = YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = YOUR_AWS_SECRET_ACCESS_KEY

[project1]
role_arn = arn:aws:iam::123456789012:role/testing
source_profile = default
role_session_name = OPTIONAL_SESSION_NAME

By setting the AWS_PROFILE environment variable, or profile option when instantiating a client, the role specified in project1 will be assumed, using the default profile as the source credentials.

Roles can also be assumed for profiles defined in ~/.aws/config. Setting the environment variable AWS_SDK_LOAD_NONDEFAULT_CONFIG enables loading profiles for assuming a role from ~/.aws/config. When enabled, profiles from both ~/.aws/config and ~/.aws/credentials will be loaded. Profiles from ~/.aws/credentials are loaded last and will take precedence over a profile from ~/.aws/config with the same name. Profiles from either location can serve as the source_profile or the profile to be assumed.

Profile in ~/.aws/config:

[profile project1]
role_arn = arn:aws:iam::123456789012:role/testing
source_profile = default
role_session_name = OPTIONAL_SESSION_NAME

Profile in ~/.aws/credentials:

[project2]
aws_access_key_id = YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = YOUR_AWS_SECRET_ACCESS_KEY

Using the above files, [project1] will be assumed using [project2] as the source credentials.