You are viewing an old version of this page. View the current version.

Compare with Current Restore this Version View Page History

« Previous Version 4 Current »

Prerequisites

The main idea of this project is to create application which manages user's profiles and its bunch of back-end and front-end are configured
via configuration of back-end. So if certain properties are changed on back-end side, then front-end is changed in appropriate way
to match configuration of back-end. One of such configured flows is Login flow which is described in this documentation.

There are two possible login flows: one-step login and several steps login. The flow depends on property
systemBehaviorConfigurations/multifactorAuthentication/multifactorAuthSystemEnabled. Hence, if it's set to true,
then several step login flow is chosen for the system (both on front-end and back-end sides). Otherwise, one-step
login is performed. Also login as one-step action performed in case of using third-parties (Google, Facebook etc.)

Firstly, login via third-parties is described.

Login via third-party (Google, Facebook etc.)

An ability to login into the system can be performed in several different ways depending on configuration of back-end.
Default configuration allows to perform login:

  • via email;
  • via phone number;
  • via Google;
  • via Facebook;
  • via Okta;
  • via Twitter.  

Login via third-parties (Facebook, Google etc.) can be disabled for the system. In such case 
there are no appropriate buttons on front-end and also back-end doesn't process requests for appropriate endpoints.

To disable desired option, e.g. Facebook, an appropriate property must be set to desired value in application.yaml 
in section systemBehaviorConfiguration/oauth2. For Facebook it's systemBehaviorConfiguration/oauth2/facebook 
and the value false.

As mentioned above, such changes lead to changing of system's behavior both on front-end and back-end sides.

Changes on front-endChanges on back-end
If login option (facebook, google etc.) disabled, then
an appropriate button disappears
from login page		If login option (facebook, google etc.) disabled, then
endpoint for appropriate option (e.g. /api/v1/login/facebook)
isn't registered and exposed, so an attempt to reach it leads to error
with the message "No handler."

Listed login options can be enabled or disabled in any combinations.
If you want to add another third-party for login flow, please, refer to the article sign in/up with social networks.

Endpoint's path for a third-party has the following pattern: /api/v1/login/thirdParty'sName.
These endpoints are created and exposed by Spring, but redirect URI can be configured via application.yaml.

Several steps login flow

The main difference between one-step login and several steps login is requirement to provide a one-time tokens
for user's enabled MFA (multi-factor authentication) options for additional security. So, if user has enabled MFA
for email, then only one-time token which is sent to user's email should be provided, if both email and phone number
MFA enabled, then two one-time tokens should be provided by user to complete login operation.

Login flow: the 1st step

To choose several steps login, login operation must be performed via email or phone number. Also, application.yaml must have the following configuration:

application.yaml
...
systemBehaviorConfigurations:
  multifactorAuthentication:
    multifactorAuthSystemEnabled: true
...

Path: /api/v1/login

Request and response structures

If login via email/phone number are chosen, then request must have the following structure:

request
{
	"userKey": "email/phone number",
	"password": "user password"
}


In such case, response contains listed below information:

response
{
  "processingId": "processing ID of the operation",
  "email": "user's email",
  "phoneNumber": "user's phone number",
  "enabledMfaSteps": {
    "emailVerificationEnabled": true|false,
    "phoneNumberVerificationEnabled": true|false,
    "googleAuthenticatorVerificationEnabled": true|false
  }
}

Login flow: the 2nd step

Path: /api/v1/token/login

The next step in several steps login flow is to request from the system one-time tokens for user's enabled MFA options.
So, depending on enabled MFA options request and response have the following structures:

request
{
	"destination": "EMAIL|PHONE_NUMBER",
	"processingId": "processing ID from the previous step"
}
response
{
  "destination": "user's email or phone number, depends on destination chosen in request",
  "expiration": "30 MINUTES"
}


After requesting and getting one-time tokens for all enabled MFA options, the final step of login can be performed.

Login flow: the 3rd step

Path: /api/v1/login/verification

This step is final action which should be performed to successfully finish several steps login flow.
On that step one-time tokens for all user's enabled MFA options which the user has got must be provided.
The request and response have structures, listed below. Note, that MFA option is disabled for user, then
null must be passed as its value.

request
{
	"userKey": "user key entered on the first step",
	"processingId": "processing ID from the first step",
	"oneTimeTokens": {
		"emailToken": "email one-time token"|null,
		"smsToken": "phone number one-time token"|null,
		"googleAuthenticatorToken": "google authenticator one-time token"|null
	}
}
response
{
  "accessToken" : "access token",
  "refreshToken": "refresh token"
}

As access and refresh tokens are handled by front-end, then for user after the last step follows redirect to main page.



If you have any questions regarding login flow or any other questions, feel free to contact Diakonov Serhii (s.dyakonov@knubisoft.com) or Kostenko Vadym (v.kostenko@knubisoft.com)