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 AWS CLI or AWS API requests. This is preferable to storing access keys within the EC2 instance. To assign an AWS 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 AWS 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 AWS.

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:

IMDSv2 is a more secure approach than IMDSv1.

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, AWS 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.

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.