In comparison to our previous, fully API-based implementation, current auth-service version fully supports OAuth2 PKCE-based authorization flow and thus contains UI (Frontend) part to interact with users and backend API to interact with applications (Web or Mobile). The only supported way to authenticate users is an interactive login: this is why auth-service now contains UI part.

Not that at first new login attempt each user should empty cache.

OAuth2 specification can be found here:

• OAuth2 RFC (Common): https://tools.ietf.org/html/rfc6749

• OAuth2 PKCE RFC: https://tools.ietf.org/html/rfc7636

OAuth2 specification for mobile and SPA applications:

• OAuth2 for Native Apps: https://tools.ietf.org/html/rfc8252

General OAuth2 flow for interactive user login

Prerequisites:

1. Application owner should generate unique application “clientId” to be identified in the OAuth system.

2. Web application should contain callback page/URL to catch data from OAuth2 UI. Mobile application should generate callback URL according to the one of the schemes described in the chapter 7 of “OAuth2 for Native Apps” specification.

Flow:

1. User opens web or mobile application. If it’s not logged in, user can press some button to log in or the application can start log in process automatically. Application generates random unique code_verifier string and remembers it.

2. User is redirected to OAuth2 UI webpage in existing browser tab/window, popup window, custom browser tab (in mobile applications). Application sends following parameters in the QUERY_STRING of OAuth2 URL:

   • redirect_uri – Fully-qualified URL of the callback page

   • client_id – Unique application identifier

   • code (code_challenge) – string that contains code_verifier encryprted according to following scheme: code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) . See OAuth2 PKCE RFC for more details.

3. User enters the credentials (or uses “Sign-in with Google” button if enabled)

4. If enabled: user comes through two-factor authentication process

5. OAuth2 UI generates unique authorization code, adds it as a “code” parameter to the callback “redirect_uri” URL and redirects user back to the application using callback URL.

6. Application reads authorization code from the URL.

7. Application sends client_id, redirect_uri (from step 2), code_verifier (from step 1) and authorization_code (from step 5) to the token endpoint of the OAuth2 API.

8. Token endpoints validates parameters and generates access_token and refresh_token as earlier.

9. Application performs requests to API using existing Authorization/Bearer scheme.

OAuth2 supports only interactive user login flow. It means that every application (web, desktop or mobile) is strongly advised to use the flow according to “OAuth2 for Native Apps” RFC using OAuth2 UI of auth-service.

But if you need to avoid interactive login for some reason, your application needs to simulate functionality of OAuth2 UI and call OAuth2 API sign-in endpoints directly with extended list of parameters (see Swagger docs for details) instead of steps 1-4. After receiving API response with redirect_uri parameter, application should follow the flow starting from step 5.