com.amazonaws.auth

Class CognitoCachingCredentialsProvider

java.lang.Object

com.amazonaws.auth.CognitoCredentialsProvider

com.amazonaws.auth.CognitoCachingCredentialsProvider

All Implemented Interfaces:

AWSCredentialsProvider

public class CognitoCachingCredentialsProvider
extends CognitoCredentialsProvider

This credentials provider is intended for Android applications. It offers the ability to persist the Cognito identity id in SharedPreferences. Furthermore, it caches session credentials so as to reduce the number of network requests. This is the provider to use with a custom identity provider, which should be an extension of AWSAbstractCognitoIdentityProvider. This will consume an identity provider, as well. If one is passed in to a constructor, then that one is the one that is consumed, but if not/a constructor that doesn't take an identity provider is used, then the Cognito identity provider is used by default.

Note: if you haven't yet associated your IAM roles with your identity pool, please do so via the Cognito console before using this constructor. You will get an InvalidIdentityPoolConfigurationException if you use it and have not.

 // initiate a credentials provider
 CognitoCachingCredentialsProvider provider = new CognitoCachingCredentialsProvider(
         context,
         "identityPoolId",
         Regions.US_EAST_1);

 // use the provider to instantiate an AWS client
 AmazonSNS snsClient = new AmazonSNSClient(provider);

 // If the user is authenticated through login with Amazon, you can set the map
 // of token to the provider
 Map<String, String> logins = new HashMap<String, String>();
 logins.put(""www.amazon.com", "login with Amazon token");
 provider.setLogins(logins);

 // Note: Please reuse the provider when possible.

 //The existing constructor will work without doing so, but will not use the enhanced flow:
 CognitoCachingCredentialsProvider provider = new CognitoCachingCredentialsProvider(
         context,
         "awsAccountId",
         "identityPoolId",
         "unauthRoleArn",
         "authRoleArn",
         Regions.US_EAST_1);
 

Field Summary

Fields inherited from class com.amazonaws.auth.CognitoCredentialsProvider

DEFAULT_DURATION_SECONDS, DEFAULT_THRESHOLD_SECONDS

Constructor Summary

Constructors

Constructor and Description
CognitoCachingCredentialsProvider(android.content.Context context, AWSCognitoIdentityProvider provider, Regions region) Constructs a new CognitoCachingCredentialsProvider, which will set up a link to the provider passed in using the enhanced authentication flow to get short-lived credentials from Amazon Cognito, which can be retrieved from getCredentials()
CognitoCachingCredentialsProvider(android.content.Context context, AWSCognitoIdentityProvider provider, Regions region, ClientConfiguration clientConfiguration) Constructs a new CognitoCachingCredentialsProvider, which will set up a link to the provider passed in using the enhanced authentication flow to get short-lived credentials from Amazon Cognito, which can be retrieved from getCredentials()
CognitoCachingCredentialsProvider(android.content.Context context, AWSCognitoIdentityProvider provider, java.lang.String unauthArn, java.lang.String authArn) Constructs a new CognitoCachingCredentialsProvider, which will set up a link to the provider passed in using the basic authentication flow to get get short-lived credentials from STS, which can be retrieved from getCredentials()
CognitoCachingCredentialsProvider(android.content.Context context, AWSCognitoIdentityProvider provider, java.lang.String unauthArn, java.lang.String authArn, com.amazonaws.services.securitytoken.AWSSecurityTokenService stsClient) Constructs a new CognitoCachingCredentialsProvider, which will set up a link to the provider passed in to use the basic authentication flow to get short-lived credentials from STS, which can be retrieved from getCredentials()
CognitoCachingCredentialsProvider(android.content.Context context, AWSConfiguration awsConfiguration) Constructs a new CognitoCachingCredentialsProvider, which will use the specified Amazon Cognito identity pool to make a request to Cognito, using the enhanced flow, to get short lived session credentials, which will then be returned by this class's getCredentials() method.
CognitoCachingCredentialsProvider(android.content.Context context, java.lang.String identityPoolId, Regions region) Constructs a new CognitoCachingCredentialsProvider, which will use the specified Amazon Cognito identity pool to make a request to Cognito, using the enhanced flow, to get short lived session credentials, which will then be returned by this class's getCredentials() method.
CognitoCachingCredentialsProvider(android.content.Context context, java.lang.String identityPoolId, Regions region, ClientConfiguration clientConfiguration) Constructs a new CognitoCachingCredentialsProvider, which will use the specified Amazon Cognito identity pool to make a request to Cognito, using the enhanced flow, to get short lived session credentials, which will then be returned by this class's getCredentials() method.
CognitoCachingCredentialsProvider(android.content.Context context, java.lang.String accountId, java.lang.String identityPoolId, java.lang.String unauthArn, java.lang.String authArn, com.amazonaws.services.cognitoidentity.AmazonCognitoIdentityClient cibClient, com.amazonaws.services.securitytoken.AWSSecurityTokenService stsClient) Constructs a new CognitoCachingCredentialsProvider, which will use the specified Amazon Cognito identity pool to make a request to the AWS Security Token Service (STS) to get short-lived session credentials, which will then be returned by this class's getCredentials() method.
CognitoCachingCredentialsProvider(android.content.Context context, java.lang.String accountId, java.lang.String identityPoolId, java.lang.String unauthRoleArn, java.lang.String authRoleArn, Regions region) Constructs a new CognitoCachingCredentialsProvider, which will use the specified Amazon Cognito identity pool to make a request, using the basic authentication flow, to the AWS Security Token Service (STS) to request short-lived session credentials, which will then be returned by this class's getCredentials() method.
CognitoCachingCredentialsProvider(android.content.Context context, java.lang.String accountId, java.lang.String identityPoolId, java.lang.String unauthRoleArn, java.lang.String authRoleArn, Regions region, ClientConfiguration clientConfiguration) Constructs a new CognitoCachingCredentialsProvider, which will use the specified Amazon Cognito identity pool to make a request, using the basic authentication flow, to the AWS Security Token Service (STS) to request short-lived session credentials, which will then be returned by this class's getCredentials() method.

Method Summary

Modifier and Type	Method and Description
void	clear() Clear all in-memory and saved state for the credentials provider.
void	clearCredentials() Clear credentials.
java.lang.String	getCachedIdentityId() Gets the cached identity id without making a network request.
AWSSessionCredentials	getCredentials() If the current session has expired/credentials are invalid, a new session is started, establishing the credentials.
java.lang.String	getIdentityId() Gets the Cognito identity id of the user.
void	refresh() Forces this credentials provider to refresh its credentials.
void	setLogins(java.util.Map<java.lang.String,java.lang.String> logins) Set the logins map used to authenticated with Amazon Cognito.
void	setPersistenceEnabled(boolean isPersistenceEnabled) Set the flag that determines if the credentials and identityId will be stored in memory or SharedPreferences.
void	setUserAgentOverride(java.lang.String userAgentOverride) The user agent string is sometimes combined with other strings.

Methods inherited from class com.amazonaws.auth.CognitoCredentialsProvider

getCustomRoleArn, getIdentityPoolId, getIdentityProvider, getLogins, getRefreshThreshold, getSessionCredentialsExpiration, getSessionCredentitalsExpiration, getSessionDuration, getToken, registerIdentityChangedListener, setCustomRoleArn, setRefreshThreshold, setSessionCredentialsExpiration, setSessionDuration, unregisterIdentityChangedListener, withLogins, withRefreshThreshold, withSessionDuration

Methods inherited from class java.lang.Object

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

Constructor Detail

CognitoCachingCredentialsProvider

public CognitoCachingCredentialsProvider(android.content.Context context,
                                         java.lang.String accountId,
                                         java.lang.String identityPoolId,
                                         java.lang.String unauthRoleArn,
                                         java.lang.String authRoleArn,
                                         Regions region)

Constructs a new CognitoCachingCredentialsProvider, which will use the specified Amazon Cognito identity pool to make a request, using the basic authentication flow, 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:

context - The Android context to be used for the caching

accountId - The AWS accountId for the account with Amazon Cognito

identityPoolId - The Amazon Cogntio identity pool to use

unauthRoleArn - The ARN of the IAM Role that will be assumed when unauthenticated

authRoleArn - The ARN of the IAM Role that will be assumed when authenticated

region - The region to use when contacting Cognito Identity

CognitoCachingCredentialsProvider

public CognitoCachingCredentialsProvider(android.content.Context context,
                                         java.lang.String accountId,
                                         java.lang.String identityPoolId,
                                         java.lang.String unauthRoleArn,
                                         java.lang.String authRoleArn,
                                         Regions region,
                                         ClientConfiguration clientConfiguration)

Constructs a new CognitoCachingCredentialsProvider, which will use the specified Amazon Cognito identity pool to make a request, using the basic authentication flow, to the AWS Security Token Service (STS) to request short-lived session credentials, which will then be returned by this class's getCredentials() method.

This version of the constructor allows you to specify a client configuration for the Amazon Cognito and STS clients.

Parameters:

context - The Android context to be used for the caching

accountId - The AWS accountId for the account with Amazon Cognito

identityPoolId - The Amazon Cognito identity pool to use

unauthRoleArn - The ARN of the IAM Role that will be assumed when unauthenticated

authRoleArn - The ARN of the IAM Role that will be assumed when authenticated

region - The region to use when contacting Cognito Identity

clientConfiguration - Configuration to apply to service clients created

CognitoCachingCredentialsProvider

public CognitoCachingCredentialsProvider(android.content.Context context,
                                         java.lang.String identityPoolId,
                                         Regions region)

Constructs a new CognitoCachingCredentialsProvider, which will use the specified Amazon Cognito identity pool to make a request to Cognito, using the enhanced flow, to get short lived session credentials, which will then be returned by this class's getCredentials() method.

Note: if you haven't yet associated your IAM roles with your identity pool, please do so via the Cognito console before using this constructor. You will get an InvalidIdentityPoolConfigurationException if you use it and have not. The existing constructor (mirroring this one but with roles and an account id) will work without doing so, but will not use the enhanced flow.

Parameters:

context - The Android context to be used for the caching

identityPoolId - The Amazon Cognito identity pool to use

region - The region to use when contacting Cognito Identity

CognitoCachingCredentialsProvider

public CognitoCachingCredentialsProvider(android.content.Context context,
                                         AWSConfiguration awsConfiguration)

Constructs a new CognitoCachingCredentialsProvider, which will use the specified Amazon Cognito identity pool to make a request to Cognito, using the enhanced flow, to get short lived session credentials, which will then be returned by this class's getCredentials() method.

Note: if you haven't yet associated your IAM roles with your identity pool, please do so via the Cognito console before using this constructor. You will get an InvalidIdentityPoolConfigurationException if you use it and have not. The existing constructor (mirroring this one but with roles and an account id) will work without doing so, but will not use the enhanced flow.

Example json file: { "CredentialsProvider": { "CognitoIdentity": { "Default": { "PoolId": "us-east-1:example-pool-id1234", "Region": "us-east-1" } } } }

Parameters:

context - The Android context to be used for the caching

awsConfiguration - The configuration holding you identity pool id and the region to use when contacting Cognito Identity

CognitoCachingCredentialsProvider

public CognitoCachingCredentialsProvider(android.content.Context context,
                                         java.lang.String identityPoolId,
                                         Regions region,
                                         ClientConfiguration clientConfiguration)

Constructs a new CognitoCachingCredentialsProvider, which will use the specified Amazon Cognito identity pool to make a request to Cognito, using the enhanced flow, to get short lived session credentials, which will then be returned by this class's getCredentials() method.

This version of the constructor allows you to specify a client configuration for the Amazon Cognito client.

Note: if you haven't yet associated your IAM roles with your identity pool, please do so via the Cognito console before using this constructor. You will get an InvalidIdentityPoolConfigurationException if you use it and have not. The existing constructor (mirroring this one but with roles and an account id) will work without doing so, but will not use the enhanced flow.

Parameters:

context - The Android context to be used for the caching

identityPoolId - The Amazon Cognito identity pool to use

region - The region to use when contacting Cognito Identity

clientConfiguration - Configuration to apply to service clients created

CognitoCachingCredentialsProvider

public CognitoCachingCredentialsProvider(android.content.Context context,
                                         java.lang.String accountId,
                                         java.lang.String identityPoolId,
                                         java.lang.String unauthArn,
                                         java.lang.String authArn,
                                         com.amazonaws.services.cognitoidentity.AmazonCognitoIdentityClient cibClient,
                                         com.amazonaws.services.securitytoken.AWSSecurityTokenService stsClient)

Constructs a new CognitoCachingCredentialsProvider, which will use the specified Amazon Cognito identity pool to make a request to the AWS Security Token Service (STS) to get short-lived session credentials, which will then be returned by this class's getCredentials() method.

This version of the constructor allows you to specify the Amazon Cognito and STS client to use.

Set the roles and stsClient to null to use the enhanced authentication flow, not contacting STS. Otherwise the basic flow will be used.

Parameters:

context - The Android context to be used for the caching

accountId - The AWS accountId for the account with Amazon Cognito

identityPoolId - The Amazon Cogntio identity pool to use

unauthArn - The ARN of the IAM Role that will be assumed when unauthenticated

authArn - The ARN of the IAM Role that will be assumed when authenticated

cibClient - Preconfigured CognitoIdentity client to make requests with

stsClient - Preconfigured STS client to make requests with

CognitoCachingCredentialsProvider

public CognitoCachingCredentialsProvider(android.content.Context context,
                                         AWSCognitoIdentityProvider provider,
                                         java.lang.String unauthArn,
                                         java.lang.String authArn)

Constructs a new CognitoCachingCredentialsProvider, which will set up a link to the provider passed in using the basic authentication flow to get get short-lived credentials from STS, which can be retrieved from getCredentials()

This version of the constructor allows you to specify your own Identity Provider class.

Parameters:

context - The Android context to be used for the caching

provider - a reference to the provider in question, including what's needed to interact with it to later connect with STS

unauthArn - the unauthArn, for use with the STS call

authArn - the authArn, for use with the STS call

CognitoCachingCredentialsProvider

public CognitoCachingCredentialsProvider(android.content.Context context,
                                         AWSCognitoIdentityProvider provider,
                                         java.lang.String unauthArn,
                                         java.lang.String authArn,
                                         com.amazonaws.services.securitytoken.AWSSecurityTokenService stsClient)

Constructs a new CognitoCachingCredentialsProvider, which will set up a link to the provider passed in to use the basic authentication flow to get short-lived credentials from STS, which can be retrieved from getCredentials()

This version of the constructor allows you to specify your own Identity Provider class, and the STS client to use.

Parameters:

context - The Android context to be used for the caching

provider - a reference to the provider in question, including what's needed to interact with it to later connect with STS

unauthArn - the unauthArn, for use with the STS call

authArn - the authArn, for use with the STS call

stsClient - the sts endpoint to get session credentials from

CognitoCachingCredentialsProvider

public CognitoCachingCredentialsProvider(android.content.Context context,
                                         AWSCognitoIdentityProvider provider,
                                         Regions region)

Constructs a new CognitoCachingCredentialsProvider, which will set up a link to the provider passed in using the enhanced authentication flow to get short-lived credentials from Amazon Cognito, which can be retrieved from getCredentials()

This version of the constructor allows you to specify your own Identity Provider class.

Note: if you haven't yet associated your IAM roles with your identity pool, please do so via the Cognito console before using this constructor. You will get an InvalidIdentityPoolConfigurationException if you use it and have not. The existing constructor (mirroring this one but with roles) will work without doing so, but will not use the enhanced flow.

Parameters:

context - The Android context to be used for the caching

provider - a reference to the provider in question, including what's needed to interact with it to later connect with Amazon Cognito

region - The region to use when contacting Cognito

CognitoCachingCredentialsProvider

public CognitoCachingCredentialsProvider(android.content.Context context,
                                         AWSCognitoIdentityProvider provider,
                                         Regions region,
                                         ClientConfiguration clientConfiguration)

Constructs a new CognitoCachingCredentialsProvider, which will set up a link to the provider passed in using the enhanced authentication flow to get short-lived credentials from Amazon Cognito, which can be retrieved from getCredentials()

This version of the constructor allows you to specify your own Identity Provider class and the configuration for the Amazon Cognito client.

Note: if you haven't yet associated your IAM roles with your identity pool, please do so via the Cognito console before using this constructor. You will get an InvalidIdentityPoolConfigurationException if you use it and have not. The existing constructor (mirroring this one but with roles) will work without doing so, but will not use the enhanced flow.

Parameters:

context - The Android context to be used for the caching

provider - a reference to the provider in question, including what's needed to interact with it to later connect with Amazon Cognito

clientConfiguration - Configuration to apply to service clients created

region - The region to use when contacting Cognito Identity

Method Detail

getIdentityId

public java.lang.String getIdentityId()

Gets the Cognito identity id of the user. The first time when this method is called, a network request will be made to retrieve a new identity id. After that it's saved in SharedPreferences. Please don't call it in the main thread.

Overrides:

getIdentityId in class CognitoCredentialsProvider

Returns:

identity id of the user

getCredentials

public AWSSessionCredentials getCredentials()

Description copied from class: CognitoCredentialsProvider

If the current session has expired/credentials are invalid, a new session is started, establishing the credentials. In either case, those credentials are returned

Specified by:

getCredentials in interface AWSCredentialsProvider

Overrides:

getCredentials in class CognitoCredentialsProvider

Returns:

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

refresh

public void refresh()

Description copied from interface: AWSCredentialsProvider

Forces this credentials provider to refresh its credentials. For many implementations of credentials provider, this method may simply be a no-op, such as any credentials provider implementation that vends static/non-changing credentials. For other implementations that vend different credentials through out their lifetime, this method should force the credentials provider to refresh its credentials.

Specified by:

refresh in interface AWSCredentialsProvider

Overrides:

refresh in class CognitoCredentialsProvider

setLogins

public void setLogins(java.util.Map<java.lang.String,java.lang.String> logins)

Description copied from class: CognitoCredentialsProvider

Set the logins map used to authenticated with Amazon Cognito. Note: You should manually call refresh on on the credentials provider after adding logins to the provider as your Identity Id may have changed.

Overrides:

setLogins in class CognitoCredentialsProvider

Parameters:

logins - The new logins map (providerName, providerToken) to use to communicate with Amazon Cognito

clear

public void clear()

Description copied from class: CognitoCredentialsProvider

Clear all in-memory and saved state for the credentials provider. Will destroy any saved Amazon Cognito Identity Id and associated AWS credentials.

Overrides:

clear in class CognitoCredentialsProvider

clearCredentials

public void clearCredentials()

Description copied from class: CognitoCredentialsProvider

Clear credentials. This will destroy all the saved AWS credentials but not the identity Id.

Overrides:

clearCredentials in class CognitoCredentialsProvider

getCachedIdentityId

public java.lang.String getCachedIdentityId()

Gets the cached identity id without making a network request.

Returns:

cached identity id, null if it doesn't exist

setPersistenceEnabled

public void setPersistenceEnabled(boolean isPersistenceEnabled)

Set the flag that determines if the credentials and identityId will be stored in memory or SharedPreferences.

Parameters:

isPersistenceEnabled - flag that indicates if the credentials need to be persisted or not

setUserAgentOverride

public void setUserAgentOverride(java.lang.String userAgentOverride)

The user agent string is sometimes combined with other strings. If this property is set, it instructs the client to only use this as the full user agent string.

Parameters:

userAgentOverride - The string to use as the full user agent when sending requests.