Two Factor Authentication

TFA and Login

Login

Case 1: When user TFA setup is required

Upon logging in tfa-auth cookie is set instead of qt-auth.

tfa-auth cookie is used to make /api/auth/v1/tfa/qr-code and /api/auth/v1/tfa/enable API requests

The login api returns 200 with message and code.

Sample CURL

curl -X POST \
  http://<publisher-website-url>/api/auth/v1/login \
  -H 'Host: <publisher-host>'\
  --data-raw '{"username": "Somename", "password": "password"}'

Response

Status: 200

Body: {
    "code": "tfa-setup-is-required",
    "message": "TFA setup is required for this user"
}

Case 2: When user is TFA enrolled

If the user had enabled tfa, upon logging in tfa-auth cookie is set instead of qt-auth.

tfa-auth cookie is used to make /api/auth/v1/tfa/validate API request

The login api returns 200 with message and code.

Sample CURL

curl -X POST \
  http://<publisher-website-url>/api/auth/v1/login \
  -H 'Host: <publisher-host>'\
  --data-raw '{"username": "Somename", "password": "password"}'

Response

Status: 200

Body: {
    "code": "tfa-validation-is-required",
    "message": "TFA validation is required for this user"
}

---

Case 3: TFA with social login

Login URL format: <publisher-url>/api/auth/v1/login?auth-provider=google&redirect-url=<redirect-url>

After loggging in to social provider, user will be redirected to given redirect-url with query param code indicating TFA status for the user and tfa-auth cookie is set

Possible code values:

1. tfa-validation-is-required
2. tfa-setup-is-required

Sample redirect URL with code: <some-redirect-url>/<some-path>?code=tfa-validation-is-required

Get two factor auth(tfa) secret and qr-code

The user needs to be logged it. They need to have qt-auth cookie. A GET call is made to /api/auth/v1/tfa/qr-code, this api returns

• qr-code-url: The url for qr-code
• secret-key: The key used to valid tfa code

Usage

Sample CURL

curl -X GET \
  http://<publisher-website-url>/api/auth/v1/tfa/qr-code \
  -H 'Cookie: tfa-auth=<tfa-auth> || qt-auth=<jwt>' \
  -H 'Host: <publisher-host>'

Response

Status: 200

Body: {
    "qr-code-url": "http://chart.apis.google.com/chart?cht=qr&chs=300x300&chl=${xyz}&chld=H|0",
    "secret-key": "FU7UCYTPFJ6HYSGFS"
}

---

Enable two factor auth(tfa)

The user needs to be logged in. They need to have qt-auth cookie. A POST call is needed made to /api/auth/v1/tfa/enable, with body containing keys

• otp: The code from the authentication app, where the app is set
• secret-key: The key used to valid tfa code, that was returned by /api/auth/v1/tfa/qr-code

Usage

Sample CURL

curl -X POST \
  http://<publisher-website-url>/api/auth/v1/tfa/enable \
  -H 'Cookie: tfa-auth=<tfa-auth> || qt-auth=<jwt>' \
  -H 'Host: <publisher-host>'\
  --data-raw '{"secret": "FU7UCYTPFJ6HYSGFS", "otp": "228072"}'

Response

Status: 200

Body: { message: "User TFA has been updated." }

---

Validate TFA

Used to validate OTP

• otp: The code from the authentication app, where the app is set

Usage

Sample CURL

curl -X POST \
  http://<publisher-website-url>/api/auth/v1/tfa/validate \
  -H 'Host: <publisher-host>'\
  -H 'Cookie: tfa-auth=<tfa-auth>' \
  --data-raw '{"otp": "171391"}'

Response

Status: 200

Body: {
    "message": "Successfully logged in",
    "user": `User Details`,
    "active-sessions-count": 1,
    "member": `User Details`
}

Reset two factor auth(tfa) - Admin

The request needs to have Admin Access Token. A POST call is needs made to /api/auth/v1/admin/reset-two-factor-auth, with body containing keys

• token: Admin Access Token as generated by /admin/access-token/integrations/<id> api
• user: object containing either user-id (as id) or email (as email)

Usage

Sample CURL

curl -X POST \
  http://<publisher-website-url>/api/auth/v1/admin/reset-two-factor-auth \
  -H 'Host: <publisher-host>'\
  --data-raw '{"user": { "email": "foo@bar.com" }}'

Response

Sample response when two factor authentication for an user has been reset

Status: 204

Sample response when invalid token is sent

Status: 401

Body: { "message": "Invalid Token" }

Sample response when token has expired

Status: 401

Body: { "message": "Token expired" }

---