In this step, you create the profiles that allow users to use MFA when accessing AWS services.
The profiles that you create include three pieces of information that you've copied and stored during the previous steps:
• Access keys (access key ID and secret access key) for the IAM user
• ARN of the role that's delegating permissions to the IAM user
• ARN of the virtual MFA device that's assigned to the IAM user
In the shared AWS config and credentials files or SDK Store that contain your AWS credentials, add the following entries:
[my-user]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY [mfa]
source_profile = my-user
role_arn = arn:aws:iam::111111111111:role/my-role
IAM roles for Amazon EC2 instances
mfa_serial = arn:aws:iam::111111111111:mfa/my-user
There are two profiles defined in the example provided:
• [my-user] profile includes the access key and secret access key that were generated and saved when you created the IAM user in Step 2.
• Details on using these two settings can be found at Static credentials (p. 33).
• [mfa] profile defines how multi-factor authentication is supported. There are three entries:
• source_profile: Specifies the profile whose credentials are used to assume the role specified by this role_arn setting in this profile. In this case, it's the my-user profile.
• role_arn: Specifies the Amazon Resource Name (ARN) of the IAM role that you want to use to perform operations requested using this profile. In this case, it's the ARN for the role you created in Step 1.
• mfa_serial: Specifies the identification or serial number of the MFA device that the user must use when assuming a role. In this case, it's the ARN of the virtual device you set up in Step 3.
• Details on using these three settings can be found at Assume role credentials (p. 23).
Using IAM roles for Amazon EC2 instances
This example covers setting up and IAM role with Amazon S3 access to use in your application deployed to an Amazon EC2 instance.
Create an IAM role
Create an IAM role that grants read-only access to Amazon S3.
1. Open the IAM console.
2. In the navigation pane, choose Roles, then Create New Role.
3. On the Select Role Type page, under AWS-service Roles, choose Amazon EC2.
4. On the Attach Policy page, choose Amazon S3 Read Only Access from the policy list, then choose Next Step. Enter a name for the role, then select Next Step. Remember this name because you'll need it when you launch your Amazon EC2 instance.
5. On the Review page, choose Create Role.
Launch an Amazon EC2 instance and specify your IAM role
You can launch an Amazon EC2 instance with an IAM role using the Amazon EC2 console.
Follow the directions to launch an instance in the Amazon EC2 User Guide for Linux Instances or the Amazon EC2 User Guide for Windows Instances.
When you reach the Review Instance Launch page, select Edit instance details. In IAM role, choose the IAM role that you created previously. Complete the procedure as directed.
Note
You need to create or use an existing security group and key pair to connect to the instance.
With this IAM and Amazon EC2 setup, you can deploy your application to the Amazon EC2 instance and it will have read access to the Amazon S3 service.
Connect to the EC2 instance
Connect to the EC2 instance
Connect to the EC2 instance so that you can transfer the sample application to it and then run the application. You'll need the file that contains the private portion of the key pair you used to launch the instance; that is, the PEM file.
You can do this by following the connect procedure in the Amazon EC2 User Guide for Linux Instances or the Amazon EC2 User Guide for Windows Instances. When you connect, do so in such a way that you can transfer files from your development machine to your instance.
If you're using an AWS Toolkit, you can often also connect to the instance by using the Toolkit. For more information, see the specific user guide for the Toolkit you use.
Run the sample application on the EC2 instance
1. Copy the application files from your local drive to your instance.
For information about how to transfer files to your instance see the Amazon EC2 User Guide for Linux Instances or the Amazon EC2 User Guide for Windows Instances.
2. Start the application and verify that it runs with the same results as on your development machine.
3. (Optional) Verify that the application uses the credentials provided by the IAM role.
a. Open the Amazon EC2 console.
b. Select the instance and detach the IAM role through Actions, Instance Settings, Attach/
Replace IAM Role.
c. Run the application again and confirm that it returns an authorization error.
Using an IAM role assumed as an IAM user
This example shows how to configure the shared AWS config and credentials files to support logging in to an AWS SDK or developer tool using an IAM role. The SDK or tool assumes the role using the credentials of a separate IAM user.
Scenario description
This scenario requires that you have two entities created in IAM:
• An IAM user, that in this example we call UserAlpha. This user has IAM policy permissions that enable it to perform only the sts:AssumeRole operation. The following JSON policy document describes this user in IAM policy language. To better understand the components of IAM policy language, see IAM JSON policy elements reference in the IAM User Guide. However, when getting started, it is far more common to simply use the AWS Management Console to graphically create users, roles, etc.
rather than writing them manually.
{
"Version": "2012-10-17", "Statement": [
How to configure the profile
• An IAM role, that in this example we call RoleBeta. This role has a trust policy that enables all users in the account to assume the role.
{ "Version": "2012-10-17", "Statement": [
{
"Effect": "Allow", "Principal": {
"AWS": "arn:aws:iam::231179739868:root"
},
"Action": "sts:AssumeRole", "Condition": {}
} ] }
It also has IAM permission policies that enable it to perform any task in Amazon S3. When getting started, it is far more common to simply use the AWS Management Console and assign AWS managed policies.
{ "Version": "2012-10-17", "Statement": [
How to configure the profile
The following example shared AWS config file and shared AWS credentials file files show how you can configure SDK or AWS developer tool access using RoleBeta.
Contents of shared config file [profile UserAlpha]
Contents of shared credentials file
[UserAlpha]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
How to use the profile
As an example, you can run the following AWS CLI command to list the Amazon S3 buckets available in the account. The AWS CLI sees that RoleBeta profile references the source_profile UserAlpha. It
How to use the profile
looks up UserAlpha's access key and secret key, and uses them to call the sts:AssumeRole operation on the ARN of RoleBeta. That operation returns short-term credentials for RoleBeta that the AWS CLI uses to call the s3:ListBuckets operation.
$ aws s3api list-buckets --profile RoleBeta { "Buckets": [
{
"Name": "my-first-bucket",
"CreationDate": "2018-08-31T07:46:02+00:00"
}, {
"Name": "my-second-bucket",
"CreationDate": "2019-09-17T19:17:31+00:00"
}, {
"Name": "my-third-bucket",
"CreationDate": "2018-06-12T23:18:08+00:00"
} ],
"Owner": { ...truncated... } }
Creating service clients
Configuration and authentication settings reference
• Standardized credential providers (p. 22) – Common credential providers standardized across multiple SDKs.
• Standardized features (p. 34) – Common features standardized across multiple SDKs.
SDKs provide language-specific APIs for AWS services. They take care of some of the heavy lifting necessary in successfully making API calls, including authentication, retry behavior, and more. To do this, the SDKs have flexible strategies to obtain credentials to use for your requests, to maintain settings to use with each service, and to obtain values to use for global settings.
Creating service clients
To programmatically access AWS services, SDKs use a client class/object for each AWS service. For example, if your application needs to access Amazon EC2, your application creates an Amazon EC2 client object to interface with that service. You then use the service client to make requests to that AWS service. A service client object is immutable, so you must create a new client for each service to which you make requests and for making requests to the same service using a different configuration.
Precedence of settings
Global settings configure features, credential providers, and other functionality that are supported by most SDKs and have a broad impact across AWS services. All SDKs have a series of places (or sources) that they check in order to find a value for global settings. The following is the setting lookup precedence:
1. Any explicit setting set in the code or on a service client itself takes precedence over anything else.
• Some settings can be set on a per-operation basis, and can be changed as needed for each operation that you invoke. For the AWS CLI or AWS Tools for PowerShell, these take the form of per-operation parameters that you enter on the command line. For an SDK, explicit assignments can take the form of a parameter that you set when you instantiate an AWS service client or configuration object, or sometimes when you call an individual API.
2. Java/Kotlin only: Sometimes there is a JVM system property associated with the setting. If it’s set, that value is used to configure the client.
3. The environment variable is checked. If it’s set, that value is used to configure the client.
4. The SDK checks the shared credentials file and then the shared config file. If the setting is present, the SDK uses it. The AWS_PROFILE environment variable or the aws.profile system property can be used to specify which profile that the SDK loads.
5. Any default value provided by the SDK code base is used last.
NoteIf a setting exists in both the config file and the credentials file for the same profile, the value in the credentials file is used instead of the value in the config file.
Config file settings list
NoteSome SDKs and tools might check in a different order. Also, some SDKs and tools support other methods of storing and retrieving parameters. For example, the AWS SDK for .NET supports an additional source called the SDK Store. For more information about providers that are unique to a SDK or tool, see the documentation for that SDK or tool (p. 6).
The order determines which methods take precedence and override others. For example, if you set up a default profile in the shared config file, it's only found and used after the SDK or tool checks the other places first. This means that if you put a setting in the credentials file, it is used instead of one found in the config file. If you configure an environment variable with a setting and value, it would override that setting in both the credentials and config files. And finally, a setting on the individual operation (AWS CLI command-line parameter or API parameter) or in code would override all other values for that one command.
Config file settings list
The settings listed in the following table can be assigned in the shared AWS config file. They are global and affect all AWS services.
Setting name Details
api_versions General configuration settings (p. 43) aws_access_key_id Static credentials (p. 33)
aws_secret_access_keyStatic credentials (p. 33) aws_session_token Static credentials (p. 33)
ca_bundle General configuration settings (p. 43) credential_process Process credentials (p. 29)
credential_source Assume role credentials (p. 23) defaults_mode Smart configuration defaults (p. 49) duration_seconds Assume role credentials (p. 23) ec2_metadata_service_endpointIMDS credentials (p. 28) ec2_metadata_service_endpoint_modeIMDS credentials (p. 28) endpoint_discovery_enabledEndpoint discovery (p. 42) external_id Assume role credentials (p. 23) max_attempts Retry behavior (p. 46)
metadata_service_num_attemptsAmazon EC2 instance metadata (p. 35) metadata_service_timeoutAmazon EC2 instance metadata (p. 35) mfa_serial Assume role credentials (p. 23) parameter_validationGeneral configuration settings (p. 43)
region AWS Region (p. 38)
Credentials file settings list
Setting name Details
retry_mode Retry behavior (p. 46)
role_arn Assume role credentials (p. 23) role_session_name Assume role credentials (p. 23)
s3_disable_multiregion_access_pointsAmazon S3 Multi-Region Access Points (p. 37) s3_use_arn_region Amazon S3 access points (p. 36)
source_profile Assume role credentials (p. 23) sso_account_id SSO credentials (p. 31) sso_region SSO credentials (p. 31) sso_role_name SSO credentials (p. 31) sso_start_url SSO credentials (p. 31)
sts_regional_endpointsSTS regionalized endpoints (p. 40) web_identity_token_fileAssume role credentials (p. 23)
Credentials file settings list
The settings listed in the following table can be assigned in the shared AWS credentials file. They are global and affect all AWS services.
Setting name Details
aws_access_key_id Static credentials (p. 33) aws_secret_access_keyStatic credentials (p. 33) aws_session_token Static credentials (p. 33)
Environment variables list
Environment variables supported by most SDKs are listed in the following table. They are global and affect all AWS services.
Setting name Details
AWS_ACCESS_KEY_ID Static credentials (p. 33)
AWS_CA_BUNDLE General configuration settings (p. 43)
AWS_CONFIG_FILE Location of the shared config and credentials files (p. 5)
AWS_CONTAINER_AUTHORIZATION_TOKENContainer credentials (p. 27)
Standardized credential providers
Setting name Details
AWS_CONTAINER_CREDENTIALS_FULL_URIContainer credentials (p. 27) AWS_CONTAINER_CREDENTIALS_RELATIVE_URIContainer credentials (p. 27) AWS_DEFAULTS_MODE Smart configuration defaults (p. 49) AWS_EC2_METADATA_SERVICE_ENDPOINTIMDS credentials (p. 28)
AWS_EC2_METADATA_SERVICE_ENDPOINT_MODEIMDS credentials (p. 28) AWS_ENABLE_ENDPOINT_DISCOVERYEndpoint discovery (p. 42) AWS_MAX_ATTEMPTS Retry behavior (p. 46)
AWS_METADATA_SERVICE_NUM_ATTEMPTSAmazon EC2 instance metadata (p. 35) AWS_METADATA_SERVICE_TIMEOUTAmazon EC2 instance metadata (p. 35) AWS_PROFILE Shared AWS config and credentials
files (p. 2)
AWS_REGION AWS Region (p. 38)
AWS_RETRY_MODE Retry behavior (p. 46)
AWS_S3_DISABLE_MULTIREGION_ACCESS_POINTSAmazon S3 Multi-Region Access Points (p. 37) AWS_S3_USE_ARN_REGIONAmazon S3 access points (p. 36)
AWS_SECRET_ACCESS_KEYStatic credentials (p. 33) AWS_SESSION_TOKEN Static credentials (p. 33)
AWS_SHARED_CREDENTIALS_FILELocation of the shared config and credentials files (p. 5)
AWS_STS_REGIONAL_ENDPOINTSSTS regionalized endpoints (p. 40)
Standardized credential providers
Many credential providers have been standardized to consistent defaults and to work the same way across many SDKs. This consistency increases productivity and clarity when coding across multiple SDKs.
All settings can be overridden in code. For details, see your specific SDK API.
Important
Not all SDKs support all providers, or even all aspects within a provider.
Topics
• Credential provider chain (p. 23)
• Assume role credentials (p. 23)
• Container credentials (p. 27)
• IMDS credentials (p. 28)
• Process credentials (p. 29)
• SSO credentials (p. 31)
• Static credentials (p. 33)
Credential provider chain
Credential provider chain
All SDKs have a series of places (or sources) that they check in order to find valid credentials to use to make a request to an AWS service. After valid credentials are found, the search is stopped. This systematic search is called the default credential provider chain. Although the distinct chain used by each SDK varies, they most often include sources such as the following:
• Static credentials (such as AWS_ACCESS_KEY_ID). For more information, see Static credentials (p. 33).
• Web identity token from AWS Security Token Service (AWS STS). For more information, see Assume role credentials (p. 23).
• AWS Single Sign-On. For more information, see SSO credentials (p. 31).
• Trusted entity provider (such as AWS_ROLE_ARN). For more information, see Assume role credentials (p. 23).
• Amazon Elastic Container Service (Amazon ECS) credentials. For more information, see Container credentials (p. 27).
• Custom credential provider. For more information, see Process credentials (p. 29).
• Amazon Elastic Compute Cloud (Amazon EC2) instance profile credentials (IMDS credential provider).
For more information, see IMDS credentials (p. 28).
For each step in the chain, there are a variety of ways to assign setting values. Setting values specified in code always take precedence, but there are also Environment variables (p. 7) and the Shared AWS config and credentials files (p. 2). For more information, see Precedence of settings (p. 19).
Assume role credentials
Assuming a role involves using a set of temporary security credentials that you can use to access AWS 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. Typically, you assume a role within your account or for cross-account access.
To learn more about IAM roles, see Using IAM roles in the IAM User Guide.
To learn more about assuming a role, see AssumeRole in the AWS Security Token Service API Reference.
Configure this functionality by using the following:
credential_source - shared AWS config file setting
Used within Amazon EC2 instances or containers to specify where the SDK or development tool can find credentials that have permission to assume the role that you specify with the role_arn parameter.
Default value: None Valid values:
• Environment – Specifies that the SDK or tool is to retrieve source credentials from the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (p. 33).
• Ec2InstanceMetadata – Specifies that the SDK or tool is to use the IAM role attached to the EC2 instance profile to get source credentials.
• EcsContainer – Specifies that the SDK or tool is to use the IAM role attached to the ECS container to get source credentials.
You cannot specify both credential_source and source_profile in the same profile.
Assume role credentials
Example of setting this in a config file to indicate that credentials should be sourced from Amazon EC2:
credential_source = Ec2InstanceMetadata
role_arn = arn:aws:iam::123456789012:role/my-role-name
duration_seconds - shared AWS config file setting
Specifies the maximum duration of the role session, in seconds.
This setting applies only when the profile specifies to assume a role.
Default value: 3600 seconds (one hour)
Valid values: The value can range from 900 seconds (15 minutes) up to the maximum session duration setting configured for the role (which can be a maximum of 43200 seconds, or 12 hours).
For more information, see View the Maximum Session Duration Setting for a Role in the IAM User Guide.
Example of setting this in a config file:
duration_seconds = 43200
external_id - shared AWS config file setting
Specifies a unique identifier that is used by third parties to assume a role in their customers' accounts.
This setting applies only when the profile specifies to assume a role and the trust policy for the role requires a value for ExternalId. The value maps to the ExternalId parameter that is passed to the AssumeRole operation when the profile specifies a role.
Default value: None.
Valid values: See How to use an External ID When Granting Access to Your AWS Resources to a Third Party in the IAM User Guide.
Example of setting this in a config file:
external_id = unique_value_assigned_by_3rd_party
mfa_serial - shared AWS config file setting
Specifies the identification or serial number of a multi-factor authentication (MFA) device that the user must use when assuming a role.
Required when assuming a role where the trust policy for that role includes a condition that requires MFA authentication.
Default value: None.
Valid values: 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. For more information about MFA, see Configuring MFA-Protected API Access in the IAM User Guide.
Example of setting this in a config file:
Assume role credentials
mfa_serial = arn:aws:iam::123456789012:mfa/my-user-name
role_arn - shared AWS config file setting
role_arn - shared AWS config file setting