Amazon Cognito integration

Amazon Cognito lets you add user sign-up, sign-in, and access control to your web and mobile apps.

# MIRACL Trust application setup

An application on the MIRACL platform is required. It will be used by the Cognito platform as a Federated Identity Provider. Learn how to register a new app here.

# Cognito setup

You can create a new user pool or integrate into an existing one. MIRACL Trust can work both as an only authentication method and alongside other types of authentication.

# Create Federated Identity Provider

This configuration will establish the connection to MIRACL Trust.

  1. Go to the ‘Sign-in experience’ tab
  2. Click ‘Add identity provider’ in the ‘Federated identity provider sign-in’ section
  3. Select ‘OpenID Connect (OIDC)’ as an integration option
  4. Fill in MIRACL for the ‘Provider name’ (this will be used as an identifier)
  5. Fill in the ‘Client ID’ and ‘Client secret’ from the MIRACL Trust Console
  6. For ‘Authorized scopes’ fill in openid email
  7. Set the ‘Attribute request method’ to ‘POST’
  8. Set ‘Retrieve OIDC endpoints’ to ‘Auto fill through issuer URL’
  9. Fill in https://api.mpin.io for ‘Issuer URL’
  10. Click ‘Add identity provider’

# Configure Hosted UI Domain

For Cognito to handle the redirections and automatically process the authentication result from MIRACL Trust, you need to set up the Cognito Hosted UI.

  1. Go to the ‘App integration’ tab
  2. From the ‘Domain’ options select either ‘Create Cognito domain’
  3. Fill in the domain field
  4. Click ‘Create domain’
  5. Allow time for the domain settings to propagate

# Create App Client

Creating an App Client will set the Cognito OAuth 2.0 settings you will need to integrate with your application. This example will assume that your application is running locally on http://localhost:3000.

  1. Go to the ‘App integration’ tab
  2. Click ‘Create app client’ in the ‘App clients and analytics’ section
  3. Select ‘Public client’ for ‘App type’
  4. Enter an ‘App client name’
  5. Select ‘Don’t generate a client secret’ for ‘Client secret’
  6. Fill in http://localhost:3000 in ‘Allowed callback URLs’
  7. Add http://localhost:3000 in ‘Allowed sign-out URLs’
  8. Add the previously created MIRACL provider in the ‘Identity providers’ section
  9. Optionally remove ‘Cognito user pool’ from the ‘Identity providers’ section
  10. Ensure that ‘Authorization code grant’ is enabled for ‘OAuth 2.0 grant types’
  11. Click ‘Create app client’

# Integrating into your application back-end

It’s recommended to use an OAuth 2.0 client library to set up your back-end application with Cognito for authentication. OAuth libraries are available in a variety of languages. For a list of implementations visit https://oauth.net/code/.

# Integrating into a single-page application (SPA)

The easiest way to integrate Cognito authentication into your SPA is using the AWS Amplify tooling. You can use the Amplify CLI to set up your project following this guide, which is going to automatically generate the needed configuration for your app.

Alternatively, you can directly install the Amplify library using NPM or Yarn.

npm install aws-amplify
# or
yarn add aws-amplify

In this case, you need to generate the configuration manually and it should look similar in structure to this example aws-exports.js file:

export default {
    "aws_project_region": "eu-west-2",
    "aws_cognito_identity_pool_id": "eu-west-2:<REDACTED>",
    "aws_cognito_region": "eu-west-2",
    "aws_user_pools_id": "<REDACTED>",
    "aws_user_pools_web_client_id": "<REDACTED>",
    "oauth": {
        "domain": "<REDACTED>.auth.eu-west-2.amazoncognito.com",
        "scope": ["email", "profile", "openid"],
        "redirectSignIn": "http://localhost:3000",
        "redirectSignOut": "http://localhost:3000",
        "responseType": "code"
    },
    "aws_cognito_username_attributes": [
        "EMAIL"
    ],
    "aws_cognito_social_providers": [],
    "aws_cognito_signup_attributes": [
        "EMAIL"
    ],
    "aws_cognito_mfa_configuration": "OFF",
    "aws_cognito_mfa_types": [],
    "aws_cognito_verification_mechanisms": [
        "EMAIL"
    ]
};

Once set up, using the Amplify library in your application is simple.

import { Amplify, Auth } from 'aws-amplify';
import awsExports from './aws-exports';

// Configure the Amplify lib.
Amplify.configure(awsExports);

// Redirect the user for authentication.
function signIn() {
  // The federated identity provider name needs to passed as
  // an argument to automatically redirect to that authentication.
  Auth.federatedSignIn({ provider: 'MIRACL' })
}

// Check if the user is logged in and output the result in the console.
function checkUser() {
  Auth.currentAuthenticatedUser()
    .then(user => console.log({ user }))
    .catch(err => console.log(err))
}

// Sign out the user both from Cognito and the application.
function signOut() {
  Auth.signOut()
    .then(data => console.log(data))
    .catch(err => console.log(err))
}