Using the AWS credentials file and credential Profiles
For reference information on the location and formatting of the shared AWS
config
and credentials
files, see Configuration and Location of the shared AWSconfig
and credentials
files in the
AWS SDKs and Tools Reference Guide.
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. For more details on these configuration settings, see Assume role
credentials in the AWS SDKs and Tools Reference Guide.
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.