Login flow configuration

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account.

<h3 style="text-align: left;">Prerequisites</h3>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.<h2 style="text-align: left;">Login via third-party (Google, Facebook etc.)</h2><hr />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:<ul><li>via email;</li><li>via phone number;</li><li>via Google;</li><li>via Facebook;</li><li>via Okta;</li><li>via Twitter.  </li></ul>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. <img class="confluence-embedded-image" draggable="false" width="456" src="/download/attachments/74645544/Screenshot%202023-10-20%20at%2003.11.11.png?version=1&amp;modificationDate=1697762967000&amp;api=v2" data-image-src="/download/attachments/74645544/Screenshot%202023-10-20%20at%2003.11.11.png?version=1&amp;modificationDate=1697762967000&amp;api=v2" data-unresolved-comment-count="0" data-linked-resource-id="74645543" data-linked-resource-version="1" data-linked-resource-type="attachment" data-linked-resource-default-alias="Screenshot 2023-10-20 at 03.11.11.png" data-base-url="https://wiki.knubisoft.com" data-linked-resource-content-type="image/png" data-linked-resource-container-id="74645544" data-linked-resource-container-version="5" title="Profile-API documentation > Login flow configuration > Screenshot 2023-10-20 at 03.11.11.png" data-location="Profile-API documentation > Login flow configuration > Screenshot 2023-10-20 at 03.11.11.png" data-image-height="1608" data-image-width="1386">As mentioned above, such changes lead to changing of system's behavior both on front-end and back-end sides. <table class="wrapped confluenceTable"><colgroup><col /><col /></colgroup><tbody><tr><th class="confluenceTh">Changes on front-end</th><th class="confluenceTh">Changes on back-end</th></tr><tr><td class="confluenceTd">If login option (facebook, google etc.) disabled, then an appropriate button disappears from login page</td><td class="confluenceTd">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 &quot;No handler.&quot;</td></tr></tbody></table>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 <a class="confluence-link" href="/pages/viewpage.action?pageId=68190588" data-linked-resource-id="68190588" data-linked-resource-version="14" data-linked-resource-type="page" data-linked-resource-default-alias="Sign in/up with social networks." data-base-url="https://wiki.knubisoft.com">sign in/up with social networks</a>.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.<h2 style="text-align: left;">Several steps login flow</h2>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.<h2 style="text-align: left;">Login flow: the 1st step</h2><hr />To choose several steps login, login operation must be performed via email or phone number. Also, application.yaml must have the following configuration:<table class="wysiwyg-macro" data-macro-name="code" data-macro-id="04535042-18b7-4c3d-8d68-99e807333a5f" data-macro-parameters="language=yml|title=application.yaml" data-macro-schema-version="1" style="background-image: url(https://wiki.knubisoft.com/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9eW1sfHRpdGxlPWFwcGxpY2F0aW9uLnlhbWx9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>...
systemBehaviorConfigurations:
 multifactorAuthentication:
 multifactorAuthSystemEnabled: true
...</pre></td></tr></table>Path: /api/v1/loginRequest and response structuresIf login via email/phone number are chosen, then request must have the following structure:<table class="wysiwyg-macro" data-macro-name="code" data-macro-id="02ebf848-3afe-448a-93e8-0889535bf7b6" data-macro-parameters="language=js|title=request" data-macro-schema-version="1" style="background-image: url(https://wiki.knubisoft.com/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9anN8dGl0bGU9cmVxdWVzdH0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>{
	"userKey": "email/phone number",
	"password": "user password"
}</pre></td></tr></table> In such case, response contains listed below information:<table class="wysiwyg-macro" data-macro-name="code" data-macro-id="078524bc-9934-4476-8c7d-4d46290d45e1" data-macro-parameters="language=js|title=response" data-macro-schema-version="1" style="background-image: url(https://wiki.knubisoft.com/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9anN8dGl0bGU9cmVzcG9uc2V9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>{
 "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
 }
}</pre></td></tr></table><h2>Login flow: the 2nd step</h2><hr />Path: /api/v1/token/loginThe 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:<table class="wysiwyg-macro" data-macro-name="code" data-macro-id="cdfffd96-a122-41bd-b129-57552c4750c0" data-macro-parameters="language=js|title=request" data-macro-schema-version="1" style="background-image: url(https://wiki.knubisoft.com/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9anN8dGl0bGU9cmVxdWVzdH0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>{
	"destination": "EMAIL|PHONE_NUMBER",
	"processingId": "processing ID from the previous step"
}</pre></td></tr></table><table class="wysiwyg-macro" data-macro-name="code" data-macro-id="fe3e7950-5576-4248-937a-b6ae7bbdd248" data-macro-parameters="language=js|title=response" data-macro-schema-version="1" style="background-image: url(https://wiki.knubisoft.com/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9anN8dGl0bGU9cmVzcG9uc2V9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>{
 "destination": "user's email or phone number, depends on destination chosen in request",
 "expiration": "30 MINUTES"
}</pre></td></tr></table> After requesting and getting one-time tokens for all enabled MFA options, the final step of login can be performed.<h2>Login flow: the 3rd step</h2><hr />Path: /api/v1/login/verificationThis 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.<table class="wysiwyg-macro" data-macro-name="code" data-macro-id="d9de24d9-454f-4a33-94b1-b823c7f4e67e" data-macro-parameters="language=js|title=request" data-macro-schema-version="1" style="background-image: url(https://wiki.knubisoft.com/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9anN8dGl0bGU9cmVxdWVzdH0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>{
	"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
	}
}</pre></td></tr></table><table class="wysiwyg-macro" data-macro-name="code" data-macro-id="ae3a2d46-9486-4309-b16c-439b21a842fb" data-macro-parameters="language=js|title=response" data-macro-schema-version="1" style="background-image: url(https://wiki.knubisoft.com/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9anN8dGl0bGU9cmVzcG9uc2V9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>{
 "accessToken" : "access token",
 "refreshToken": "refresh token"
}</pre></td></tr></table>As access and refresh tokens are handled by front-end, then for user after the last step follows redirect to main page.<h2>One-step login flow</h2><hr />If additional security isn't required, then one-step login flow can be chosen. For that MFA should be disabled for the system. In such case login flow is changed to one-step login. NOTE 1: If you want to have a one-step login flow in the system, then MFA should be disabled for the whole system which affects other operations and makes them less secure, especially User key (email and phone number) recovery flow.NOTE 2: Login via third-parties is configured separately from MFA, so it can be performed in both cases.So application.yaml should be configured as following:<table class="wysiwyg-macro" data-macro-name="code" data-macro-id="8051eb7f-1cb8-42b5-833e-30d0a093e422" data-macro-parameters="language=yml|title=application.yaml" data-macro-schema-version="1" style="background-image: url(https://wiki.knubisoft.com/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9eW1sfHRpdGxlPWFwcGxpY2F0aW9uLnlhbWx9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>...
systemBehaviorConfigurations:
 multifactorAuthentication:
 multifactorAuthSystemEnabled: false
...</pre></td></tr></table>If login is performed via email or phone number with the following configuration, then only one action should be performed for login.Path: /api/v1/login<table class="wysiwyg-macro" data-macro-name="code" data-macro-id="5d423b6f-a44a-47d8-950c-da8b819fd937" data-macro-parameters="language=js|title=request" data-macro-schema-version="1" style="background-image: url(https://wiki.knubisoft.com/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9anN8dGl0bGU9cmVxdWVzdH0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>{
	"userKey": "email/phone number",
	"password": "user password"
}</pre></td></tr></table><table class="wysiwyg-macro" data-macro-name="code" data-macro-id="03e30ae1-ef28-4cae-9541-27fce19c4fec" data-macro-parameters="language=js|title=response" data-macro-schema-version="1" style="background-image: url(https://wiki.knubisoft.com/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6bGFuZ3VhZ2U9anN8dGl0bGU9cmVzcG9uc2V9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>{
 "accessToken" : "access token",
 "refreshToken": "refresh token"
}</pre></td></tr></table> NOTE: As you can see, endpoint with the same path (&quot;/api/v1/login&quot;) has different responses depending on system configuration. It's achieved due to custom logic of @RegisterEndpointCondition annotation, which allows to map different method to the same path depending on configuration. If you have any questions regarding login flow or any other questions, feel free to contact <a class="confluence-link confluence-userlink user-mention" data-username="Diakonov Serhii" href="/display/~Diakonov+Serhii" data-linked-resource-id="57180419" data-linked-resource-version="1" data-linked-resource-type="userinfo" userkey="ff808181813d482c01842ee0d073002e" data-linked-resource-default-alias="Diakonov Serhii" data-base-url="https://wiki.knubisoft.com">Diakonov Serhii</a> (s.dyakonov@knubisoft.com) or <a class="confluence-link confluence-userlink user-mention" data-username="Kostenko Vadym" href="/display/~Kostenko+Vadym" data-linked-resource-id="57180421" data-linked-resource-version="1" data-linked-resource-type="userinfo" userkey="ff808181813d482c01842ee0d09a0030" data-linked-resource-default-alias="Kostenko Vadym" data-base-url="https://wiki.knubisoft.com">Kostenko Vadym</a> (v.kostenko@knubisoft.com)