API Multi-Factor Authentication

Introduction

Overview

In this document, we will guide you through the Acreto Multi-Factor Authentication mechanism, as implemented in Acreto API for administrative needs.

Acreto’s Multi-Factor Authentication uses Time-based One-Time Passwords (TOTP) and was tested with the Google Authenticator app.

Acreto’s Multi-Factor Authentication consists of the following steps:

  1. initial configuration
  2. using two-factor authentication

Prerequisites

Before you start, you will need to:

Conventions

In this document, we follow conventions and use variables as defined in API Quick start.

TOTP initial configuration

To configure TOTP multi-factor authentication for a user, you need to follow the following process:

  1. Log in as the user
  2. Generate TOTP keys using POST ​/users​/{username}​/otp endpoint
  3. Add Acreto to your Google Authenticator by scanning generated QR code
  4. Activate multi-factor authentication by providing user-supplied verification code to PATCH ​/users​/{username}​/otp endpoint

Initial configuration example

Generate TOTP keys

Request:

curl -X 'POST' \
  'https://api-is-rock-solid.acreto.net/v2/users/user%40email.com/otp' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d ''

Response:

{
  "barcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGYUlEQVR4nOyd0Y7bOgxEsxf5/1/uRQu4SAjRHF........rkJggg==",
  "secret": "P3YOQUQT1234O2S5FNDOAMMBM7NGFQKG",
  "url": "otpauth://totp/Acreto:user@domain.com?algorithm=SHA1&digits=6&issuer=Acreto&period=30&secret=P3YOQUQT1234O2S5FNDOAMMBM7NGFQKG"
}

Display QR code to the user

<html>
<body>
 <img src="data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGYUlEQVR4nOyd0Y7bOgxEsxf5/1/uRQu4SAjRHF........rkJggg==" />
</body>
</html>

Activate MFA using verification code

Request:

curl -X 'PATCH' \
  'https://dev-api-never-works.acreto.net/v2/users/user%40email.com/otp' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "123456"
}'

Response: HTTP status 204.

Using multi-factor authentication

To correctly support multi-factor authentication, your app needs to detect HTTP status code 424. Once such a code is received, the app should resend the failed request with an additional HTTP Header, X-OTP, containing TOTP code generated by the TOTP app (Google Authenticator).

Login without one-time password

Request:

curl -ik -X 'POST' \
  'https://dev-api-never-works.acreto.net/v2/auth/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "password": "******************",
  "username": "user@domain.com"
}'

Response (with headers):

HTTP/1.1 424 Failed Dependency
Content-Type: application/json
Vary: Origin
X-Request-Id: f4a12ef8-5134-c510-c409-b634ff4e4681
Date: Mon, 10 May 2021 16:31:58 GMT
Content-Length: 146

{"code":16432,"message":"This operation requires multi-factor authentication. Please retry with proper multi-factor authentication infromation."}

As you see, we got HTTP status 424. A request needs to be repeated with X-OTP header included.

Login with one-time password

Request:

curl -X 'POST'   'http://localhost:7010/v2/auth/login'   -H 'accept: application/json'   -H 'Content-Type: application/json' -H "X-OTP: 000000"  -d '{
  "password": "******************",
  "username": "user@domain.com"
}'

Response:

{
  "accessToken":"etgrevfdsr5byu57uj6t57uj657ub76yJh......HkShSxy9wUWMs3C_U5mOZq7vpIG7p73gMCpsDZthn90",
  "customers":
    [
      {"name":"Some Customer","uuid":"b7921abe-28e8-40aa-b527-00586e2ce3f1"},
      {"name":"Some Customer 2","uuid":"b7921abe-28e8-40aa-b527-00586e2ce3f1"}
    ],
  "expiry":600
}