Front-End Web & Mobile

Understanding Amazon Cognito Authentication Part 2: Developer Authenticated Identities

Amazon Cognito helps you create unique identifiers for your end users that are kept consistent across devices and platforms. Cognito also delivers temporary, limited-privilege credentials to your application to access AWS resources. In a previous post, I covered the basics of Cognito’s authentication flow. In this post, I will show the differences in that flow when using developer authenticated identities.

Basic Authflow

As covered in previous blog posts, a user authenticating through Cognito will go through a three-step process to bootstrap their credentials:

  1. GetId – Create (or retrieve) a Cognito identity. Only necessary once per device.
  2. GetOpenIdToken – Obtain an OpenId Connect token for that identity.
  3. AssumeRoleWithWebIdentity – Exchange token for AWS credentials scoped to the identity.

Basic auth flow

In the basic authflow, all three calls are made from the user’s end device.

Developer Authenticated Identities Authflow

With developer authenticated identities, we introduced a new API, GetOpenIdTokenForDeveloperIdentity. This API call replaces the use of GetId and GetOpenIdToken from the device and should be called from your backend as part of your own authentication API.

With this change, the authflow from the device becomes:

  1. Your authentication API (which calls GetOpenIdTokenForDeveloperIdentity)
  2. AssumeRoleWithWebIdentity

New auth flow

The AWS Mobile SDK has been updated to support this flow via the use of a new interface called AWSCognitoIdentityProvider. See the Developer Guides (iOS|Android) for information on implementing these providers.

GetOpenIdTokenForDeveloperIdentity

As mentioned earlier, GetOpenIdTokenForDeveloperIdentity replaces the use of GetId and GetOpenIdToken from the device. Because this API call is signed by your AWS credentials, Cognito can trust that the user identifier supplied in the API call is valid. This replaces the token validation Cognito performs with public providers.

The API takes a number of fields, but only two are required:

  • IdentityPoolId – The Id of the pool you are using.
  • Logins – A map of logins for this identity. As with GetId and GetOpenIdToken, you can supply any supported public provider token, but you can additionally supply a user identifier keyed by the developer provider name that you set when you created the identity pool. This should be a unique identifer for this user in your system.
"Logins": {
    "graph.facebook.com": "FB_TOKEN",
    "accounts.google.com": "GOOGLE_TOKEN",
    "www.amazon.com": "AMZN_TOKEN",
    "login.mycompany.myapp": "USER_IDENTIFIER"
}

If the user identifier isn’t already linked to an existing identity, Cognito will create a new identity and return the new identity id and an OpenId Connect token for that identity. If the user identifer is already linked, Cognito will return the pre-existing identity id and an OpenId Connect token.

Linking Logins

As with public providers, supplying additional logins that are not already associated with an identity will implicitly link those logins to that identity. It is important to note that if you link a public provider login to an identity that user can use the basic authflow with that provider, but they cannot use your developer provider name in the logins map when calling GetId or GetOpenIdToken.

Merging Identities

With developer authenticated identities, Cognito supports both implicit merging as described in our previous post as well as explicit merging via the MergeDeveloperIdentities API call. This explicit merging allows you to mark two identities with user identifiers in your system as a single identity. You simply supply the source and destination user identifiers and Cognito will merge them. The next time you request an OpenId Connect token for either user identifier, the same identity id will be returned.

Conclusion

I hope this clarifies how Cognito authentication works with developer-authenticated identities. If you have any comments or questions, please free to leave a comment here or visit our forums and we will try to assist you.