Circle API Demos
Credential-Free Authentication with Auth0
Access Verification and Recovery with Circle-of-Trust
Here is some step-by-step guidance to help you get the most out of the demo.
What this demo shows
This demo shows two separate but intertwined functionalities:
Circle Credential-free Authentication – as it can be used when integrated with Auth0 for Federated Identities (e.g. Google/Gmail);
Circle-of-Trust Level 1 – a delegated distributed method of identity verification + authentication that works as a step-up escalation here with Auth0.
1. Circle Access Desktop + Auth0
The Auth0 Integration with the Circle Data API enables credential-free authentication with Circle Access Desktop. We support these Identity Providers for this demo, but any that Auth0 supports can be easily implemented. Simply pick the one you prefer. The user is authenticated by Auth0 using the API, and then the following process commences:
The user requests and securely receives the Access Token and Refresh Token;
The Access Token is used to log the user in; and
The Refresh Token is securely stored in a Circle Secure Capsule on the device for future frictionless logins.
After this process, the user no longer needs to provide credentials, including passwords or other information, to authenticate with the Identity Provider for all future sessions.
This is because the user has been authenticated by Auth0, which then securely transmits a Refresh Token to Circle Service on the endpoint device, which stores it securely in an AES 256 encrypted Secure Capsule. This Refresh Token can then be used to request Access Token whenever needed - subject to any limits and rules applied to the Refresh Token for duration and usage.
Resetting the Refresh Token from Circle Secure Capsule
The reset button deletes the refresh token from Circle Secure Capsule. The user must now re-authenticate through Auth0 with the selected Federated Identity Provider (in the case of Google).
The Log Out button logs the user from the Web page, but the refresh token remains stored in Circle Secure Capsule. The user can then log in again using this stored token.
Re-authentication: See below.
You can also invite your other devices to the secured capsule in this demo.
First, you will need to navigate to your profile icon.
If you are inviting a new device, click add device and you will be given an Invite ID and an Auth Code. Take note of these.
Sign into the demo using the device that you wish to ad.
Navigate to your profile icon again and click Accept Invite and input both the Invite ID and the Auth Code.
If the codes match, your new device will be added to the secure capsule.
To get started, just click the log-in button. This leverages our Auth0 integration to enable you to log in credential-free with one of the Federated Identity-supported identity providers - Google or LinkedIn.
Understand the roles
This demo demonstrates the basic mechanisms of Circle-of-Trust distributed human-in-the-loop identity verification and authentication. It combines end user and administrator / Circle-of-Trust Owner functions and UI.
This can be confusing until you understand the roles, functionalities, and how they interact.
For this demo, you have to assume three different roles:
Demo user – The person testing the platform.
Email authenticator – The first authenticator who receives an authentication code via email.
SMS authenticator – The second authenticator who receives an authentication code via SMS.
For pedagogical efficiency, it would make sense for the demo user to assume all three roles or delegate the email authenticator and SMS authenticator roles to persons within proximity.
What does Circle-of-Trust do?
With Circle-of-Trust, the identity verification and authentication process is entirely separate – delegated by Auth0 to Circle and executed in Circle’s patented, distributed peer-to-peer process. When triggered using the Re-authentication option:
Circle Service locks the Secure Capsule. The Secure Capsule will remain locked until the demo user receives and inputs the authentication codes from the person(s) they were sent to.
Sends two codes via separate channels (email and SMS) as set by the demo user in the demo admin panel.
The Web site presents the user with a dialogue box to input the codes to unlock the Secure Capsule, which is required for any operations with the Auth0 token (such as logging in).
When the authenticators verify the Demo User's identity - whether in person, by video conference, phone, or otherwise as appropriate - they give the Demo User the codes they have received.
The Demo User inputs the codes to unlock the Secure Capsule and restore standard credential-free authentication.
Since the demo user, in this case, is both the administrator and end-user, the application does not actually ‘lock’ the user out of the page – but it could. To prevent any scenario with an unrecoverable lock-out for this demo, the user can close the dialogue box and access and update the re-authentication settings as needed.
Using the settings panel
The demo user can:
Customize the text copy of messages that are sent;
Input the email and mobile number to which the codes will be sent; and
Use Circle’s E2EE Web video conferencing if desired to visually confirm identity and transmit codes completely out-of-band.
Notice that a video conferencing option is also available as an added precaution to verify the identity of your authenticators. When selected, the Demo User and 2 Authenticators will all be sent a link to a unique, one-time encrypted p2p video conference and their respective codes.
Notes on secure video conference option
Circle creates and provides a URL for a unique, one-time end-to-end encrypted video conferencing room. To use this, the demo user must have the link sent to them by the recipient/authenticator. In a more advanced application, all participants could share the link automatically.
By doing a video conference, the person being authenticated can now be visually seen and identified directly by the person authenticating him or her.
The authentication codes can also be transmitted verbally – or otherwise (e.g., QR code) – in the session, avoiding all vulnerable communications such as SMS and email.
The Demo User initiates re-authentication by selecting that option on the menu. Before doing that, however, the demo user should click on the settings panel to ensure the settings are well-defined, especially the email and number for the two authenticators.
After defining the settings, the Demo User needs to click Save Settings to save them.
The Demo User initiates re-authentication by selecting that option on the menu.
Once re-authentication is initiated, the Demo User is locked out of the page until both Authenticators have verified the identity of the Demo User and provided the codes sent to them by Circle-of-Trust.
To do this, they can meet in the encrypted video conference room using the link that was sent.
Unlocking the capsule with authentication codes
The Demo User inputs the codes into the screen and clicks the Check button. If the codes match those stored in the Circle, the Authenticators verify the Demo User’s identity. This unlocks the capsule and access to the site; the page is restored. Other options include:
Settings. Return Demo User to the Settings panel if any updates are needed (e.g., wrong email or phone number).
Resend. Sends a new set of codes if, for some reason, the first set was not received. Note – the previous regulations will no longer work.
The demo user can customize the text copy of messages that are sent.
The demo user will be locked out until both authenticators have received and authenticated him/her to provide the codes for unlocking the Secure Capsule.
The only way to unlock the capsule is with both authentication codes provided.
The Demo User can choose to use Circle’s E2EE Web video conferencing if desired to confirm identity and transmit codes completely out-of-band visually.
The Authenticators can meet in the encrypted video conference room using the link sent after receiving the two authentication codes via email and SMS.
The demo user inputs the authentication codes into the screen and clicks on, Check.