Authenticating users with AWS Cognito in Fauna

✔️ Pre-requisites

This article assumes that you have some basic understanding of AWS Cognito and Fauna Authentication. If either of these concepts is completely new to you, review the following tutorials before proceeding.Using Amazon Cognito Identity to authenticate usersUser Management with AWS CognitoFauna | User authentication

AWS Cognito and Fauna authentication architecture

ℹ️ Review all the available triggers by logging into your AWS console and navigating to Cognito > User Pools > Name of your User pool > Triggers.

Authentication flow

1. The client application (React app) sends a request to Cognito.
2. Cognito invokes an AWS Lambda function in the token generation phase.
3. The Lambda function generates a user-based access_token and refresh_token for Fauna. These tokens auto-expire after a specified time.
4. Cognito returns all the tokens to the client application.
5. The client application uses the tokens to communicate with Fauna database.

Creating a new Cognito App

The client secret is an optional parameter that provides an extra layer of security. For simplicity, this tutorial is not utilizing this feature. Review the AWS Cognito documentation for more information.

Adding Cognito to the client application

git clone https://github.com/fauna-labs/fauna-cognito-auth

export const config = {
    UserPoolId: 'us-east-1_teqKLEjjjc',
    ClientId: '7spl4e1pnj5h97jjh8l6b6a5jn'
}

npm install
npm start

Fauna configuration

// Create accounts Collection
CreateCollection({ name: 'Account' })

CreateIndex({
  name: 'accounts_by_email',
  source: Collection('Account'),
  // We will search on email
  terms: [
    {
      field: ['data', 'email']
    }
  ],
  unique: true,
  serialized: true
})

{
    "title": "The Hateful Eight",
    "director": "Quentin Tarantino",
    "release": "December 25, 2015"
}

{
    "title": "Once Upon a Time in Hollywood",
    "director": "Quentin Tarantino",
    "release": "July 26, 2019"
}

Creating a Lambda function

...
// Registers a new User in FaunaDB
const registerUser = (email) => {
    return serverClient.query(
        q.Create(
          q.Collection('accounts'),
          { data: { email } },
        )
    );
};

// Get a user
const getUserByEmail = (email) => {
    return serverClient.query(
        q.Get(
          q.Match(q.Index('accounts_by_email'), email)
        )
    );
};

const createRefreshToken = (ref, ttl) => {
    return serverClient.query(
        q.Create(q.Tokens(), {
            instance: q.Ref(q.Collection("accounts"), ref),
            data: {
              type: "refresh"
            },
            ttl: q.TimeAdd(q.Now(), ttl, "seconds"),
        })
    );
};

const createAccessToken = (accountRef, refreshTokenRef, ttl) => {
    return serverClient.query(
        q.Create(q.Tokens(), {
            instance: q.Ref(q.Collection("accounts"), accountRef),
            data: {
              type: 'access',
              refresh:  refreshTokenRef
            },
            ttl: q.TimeAdd(q.Now(), ttl, 'seconds')
        })
    );
};

💡 On line 4, you have to define the Fauna server key secret (Generated in the previous step). Please be advised that hardcoding this value is not recommended. You must use a secret manager to maintain this key.💡 Please refer to the following article to learn more about how to manage secrets inside your Lambda functions.

const faunadb = require('faunadb');
const q = faunadb.query;

const serverClient = new faunadb.Client({ secret: '<Your Fauna Server Secrect>' });
// In production do not hardcode this value.
...

const email = event.request.userAttributes['email'];

try {
    const foundUser = await getUserByEmail(email);
    userId = foundUser.ref.id;

} catch (e) {
    console.log('Error: %s', e);
    const newUser = await registerUser(email);
    userId = newUser.ref.id;
}

try {
    const faunaRefreshToken = await createRefreshToken(userId, 3600);
    fauna_refresh_token = faunaRefreshToken.secret;
    console.log('fauna_refresh_token', fauna_refresh_token);
    const rret = await createAccessToken(userId, fauna_refresh_token, 600);
    fauna_access_token = rret.secret;
    console.log('fauna_access_token', rret.secret);
} catch (e) {
  console.log('Token Generation Error: %s', e);
}

event.response = {
    "claimsOverrideDetails": {
        "claimsToAddOrOverride": {
            fauna_access_token,
            fauna_refresh_token,
        },
        "claimsToSuppress": ["email"]
    }
};
context.done(null, event);
return event;

Test the client application

npm start

const onSubmit = async e => {
      e.preventDefault();
      console.log('State', state);

      const cognitoUser = new CognitoUser({
        Username: state.username,
        Pool: userPool,
      });
      const authenticationDetails = new AuthenticationDetails({
          Username: state.username,
          Password: state.password,
      });

      cognitoUser.authenticateUser(authenticationDetails, {
        onSuccess: data => {
          setCookie('fauna_access_token', data.getIdToken().payload.fauna_access_token)
          setCookie('cognito_refresh', data.getRefreshToken().getToken())
          setCookie('cognito_username', data.getAccessToken().payload.username)
          console.log('Auth Data', data);
          alert('User Login Successful');
          history.push('/movies');
        },

        onFailure: err => {
          console.log('Failed', err)
        },

        newPasswordRequired: newPass => {
          console.log('New Pass Required', newPass)
        }
      })
  }

const queryMovies = async () => {
      const serverClient = new faunadb.Client({ secret: cookies.fauna_access_token });
      try {
          const movies = await serverClient.query(
            q.Map(
              q.Paginate(q.Documents(q.Collection("movies"))),
              q.Lambda("X", q.Get(q.Var("X")))
            )
          )
          console.log('Movies', movies);
        } catch (error) {
          console.log('error', error);
          if(error.name === "Unauthorized") {
            // Refresh Tokens
            alert('Token Expired! Refresh Token or Log in again')
          }
      }
  }

import { CognitoUserPool, CognitoUser, CognitoRefreshToken } from 'amazon-cognito-identity-js';
...
const refreshTokens = () => {
    const cognitoUser = new CognitoUser({
        Username: cookies.cognito_username,
        Pool: userPool,
    });

    const cognito_refresh_token = new CognitoRefreshToken({ RefreshToken: cookies.cognito_refresh })

    cognitoUser.refreshSession(cognito_refresh_token, (err, session) => {
        if (err) {
            console.error(err);
        }
        setCookie('fauna_access_token', session.getIdToken().payload.fauna_access_token);
        alert('Token Refreshed')
    });
}

Conclusion