public interface AmazonCognitoIdentity
Amazon Cognito is a web service that delivers scoped temporary credentials to mobile devices and other untrusted environments. Amazon Cognito uniquely identifies a device and supplies the user with a consistent identity over the lifetime of an application.
Using Amazon Cognito, you can enable authentication with one or more third-party identity providers (Facebook, Google, or Login with Amazon), and you can also choose to support unauthenticated access from your app. Cognito delivers a unique identifier for each user and acts as an OpenID token provider trusted by AWS Security Token Service (STS) to access temporary, limited-privilege AWS credentials.
To provide end-user credentials, first make an unsigned call to GetId.
If the end user is authenticated with one of the supported identity
providers, set the Logins
map with the identity provider token.
GetId
returns a unique identifier for the user.
Next, make an unsigned call to GetCredentialsForIdentity. This call
expects the same Logins
map as the GetId
call, as
well as the IdentityID
originally returned by GetId
. Assuming your identity pool has been configured via the
SetIdentityPoolRoles operation, GetCredentialsForIdentity
will return AWS credentials for your use. If your pool has not been
configured with SetIdentityPoolRoles
, or if you want to follow
legacy flow, make an unsigned call to GetOpenIdToken, which returns
the OpenID token necessary to call STS and retrieve AWS credentials. This
call expects the same Logins
map as the GetId
call,
as well as the IdentityID
originally returned by
GetId
. The token returned by GetOpenIdToken
can be
passed to the STS operation AssumeRoleWithWebIdentity to retrieve AWS credentials.
If you want to use Amazon Cognito in an Android, iOS, or Unity application, you will probably want to make API calls via the AWS Mobile SDK. To learn more, see the AWS Mobile SDK Developer Guide.
Modifier and Type | Method and Description |
---|---|
ResponseMetadata |
getCachedResponseMetadata(AmazonWebServiceRequest request)
Returns additional metadata for a previously executed successful request,
typically used for debugging issues where a service isn't acting as
expected.
|
GetCredentialsForIdentityResult |
getCredentialsForIdentity(GetCredentialsForIdentityRequest getCredentialsForIdentityRequest)
Returns credentials for the provided identity ID.
|
GetIdResult |
getId(GetIdRequest getIdRequest)
Generates (or retrieves) a Cognito ID.
|
GetOpenIdTokenResult |
getOpenIdToken(GetOpenIdTokenRequest getOpenIdTokenRequest)
Gets an OpenID token, using a known Cognito ID.
|
void |
setEndpoint(String endpoint)
Overrides the default endpoint for this client
("https://cognito-identity.us-east-1.amazonaws.com").
|
void |
setRegion(Region region)
An alternative to
setEndpoint(String) , sets
the regional endpoint for this client's service calls. |
void |
shutdown()
Shuts down this client object, releasing any resources that might be held
open.
|
void setEndpoint(String endpoint) throws IllegalArgumentException
Callers can pass in just the endpoint (ex:
"cognito-identity.us-east-1.amazonaws.com") or a full URL, including the
protocol (ex: "https://cognito-identity.us-east-1.amazonaws.com"). If the
protocol is not specified here, the default protocol from this client's
ClientConfiguration
will be used, which by default is HTTPS.
For more information on using AWS regions with the AWS SDK for Java, and a complete list of all available endpoints for all AWS services, see: http://developer.amazonwebservices.com/connect/entry.jspa?externalID= 3912
This method is not threadsafe. An endpoint should be configured when the client is created and before any service requests are made. Changing it afterwards creates inevitable race conditions for any service requests in transit or retrying.
endpoint
- The endpoint (ex:
"cognito-identity.us-east-1.amazonaws.com") or a full URL,
including the protocol (ex:
"https://cognito-identity.us-east-1.amazonaws.com") of the
region specific AWS endpoint this client will communicate
with.IllegalArgumentException
- If any problems are detected with the
specified endpoint.void setRegion(Region region) throws IllegalArgumentException
setEndpoint(String)
, sets
the regional endpoint for this client's service calls. Callers can use
this method to control which AWS region they want to work with.
By default, all service endpoints in all regions use the https protocol.
To use http instead, specify it in the ClientConfiguration
supplied at construction.
This method is not threadsafe. A region should be configured when the client is created and before any service requests are made. Changing it afterwards creates inevitable race conditions for any service requests in transit or retrying.
region
- The region this client will communicate with. See
Region.getRegion(com.amazonaws.regions.Regions)
for
accessing a given region.IllegalArgumentException
- If the given region is null,
or if this service isn't available in the given region. See
Region.isServiceSupported(String)
Region.getRegion(com.amazonaws.regions.Regions)
,
Region.createClient(Class,
com.amazonaws.auth.AWSCredentialsProvider, ClientConfiguration)
GetCredentialsForIdentityResult getCredentialsForIdentity(GetCredentialsForIdentityRequest getCredentialsForIdentityRequest) throws AmazonClientException, AmazonServiceException
Returns credentials for the provided identity ID. Any provided logins will be validated against supported login providers. If the token is for cognito-identity.amazonaws.com, it will be passed through to AWS Security Token Service with the appropriate role for the token.
This is a public API. You do not need any credentials to call this API.
getCredentialsForIdentityRequest
-
Input to the GetCredentialsForIdentity
action.
InvalidParameterException
ResourceNotFoundException
NotAuthorizedException
ResourceConflictException
TooManyRequestsException
InvalidIdentityPoolConfigurationException
InternalErrorException
ExternalServiceException
AmazonClientException
- If any internal errors are encountered
inside the client while attempting to make the request or
handle the response. For example if a network connection is
not available.AmazonServiceException
- If an error response is returned by Amazon
Cognito Identity indicating either a problem with the data in
the request, or a server side issue.GetIdResult getId(GetIdRequest getIdRequest) throws AmazonClientException, AmazonServiceException
Generates (or retrieves) a Cognito ID. Supplying multiple logins will create an implicit linked account.
This is a public API. You do not need any credentials to call this API.
getIdRequest
- Input to the GetId action.InvalidParameterException
ResourceNotFoundException
NotAuthorizedException
ResourceConflictException
TooManyRequestsException
InternalErrorException
LimitExceededException
ExternalServiceException
AmazonClientException
- If any internal errors are encountered
inside the client while attempting to make the request or
handle the response. For example if a network connection is
not available.AmazonServiceException
- If an error response is returned by Amazon
Cognito Identity indicating either a problem with the data in
the request, or a server side issue.GetOpenIdTokenResult getOpenIdToken(GetOpenIdTokenRequest getOpenIdTokenRequest) throws AmazonClientException, AmazonServiceException
Gets an OpenID token, using a known Cognito ID. This known Cognito ID is returned by GetId. You can optionally add additional logins for the identity. Supplying multiple logins creates an implicit link.
The OpenId token is valid for 15 minutes.
This is a public API. You do not need any credentials to call this API.
getOpenIdTokenRequest
- Input to the GetOpenIdToken action.InvalidParameterException
ResourceNotFoundException
NotAuthorizedException
ResourceConflictException
TooManyRequestsException
InternalErrorException
ExternalServiceException
AmazonClientException
- If any internal errors are encountered
inside the client while attempting to make the request or
handle the response. For example if a network connection is
not available.AmazonServiceException
- If an error response is returned by Amazon
Cognito Identity indicating either a problem with the data in
the request, or a server side issue.void shutdown()
ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request)
Response metadata is only cached for a limited period of time, so if you need to access this extra diagnostic information for an executed request, you should use this method to retrieve it as soon as possible after executing a request.
request
- The originally executed request.Copyright © 2018. All rights reserved.