Authentication in the Browser with Amazon Cognito and Public Identity Providers

Our earlier blog post introduced authentication with Amazon Cognito in the browser.

Amazon Cognito has since simplified the authentication workflow. This article describes authenticating the SDK in the browser using Amazon Cognito and supported public identity providers like Google, Facebook, and Amazon.

Step 1 and Step 2 outline registering your application with a public identity provider, and creating a Cognito identity pool. These steps typically need to be performed only once.

One-time Setup

Step 3 and Step 4 describe the authentication workflow of a client application using a public identity provider with Amazon Cognito.

Client Application Workflow

Step 1: Set up a public identity provider

Amazon Cognito supports Facebook, Google, Amazon, and any other OpenID Connect compliant provider. As a first step you will have to register your application with a public identity provider. Here is a list of popular providers:

You can then use the corresponding provider’s SDK in your web application to allow users to authenticate with the provider. Listed below are the developer guides for the providers listed above:

Step 2: Create a Cognito Identity Pool

To begin using Amazon Cognito you will need to set up an identity pool. An identity pool is a store of user identity data specific to your account. The easiest way to setup an identity pool is to use the Amazon Cognito console.

The New Identity Pool wizard will guide you through the configuration process. When creating your identity pool, make sure that you enable access to unauthenticated identities. At this time, you can also configure any public identity providers that you have setup in Step 1.

The wizard will then create authenticated and unauthenticated roles for you with very limited permissions. You can edit these roles later using the IAM console. Note that Amazon Cognito will use these roles to grant authenticated and unauthenticated access to your resources, so scope them accordingly.

Step 3: Starting with Unauthenticated Access to Resources

You may want to grant unauthenticated users read-only access to some resources. These permissions should be configured in the IAM role for unauthenticated access (the role created in Step 2).

Configuring the SDK

To configure the SDK to work with unauthenticated roles simply omit the Logins property of the AWS.CognitoIdentityCredentials provider.

Because your identity pool is already configured to use authenticated and unauthenticated IAM roles, you need not set the RoleArn parameter when constructing your provider.

// Identity pool already configured to use roles
var creds = new AWS.CognitoIdentityCredentials({
    IdentityPoolId: 'us-east-1:1699ebc0-7900-4099-b910-2df94f52a030'
})

AWS.config.update({
    region: 'us-east-1',
    credentials: creds
});

Making requests

Having configured a credential provider, you can now make requests with the SDK.

var s3 = new AWS.S3({region: 'us-west-2'});
s3.listObjects({Bucket: 'bucket'}, function(err, data) {
    if (err) console.log(err);
    else console.log(data);
});

Step 4: Switching to Authenticated Access

You can also use the public identity provider configured in Step 1 to provide authenticated access to your resources.

When a user of your application authenticates with a public identity provider, the response contains a login token that must be supplied to Amazon Cognito in exchange for temporary credentials.

For Facebook and Amazon, this token is available at the access_token property of the response data. For Google and any other OpenID provider, this token is available at the id_token property of the response.

Refreshing credentials

After a user has authenticated with a public identity provider, you will need to update your credential provider with the login token from the authentication response.

// access_token received in the authentication response
// from Facebook
creds.params.Logins = {};
creds.params.Logins['graph.facebook.com'] = access_token;

// Explicitly expire credentials so they are refreshed
// on the next request.
creds.expired = true;

The credential provider will refresh credentials when the next request is made.

Persisting authentication tokens

In most cases, the SDKs of public identity providers have built-in mechanisms for caching the login tokens for the duration of the session. For example, the Login with Amazon SDK for JavaScript will cache the access_token and subsequent amazon.Login.authorize() calls will return the cached token as long as the session is valid.

The Facebook SDK for JavaScript exposes a FB.getLoginStatus() method which allows you to check the status of the login session.

The Google APIs Client Library for JavaScript automatically sets the OAuth 2.0 token for your application with the gapi.auth.setToken() method. This token can be retrieved using the gapi.auth.getToken() method.

You can also implement your own caching mechanism for login tokens, if these default mechanisms are insufficient for your use case.

Wrapping up

This article describes how to grant access to your AWS resources by using Amazon Cognito with public identity providers. We hope this article helps you easily authenticate users in your web applications with Amazon Cognito. We’d love to hear more about how you’re using the SDK in your browser applications, so leave us a comment or tweet about it @awsforjs.