On his first login after an administrator has set his account with MFA the user will be asked to enroll on a 4 steps form :
Here the client is told that he is to enroll in MFA and use is mobile phone as a security piece of evidence.
Here the client is told to download Google Authenticator application, he is provided links to Android and IOS application stores.
Here the client is asked to use the Google Authenticator application to register his account either by scanning the QR code or manually entering the key.
Here the client is told to check his first TOTP code to verify the enrollment process. If validation succeed he will be logged in with a valid MFA and token.
Once a user is properly enrolled with MFA he will need is mobile device with Google Authenticator to log in. The login procedure is splitted in 2 steps with MFA :
1.2.
This article describes, how to enable and use multi factor authentication (MFA) from the backend point of view.
Currently there is just one additional authentication factor implemented, making this effectively a two factor authentication (2FA).
We choose Google Authenticator, a "Time-based One-time Password" (TOTP) implementation.
As an authenticated user, that has editing rights to the targeted user use
POST
[users] /users/{userId}/googleauth
The call of this endpoints sets three flags for the user: googleAuthAccount, googleAuthEnabled and googleAuthPending. They indicate, that an MFA account has been set up, that MFA is enabled, and that the "enrollment" is pending.
With DELETE you would switch it off, again. All flags were then set to "false". the account is deleted.
WIth PUT you can temporary enable/disable the MFA, without deleting the account.
After switching on the MFA, a shared secret has to be exchanged during the first login process:
In the first step, we login with user name and password:
POST
[app-login-controller] /app/auth
A specific appConfig is returned for MFA users:
token is not the regular authentication token, but a special factor-1 token. It can only be used to authenticate for the endpoint, that we call in the next step.
nextAuthentications contains a list of names for the next authentication factor. Currently this list contains just the one implemented factor GOOGLE_AUTH.
secret is the shared secret, that is used as a key to create a new account in the google authenicator mobile app. This secret is only shown during "enrollment", when the "googleAuthPending" flag is set for that user.
After creating the account, the mobile app shows verification codes, that keep changing after a short time interval.
We use the above factor-1 token and the verification code, that the mobile app currently shows for new account.
POST
[app-login-controller] /app/mf-auth
After this step, the user is successfully logged in, meaning, the returned token is a regular token.
The "googleAuthPending" flag for this user s now set to "false", googleAuthEnabled is still "true"
The MFA logins from now on don't exchange the secret anymore. Anything else works the same.
POST
[app-login-controller] /app/auth
We use the above factor-1 token, and the verification code, that the mobile app currently shows.
POST
[app-login-controller] /app/mf-auth
After this step, the user is successfully logged in, meaning, the returned token is a regular token.