Using credentials
To make requests to Amazon Web Services using the AWS SDK for Java 2.x, you must use cryptographically-signed credentials issued by AWS. You can use programmatic access keys or temporary security credentials such as AWS IAM Identity Center (successor to AWS Single Sign-On) or IAM roles to grant access to AWS resources.
For information on setting up credentials, see Set default credentials and Region and Set up credentials profiles.
Topics
Use the default credential provider chain
After you set default credentials and Region for your environment, the SDK for Java will automatically use those credentials when your application makes requests to AWS. The default credential provider chain, implemented by the DefaultCredentialsProvider class, checks sequentially each of places where you can set default credentials and selects the first one you set.
To use the default credential provider chain to supply credentials in your application, create a service client builder without specifying credentials provider configuration.
Region region = Region.US_WEST_2; DynamoDbClient ddb = DynamoDbClient.builder() .region(region) .build();
Credential retrieval order
The default credential provider chain of the SDK for Java 2.x searches for credentials in your environment using a predefined sequence.
-
Java system properties
-
The SDK uses the SystemPropertyCredentialsProvider class to load credentials from the
aws.accessKeyId
andaws.secretAccessKey
Java system properties. Ifaws.sessionToken
is also specified, the SDK will use temporary credentials.Note For information on how to set Java system properties, see the System Properties
tutorial on the official Java Tutorials website.
-
-
Environment variables
-
The SDK uses the EnvironmentVariableCredentialsProvider class to load credentials from the
AWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
system environment variables. IfAWS_SESSION_TOKEN
is also specified, the SDK will use temporary credentials.
-
-
Web identity token from AWS Security Token Service
-
The SDK uses the WebIdentityTokenFileCredentialsProvider class to load credentials from Java system properties or environment variables.
-
-
The shared
credentials
andconfig
files-
The SDK uses the ProfileCredentialsProvider to load credentials from the
[default]
credentials profile in the sharedcredentials
andconfig
files.Note The
credentials
andconfig
files are shared by various AWS SDKs and Tools. For more information, see The .aws/credentials and .aws/config files in the AWS SDKs and Tools Reference Guide.
-
-
Amazon ECS container credentials
-
The SDK uses the ContainerCredentialsProvider
class to load credentials from the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
system environment variable.
-
-
Amazon EC2 instance profile credentials
-
The SDK uses the InstanceProfileCredentialsProvider class to load credentials from the Amazon EC2 metadata service.
-
Use a specific credentials provider or provider chain
As an alternative to the default credential provider chain, you can specify which
credentials provider the SDK should use. For example, if you set your default credentials
using environment variables, supply an EnvironmentVariableCredentialsProvider object to the
credentialsProvider
method on the service client builder, as in the
following code snippet.
Region region = Region.US_WEST_2; DynamoDbClient ddb = DynamoDbClient.builder() .region(region) .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .build();
For a complete list of credential providers and provider chains, see All Known Implementing Classes in AwsCredentialsProvider.
You can use your own credential provider or provider chains by implementing the
AwsCredentialsProvider
interface.
Use credentials profiles
Using the shared credentials
file, you can set up custom profiles which enables you to
use multiple sets of credentials in your application. The [default]
profile was mentioned above.
The SDK uses the
ProfileCredentialsProvider
class to load credentials from profiles defined in the shared credentials
file.
For information on how to set up custom profiles, see Set up credentials profiles.
The following code snippet demonstrates how to build a service client that uses the
credentials defined as part of the profile named my_profile
.
Region region = Region.US_WEST_2; DynamoDbClient ddb = DynamoDbClient.builder() .region(region) .credentialsProvider(ProfileCredentialsProvider.create("my_profile")) .build();
Set a different profile as the default
To set a profile other than the [default]
profile as the default for your application, set the
AWS_PROFILE
environment variable to the name of your custom profile.
To set this variable on Linux, macOS, or Unix, use export
:
export AWS_PROFILE="other_profile"
To set these variables on Windows, use set
:
set AWS_PROFILE="other_profile"
Alternatively, set the aws.profile
Java system property to the name of the profile.
Load credentials from an external process
The following describes a method of sourcing credentials from an external process.
This can potentially be dangerous, so proceed with caution. Other credential providers
should be preferred if at all possible. If using this option, you should make sure that
the config
file is as locked down as possible using security best practices
for your operating system.
Ensure that your custom credential tool does not write any secret information to
StdErr
because the SDKs and CLI can capture and log such information,
potentially exposing it to unauthorized users.
The SDK for Java 2.x allows you to acquire credentials from an external process for custom use cases. There are two ways to configure this functionality.
Use the credential_process
setting
If you have a method that provides credentials, you can integrate it by adding the
credential_process
setting as part of a profile definition in the
config
file. The value you specify must use the full path to the command
file and surround the file path with quotation marks if it contains any spaces.
The SDK will call the command exactly as given and then read JSON data from
stdout
.
The following examples show the use of this setting for file paths that have no spaces and for file paths that do contain spaces.
The following code snippet demonstrates how to build a service client that uses the
credentials defined as part of the profile named
process-credential-profile
.
Region region = Region.US_WEST_2; S3Client s3Client = S3Client.builder() .region(region) .credentialsProvider(ProfileCredentialsProvider.create("process-credential-profile")) .build();
For detailed information about using an external processes as a source of credentials, refer to the process credentials section in the AWS SDKs and Tools Reference Guide.
Use the
ProcessCredentialsProvider
As an alternative to using settings in the config
file, you can use the
SDK's ProcessCredentialsProvider
to load credentials using Java.
The following examples show various versions of how to specify an external process
using the ProcessCredentialsProvider
and configuring a service client that
uses the credentials.
Supply credentials explicitly
If the default credential chain or a specific or custom provider or provider chain doesn’t work for your application, you can supply the credentials that you want directly in code. These can be AWS account credentials, IAM credentials, or temporary credentials retrieved from AWS Security Token Service (AWS STS). If you’ve retrieved temporary credentials using AWS STS, use this method to specify the credentials for AWS access.
For security, use IAM account credentials instead of the AWS account credentials when accessing AWS. For more information, see AWS Security Credentials in the Amazon Web Services General Reference.
-
Instantiate a class that provides the AwsCredentials interface, such as AwsSessionCredentials. Supply it with the AWS access key and secret key to use for the connection.
-
Create a StaticCredentialsProvider object and supply it with the
AwsCredentials
object. -
Configure the service client builder with the
StaticCredentialsProvider
and build the client.
The following example creates a new service client using credentials that you supply:
AwsBasicCredentials awsCreds = AwsBasicCredentials.create( "your_access_key_id", "your_secret_access_key"); S3Client s3 = S3Client.builder() .credentialsProvider(StaticCredentialsProvider.create(awsCreds)) .build();