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 is 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 establishes the connection to MIRACL Trust.
- Go to the ‘Sign-in experience’ tab
- Click ‘Add identity provider’ in the ‘Federated identity provider sign-in’ section
- Select ‘OpenID Connect (OIDC)’ as an integration option
- Fill in
MIRACL
for the ‘Provider name’ (this is used as an identifier) - Fill in the ‘Client ID’ and ‘Client secret’ from the MIRACL Trust Console
- For ‘Authorized scopes’ fill in
openid email
- Set the ‘Attribute request method’ to ‘POST’
- Set ‘Retrieve OIDC endpoints’ to ‘Auto fill through issuer URL’
- Fill in
https://api.mpin.io
for ‘Issuer URL’ - Click ‘Add identity provider’
# Configure 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.
- Go to the ‘App integration’ tab
- From the ‘Domain’ options select either ‘Create Cognito domain’
- Fill in the domain field
- Click ‘Create domain’
- Allow time for the domain settings to propagate
# Create 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
.
- Go to the ‘App integration’ tab
- Click ‘Create app client’ in the ‘App clients and analytics’ section
- Select ‘Public client’ for ‘App type’
- Enter an ‘App client name’
- Select ‘Don’t generate a client secret’ for ‘Client secret’
- Fill in
http://localhost:3000
in ‘Allowed callback URLs’ - Add
http://localhost:3000
in ‘Allowed sign-out URLs’ - Add the previously created
MIRACL
provider in the ‘Identity providers’ section - Optionally remove ‘Cognito user pool’ from the ‘Identity providers’ section
- Ensure that ‘Authorization code grant’ is enabled for ‘OAuth 2.0 grant types’
- 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:<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 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));
}