Read IAM role credentials on Amazon EC2
You can use an IAM role to manage temporary credentials for applications that are running on an EC2 instance and making Amazon CLI or Amazon API requests. This is preferable to storing access keys within the EC2 instance. To assign an Amazon role to an EC2 instance and make it available to all of its applications, you create an instance profile that is attached to the instance. An instance profile contains the role and enables programs that are running on the EC2 instance to get temporary credentials. For more information, see Use an IAM role to grant permissions to applications running on Amazon EC2 instances in the IAM User Guide.
This topic provides information on how to set up your Java application to run on an EC2 instance and enable the SDK for Java to acquire IAM role credentials.
Acquire IAM role credentials from the environment
If your application creates an Amazon service client by using the
create
method (or builder().build()
methods), the SDK for Java uses
the default credentials provider chain. The default credentials
provider chain searches the execution environment for configuration elements that the SDK
can trade for temporary credentials. The Default credentials provider chain section
describes the full search process.
The final step in the default provider chain is available only when your application
runs on an Amazon EC2 instance. In this step, the SDK uses an
InstanceProfileCredentialsProvider
to read the IAM role defined in the
EC2 instance profile. The SDK then acquires temporary credentials for that IAM
role.
Although these credentials are temporary and would eventually expire, an
InstanceProfileCredentialsProvider
periodically refreshes them for you so
that they continue to allow access to Amazon.
Acquire IAM role credentials programmatically
As an alternative to the default credentials provider chain that eventually uses an
InstanceProfileCredentialsProvider
on EC2, you can configure a service
client explicitly with an InstanceProfileCredentialsProvider
. This approach is
shown in the following snippet.
S3Client s3 = S3Client.builder() .credentialsProvider(InstanceProfileCredentialsProvider.create()) .build();
Securely acquire IAM role credentials
By default, EC2 instances run IMDS (Instance Metadata Service) that allows the SDK's
InstanceProfileCredentialsProvider
to access information such as the IAM
role that has been configured. EC2 instances run two versions of IMDS by default:
-
Instance Metadata Service Version 1 (IMDSv1) – a request/response method
-
Instance Metadata Service Version 2 (IMDSv2) – a session-oriented method
IMDSv2 is a more secure approach
By default, the Java SDK first tries IMDSv2 to get the IAM role, but if that fails, it tries IMDSv1. However, since IMDSv1 is less secure, Amazon recommends the use of IMDSv2 only and to disable the SDK from trying IMDSv1.
To use the more secure approach, disable the SDK from using IMDSv1 by providing one of
the following settings with a value of true
.
-
Environment variable:
AWS_EC2_METADATA_V1_DISABLED
-
JVM system property: aws.
disableEc2MetadataV1
-
Shared config file setting:
ec2_metadata_v1_disabled
With one of these settings set to true
, the SDK does not load IMDS role
credentials by using IMDSv1 if the initial IMDSv2 call fails.