Talk to usSign up

LEARNING

Getting started with Circle-of-Trust

Table of Contents

Introduction

Circle-of-Trust™ is a method of Distributed Multi-factor Human-in-the-loop Identity Verification + Authentication, intended as an escalation option when needed for high-risk use cases, contexts, and user profiles. Based on the context and policies set by the end application, Circle executes multi-factor authentication and identity verification that is delegated to authorized persons. This capability can be triggered and executed independently or work together with Cryptographic Credential-free Authentication powered by Circle. Circle-of-Trust has flexible, configurable levels of security - this is the first level of implementation.

Demo

In order to show how Circle-of-Trust Basic works and enable developers to get started quickly,  this guide is designed to work together with our integration with Auth0 and the related demo we have created.

Related Getting Started Guides:

If you have not done so already, these Getting Started Guides are recommended before you start on this one.

Learning Center

If you have not done so already, we recommend that you take a quick look at these articles to understand the key concepts of Circle and its capabilities.

Prerequisites

Before you begin:

Make sure you have a Circle account.   You can get one for free at:  https://circlesecurity.ai/developer-pricing/

Make sure you have Circle Service installed (you should have gotten it at the end of the sign up).

Core Setup

1. Create an Auth0 account. Go to the Auth0 Dashboard, Applications and create an Application:
a. Add your callback URLs ( your website site address that will run the Circle SDK code)
b. Copy your _Client ID_ and _Domain_
c. Enable _Refresh Token Rotation (this step is to increase security)_
2. Make a call to Circle to save the configuration, for example:

const state = randomString(32);
  const codeVerifier = randomString(64);
  const codeChallenge = await sha256(codeVerifier).then(bufferToBase64UrlEncoded);
const serviceConfigurationJson = {
        "domain": AUTH0_DOMAIN,
        "client_id": AUTH0_CLIENT_ID,
        "code_challenge": codeChallenge,
    "code_challenge_method": "S256",
    "scope": "openid profile email offline_access",
    "state": state,
    "response_type": "code"
  }
const configService = await  Circle.configureService("your circle id", 0, "auth0-demo", JSON.stringify(serviceConfigurationJson))

3. Now, we call Circle to login to Auth0 Service:

const loginToService = await Circle.logintoService("your circle id", 0, "auth0-demo", "auth0-token");

4. If we have the token already saved inside Circle, we just log the user in, otherwise we call Auth0 login flow.

const  token = loginToService.ServiceReturn;
if (token) {
        // parse the JWT - log the user
} else {
        // call Auth0 login -flow

Delegated Multi-Factor Authentication

Circle Service allows delegated multi-factor authentication. You can securely "lock" the user and by doing it, Circle Service will either:

  • Provide you with the number of codes you requested to unlock the user or;
  • Distribute the codes in the way you requested when you made the request.

Use Case - Example 1:

If, for any reason your website detects a new IP connection, not whitelisted, you can start the lock process by requesting 2 codes as a default, however you can select a different number (more than 2) codes if you prefer.

  • Circle Service will then lock the user and return the codes (encrypted with your public key), you can then send the codes to your server, decrypt them with your private key and distribute them the way you prefer -
  • Normally by email or sms, or send them to another authorized person or persons, who will then communicate (any mode of communication chosen by the person including a video call, etc.) to the user, after making sure the user is really who is accessing your website or application.

Steps

1. First check the user "Locked" state by calling _"whoAmI"_
2. If the user is locked, present the screen to enter the codes.
3. If the user is not locked, lock the user, get the encrypted codes and send to your server, to decrypt them and distribute.

const userData = await Circle.whoAmI("you circle id");
if (userData || userData.Locked) {
   // user is already locked
  // present the screen to enter the codes
} else {
 // if not locked you can then lock him
  const codes = await Circle.lockUser("you circle id", 2); // 2 is the number of codes
  if (codes && codes.Status.Result && codes.EncryptedUnlockCodes.length > 1) {
    const code1 = codes.EncryptedUnlockCodes[0];
    const code2 = codes.EncryptedUnlockCodes[1];
    // you can now send the codes to your server to decrypt and distribute
   }
}

Use Case - Example 2:

If, for any reason your website detects a new IP connection, not whitelisted, you can start the lock process by requesting Circle to distribute the 2 codes as a default, however you can select a different number (more than 2) codes if you prefer.

  • You will request a new Circle Token with the Multi-Factor authentication data needed for Circle Service to process the code distribution. With this new Circle Token you will make a request to lock the user.
  • Circle Service will read the data from the token provided and send the codes accordingly - Normally by email or sms, or send them to another authorized person or persons, who will then communicate (any mode of communication chosen by the person including a video call, etc.) to the use,r after making sure the user is really who accessing your website or application.

Steps

1. First check the user "Locked" state by calling _"whoAmI"_
2. If the user is locked, present the screen to enter the codes.,
3. If the user is not locked, lock the user, make the request with the new Circle Token, so Circle Service can distribute the codes accordingly.

const userData = await Circle.whoAmI("you circle id");
if (userData || userData.Locked) {
   // user is already locked
  // present the screen to enter the codes
} else {
 // if not locked you can then lock him
  const codes = await Circle.lockUser("you circle id", 2); // 2 is the number of codes
  if (codes && codes.Status.Result) {
    // the codes were successfully distributed
   }
}

You can get the full sample code on the demo.

What are your Feelings