com.amazonaws.auth

Class STSSessionCredentialsProvider

java.lang.Object

com.amazonaws.auth.STSSessionCredentialsProvider

All Implemented Interfaces:

AWSCredentialsProvider, AWSSessionCredentialsProvider, Closeable, AutoCloseable

@ThreadSafe
public class STSSessionCredentialsProvider
extends Object
implements AWSSessionCredentialsProvider, Closeable

AWSCredentialsProvider implementation that uses the AWS Security Token Service to create temporary, short-lived sessions to use for authentication. This credentials provider uses a background thread to refresh credentials. This background thread can be shut down via the close() method when the credentials provider is no longer used.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_DURATION_SECONDS Default duration for started sessions

Constructor Summary

Constructors

Constructor and Description
STSSessionCredentialsProvider(AWSCredentials longLivedCredentials) Constructs a new STSSessionCredentialsProvider, which will use the specified long lived AWS credentials to make a request to the AWS Security Token Service (STS) to request short lived session credentials, which will then be returned by this class's getCredentials() method.
STSSessionCredentialsProvider(AWSCredentials longLivedCredentials, ClientConfiguration clientConfiguration) Constructs a new STSSessionCredentialsProvider, which will use the specified long lived AWS credentials to make a request to the AWS Security Token Service (STS) to request short lived session credentials, which will then be returned by this class's getCredentials() method.
STSSessionCredentialsProvider(AWSCredentialsProvider longLivedCredentialsProvider) Constructs a new STSSessionCredentialsProvider, which will use the specified credentials provider (which vends long lived AWS credentials) to make a request to the AWS Security Token Service (STS) to request short lived session credentials, which will then be returned by this class's getCredentials() method.
STSSessionCredentialsProvider(AWSCredentialsProvider longLivedCredentialsProvider, ClientConfiguration clientConfiguration) Constructs a new STSSessionCredentialsProvider, which will use the specified credentials provider (which vends long lived AWS credentials) to make a request to the AWS Security Token Service (STS) to request short lived session credentials, which will then be returned by this class's getCredentials() method.
STSSessionCredentialsProvider(AWSSecurityTokenService sts) Constructs a new STSSessionCredentialsProvider with the alredy configured STS client.

Method Summary

Modifier and Type	Method and Description
void	close() Shut down this credentials provider, shutting down the thread that performs asynchronous credential refreshing.
AWSSessionCredentials	getCredentials() Method will return valid session credentials or throw an AmazonClientException due to STS service time-out or thread interruption.
void	refresh() Force refresh of session credentials.
void	setSTSClientEndpoint(String endpoint) Deprecated. This method may be removed in a future major version. Create multiple providers if you need to work with multiple STS endpoints.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_DURATION_SECONDS

public static final int DEFAULT_DURATION_SECONDS

Default duration for started sessions

See Also:

Constant Field Values

Constructor Detail

STSSessionCredentialsProvider

public STSSessionCredentialsProvider(AWSCredentials longLivedCredentials)

Constructs a new STSSessionCredentialsProvider, which will use the specified long lived AWS credentials to make a request to the AWS Security Token Service (STS) to request short lived session credentials, which will then be returned by this class's getCredentials() method.

Parameters:

longLivedCredentials - The main AWS credentials for a user's account.

STSSessionCredentialsProvider

public STSSessionCredentialsProvider(AWSCredentials longLivedCredentials,
                                     ClientConfiguration clientConfiguration)

Constructs a new STSSessionCredentialsProvider, which will use the specified long lived AWS credentials to make a request to the AWS Security Token Service (STS) to request short lived session credentials, which will then be returned by this class's getCredentials() method.

Parameters:

longLivedCredentials - The main AWS credentials for a user's account.

clientConfiguration - Client configuration connection parameters.

STSSessionCredentialsProvider

public STSSessionCredentialsProvider(AWSCredentialsProvider longLivedCredentialsProvider)

Constructs a new STSSessionCredentialsProvider, which will use the specified credentials provider (which vends long lived AWS credentials) to make a request to the AWS Security Token Service (STS) to request short lived session credentials, which will then be returned by this class's getCredentials() method.

Parameters:

longLivedCredentialsProvider - Credentials provider for the main AWS credentials for a user's account.

STSSessionCredentialsProvider

public STSSessionCredentialsProvider(AWSCredentialsProvider longLivedCredentialsProvider,
                                     ClientConfiguration clientConfiguration)

Constructs a new STSSessionCredentialsProvider, which will use the specified credentials provider (which vends long lived AWS credentials) to make a request to the AWS Security Token Service (STS) to request short lived session credentials, which will then be returned by this class's getCredentials() method.

Parameters:

longLivedCredentialsProvider - Credentials provider for the main AWS credentials for a user's account.

clientConfiguration - Client configuration connection parameters.

STSSessionCredentialsProvider

public STSSessionCredentialsProvider(AWSSecurityTokenService sts)

Constructs a new STSSessionCredentialsProvider with the alredy configured STS client.

Parameters:

sts - Preconfigured STS client to use for this provider

Method Detail

setSTSClientEndpoint

@Deprecated
public void setSTSClientEndpoint(String endpoint)

Deprecated. This method may be removed in a future major version. Create multiple providers if you need to work with multiple STS endpoints.

Sets the AWS Security Token Service (STS) endpoint where session credentials are retrieved from.

The default AWS Security Token Service (STS) endpoint ("sts.amazonaws.com") works for all accounts that are not for China (Beijing) region or GovCloud. You only need to change the endpoint to "sts.cn-north-1.amazonaws.com.cn" when you are requesting session credentials for services in China(Beijing) region or "sts.us-gov-west-1.amazonaws.com" for GovCloud.

Setting this invalidates existing session credentials. Calling this method will temporarily cause getCredentials() to block until a new session is fetched from the STS service.

getCredentials

public AWSSessionCredentials getCredentials()

Method will return valid session credentials or throw an AmazonClientException due to STS service time-out or thread interruption. The first call will block until valid session credentials are fetched. Subsequent calls will re-use fetched credentials that are still valid. Expiring credentials are automatically refreshed via a background thread. Multiple threads may call this method concurrently without causing simultaneous network calls to the STS service. Care has been taken to resist Throttling exceptions.

Specified by:

getCredentials in interface AWSCredentialsProvider

Specified by:

getCredentials in interface AWSSessionCredentialsProvider

Returns:

AWSCredentials which the caller can use to authorize an AWS request.

refresh

public void refresh()

Force refresh of session credentials. A decision to use this method should be made judiciously since this class automatically manages refreshing expiring credentials limiting its usefulness. Calling this method may temporarily cause getCredentials() to block until a new session is fetched from the STS service.

Specified by:

refresh in interface AWSCredentialsProvider

close

public void close()

Shut down this credentials provider, shutting down the thread that performs asynchronous credential refreshing. This should not be invoked if the credentials provider is still in use by an AWS client.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable