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" }