TOTP

Gateway UIHeadless

How to choose your integration strategy?

Learn to activate your Multi-Factor Authentication (MFA). We provide a TOTP strategy for an Organization on your Login Gateway with your customized User Interface : from the activation of the TOTP to the final login try. Or embed directly in your app with Headless Integration strategy here

Watch the video guide

• Quickstart
• 15 min

View example

Introduction

A TOTP is a Time-based One-Time Password, which allows

The fallback content to display on prerendering

to securely access a web

The fallback content to display on prerendering

thanks to a second security factor. Indeed, after the

The fallback content to display on prerendering

logs in, he will receive a unique code by SMS or via a TOTP App. Once entered into the application, this code will enable the user to access the desired service. This additional security feature is becoming increasingly popular, making traditional authentication more secure, and less sensitive.

However, it is important to ensure a number of security measures, for example, that the code is only usable for a short period of time.

What we will build together

1. Configure a TOTP
   The fallback content to display on prerendering
2. Add TOTP to your
   The fallback content to display on prerendering

Prerequisites

1. A Cryptr account
2. An IdP account from a Cryptr-supported identity provider to help you configure an IdP instance for your development

Step 1: Integrate to your Application

note

If you have already integrated Cryptr in an

The fallback content to display on prerendering

, you can directly go to Step 2

Start integrate to your favourite techno

Login

The fallback content to display on prerendering

Your login

The fallback content to display on prerendering

is almost the same whatever the authentication strategy, only the chosen authentication strategy changes the

The fallback content to display on prerendering

. Within the

The fallback content to display on prerendering

of the TOTP

The fallback content to display on prerendering

, cryptr manages for you the various exchanges with the TOTP solutions of your customers, as well as their specificities.

Single Page App

Angular

React

Vue

React native

Backend Integration

Laravel

Rails

Go

Flask

Django

Step 2: Configure your first TOTP Connection

The Cryptr API

The fallback content to display on prerendering

object definitions

• Organization: An Organization represents a business customer or partner in your Cryptr service.
• TOTP Connection: You can create or update TOTP
  The fallback content to display on prerendering
  preferences for an Organization (usualy your Enterprise customer). Everything to setup for the TOTP.

Environment variables

It is important that your Cryptr

The fallback content to display on prerendering

remains secret, and therefore is defined as a CRYPTR_API_KEY environment variable at the start of your

The fallback content to display on prerendering

. The ID of your

The fallback content to display on prerendering

CRYPTR_CLIENT_ID must also be defined.

CRYPTR_API_KEY=79cef058-530c-4c19-a12d-ff57ff5e592b
CRYPTR_CLIENT_ID=b7bde828-4df1-4f62-9a3a-d1541a2fc9e4

info

If you don't have

The fallback content to display on prerendering

, please create an account

danger

Login to your Cryptr space to create an

The fallback content to display on prerendering

. Cryptr does not keep the created

The fallback content to display on prerendering

, keep it with care. You can always create a new one in case of loss, or blacklist your

The fallback content to display on prerendering

in case of compromise.

Create your Users directory

The Organization owner

An Organization is the

The fallback content to display on prerendering

of your customers with a strong identifier we called the

The fallback content to display on prerendering

. All created users will be stored in dedicated environnment for this customers, with a unique identifier to scope your actions in connexion with this customers. So we need to create the place where we'll store users & configuration of this new customer, then get the identifier.

Create a new Organization with a name:

cURL

curl -X POST ${cryptr_service_url}/api/v2/organizations \
  -H "Authorization: Bearer your-access-token-from-client-id-and-secret" \
  -d name="Communitiz App" \
  -d email_domains[]="communitiz-app"

Kotlin

val organizationResponse = cryptr.createOrganization(
  name = "My company name",
  allowedEmailDomains = setOf("my-company.com")
)

Now we get the domain of our new Organization, here communitiz-app is the domain identifier. Now, each time a new user will be created from our TOTP, or we add a new configuration, it will be stored in a clean separated

The fallback content to display on prerendering

.

We can fetch the users from this Organization:

cURL

curl "${cryptr_service_url}/api/v2/org/${org_domain}/users" \
  -d page=${page}
  -d per_page=${per_page}

Kotlin

val listing = cryptr.listUsers(
  orgDomain = orgDomain,
  // Optional, size of the page
  // perPage = perPage,
  // Optional your current page
  // currentPage = currentPage
)

Of course, at this time our list is empty. To see more about Organization and User, please have a look at our Organization API Reference and User API Reference. We can store the

The fallback content to display on prerendering

of our Organization, and attach a TOTP

The fallback content to display on prerendering

to this. But we need to handle the user

The fallback content to display on prerendering

.

Setting up a TOTP connection

Let's configure an TOTP

The fallback content to display on prerendering

for a given Organization, which wants to add a security layer of authentication via TOTP.

The fallback content to display on prerendering

can be configured via the Cryptr

The fallback content to display on prerendering

or the back office.

When an Organization is created, Cryptr automatically prepares two environments for you: a sandbox and your default environment (for your production).

TOTP

The fallback content to display on prerendering

activation

With a created Organization, and an

The fallback content to display on prerendering

, we can create TOTP Conneciton between your

The fallback content to display on prerendering

& your customer (the Organization).

In fact, the TOTP connection is already created by default, but is not activated. Let's see how to activate it.

Create a new TOTP

The fallback content to display on prerendering

type.

cURL

curl -X PUT ${cryptr_service_url}/api/v2/org/${org_domain}/totp-connection \
    -d active=true

Kotlin

val resp = cryptr.createTotpConnection(
  orgDomain = 'communitiz-app'
)

Manage the Totp

Here are the other possible actions for managing totp

The fallback content to display on prerendering

:

Update the Totp Connection

This request will help you to update the Totp params.

cURL

curl -X PUT ${cryptr_service_url}/api/v2/org/${org_domain}/totp-connection \
  -d active=true

Kotlin

val resp = cryptr.updateTotpConnection(
    orgDomain = 'communitiz-app',
    active = true
)

Deactivate the Totp Connection

cURL

curl -X PUT ${cryptr_service_url}/api/v2/org/${org_domain}/totp-connection \
  -d active=false

Kotlin

val resp = cryptr.deleteTotpConnection(
    orgDomain = 'communitiz-app'
)

Retrieve the Totp Connection

cURL

curl "${cryptr_service_url}/api/v2/org/${org_domain}/totp-connection"

Kotlin

val resp = cryptr.getTotpConnection(
    orgDomain = 'communitiz-app'
)

You are now able to view the params of your Totp

The fallback content to display on prerendering

.

Users enrollment

First login (TOTP Mobile APP Method)

To be able to use TOTP, your users will have to be enrolled.

To do this, when your TOTP

The fallback content to display on prerendering

is activated and they initiate a login process, they will be redirected to a page containing a QR Code. This QR code will enable them to enroll (in the case of the TOTP Mobile APP method).

Once scanned on their TOTP mobile application (FreeOTP, Google Authenticator...) they can click on a button to access the next page. On this page, they'll be asked to enter their first TOTP (the one given to them by their application). Once this has been done and the process validated, your users will be enrolled.

If the TOTP is valid, users will then see a page where five recovery codes are displayed. These codes can be downloaded by the user as a text file and used if the user loses access to their TOTP application.

Users will then be prompted to confirm the download of their recovery codes. Once validated, a session is opened.

info

These recovery codes must be stored as carefully as a password (they must not be divulged or stored on the same device as the TOTP application ...).

Moreover, they are single-use, so a user can only use recovery codes 5 times. Once this number has been exceeded, you'll need to force the enrollment of your user. Finally, codes can only be used once in a 24-hour period.

Subsequent login

In the case of an already enrolled user, the next time they log on, they'll only be asked to enter a TOTP code.

API endpoint used in this guide

You can read more about

The fallback content to display on prerendering

during this guide with our API Reference.

Endpoints

POST /api/v2/organizations
Create a new organization to attach a TOTP
GET /api/v2/org/:org_domain/users
Get the users listing of an organization
PUT /api/v2/org/:org_domain/totp-connection
Create a totp connection