Amazon Cognito Integration

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

# Setup a MIRACL Trust application

An application on the MIRACL Trust platform is required. It is used by the Cognito platform as a federated identity provider. Learn how to register a new app here.

# Setup Cognito

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 a federated identity provider

This configuration establishes 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 Provide name (this is 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 the Cognito Hosted UI domain

For Cognito to handle the redirects 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 Create Cognito domain.
  3. Fill in the Domain field.
  4. Click Create Domain.
  5. Allow time for the domain settings to propagate.

# Create an app Client

Creating an app client sets the Cognito OAuth 2.0 settings that you need to integrate with your application. This example assumes 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.

# Integrate 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/.

# Integrate 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:<YOUR_IDENTITY_POOL_ID>",
  aws_cognito_region: "eu-west-2",
  aws_user_pools_id: "<YOUR_USER_POOLS_ID>",
  aws_user_pools_web_client_id: "<YOUR_POOLS_WEB_CLIENT_ID>",
  oauth: {
    domain: "<YOUR_ISSUER_DOMAIN>.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 be 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));
}