Authorization via Keycloak

When an unauthorized user opens the authorization form of the agent interface (via a direct link or via a link to a specific record), the system checks for the presence of a SimpleOne access token.

caution

It works for all pages except /side-door and /portal/login.

With a local token

The system makes a GET request to v1/user/me with Bearer Token={access_token} authorization. If the token is valid, the user's data comes in response to the request, and the SimpleOne system authorizes the user.

Without a local token

1. No user data is received in the response of the GET request to v1/user/me.

2. The system makes a GET request to v1/sso/login and checks the values of the system properties described below.

   • simple.sso.active – the property enables the Single Sign-On authorization.
   • simple.welcome_page.url – the property contains a welcome page URL. If the value is set to false, the redirection to the welcome page is disabled.
   • simple.sso.priority_over_welcome_page – if set to true, the SSO login page has the priority over the welcome page.

   The combination of these properties' values defines the page to which the user will be redirected:

   • /login – a default login page without the use of SSO.
   • /ssoLoginUrl – a SSO login page.
   • /welcomePageUrl – the page specified in the simple.welcome_page.url system property.

   The table below contains the combinations of system properties' values required for the redirection to each of the mentioned pages.

   /login

   simple.sso.active	simple.welcome_page.url	simple.sso.priority_over_welcome_page
   false	false or empty	false
   false	false or empty	true

   /ssoLoginUrl

   simple.sso.active	simple.welcome_page.url	simple.sso.priority_over_welcome_page
   true	false or empty	false
   true	false or empty	true
   true	the value is specified	true

   /welcomePageUrl

   simple.sso.active	simple.welcome_page.url	simple.sso.priority_over_welcome_page
   false	the value is specified	false
   false	the value is specified	true
   true	the value is specified	false

3. In case of going to the /<welcomePageUrl> page with the Keycloak authorization widget, the system checks for a SimpleOne access token.

   • There is a local token → the user is redirected to the main page.

   • There is no local token → the system requests the parameters to create a link to Keycloak. If there is an active OIDC Setting record, the system passes state and nonce parameters from the server, generates a link to which the user is redirected and performs a GET request auth?.

     If the link in the simple.welcome_page.url property does not match the value of the redirect link in the OIDC Setting, the users can follow the direct link to the authorization page or page with the widget and log in.

     note

     If there is no active OIDC Setting record and the URL to the Keycloak authorization widget is specified in the simple.welcome_page.url system property, the user is redirected to Keycloak or the /logout page. An error is added to the Exception Log (sys_exception_log).

Check the state parameter

---

1. When redirecting a user back, Keycloak checks for the presence of the state, session_state, id_token, access_token, and expires_in parameters in the URL.

note

If at least one parameter is missing, the user is redirected to the /logout page. An error is added to the Exception Log (sys_exception_log).

2. The system compares the state parameter values received from the Keycloak and SimpleOne servers. If the values match, the value of the server parameter is cleared and the parameters from Keycloak are processed.

note

If the parameter values do not match, the user is redirected to the /logout page. An error is added to the Exception Log (sys_exception_log).

Decrypt JSON Web Tokens (JWT)

---

1. On the server side, the Header and data (Payload) of the JSON web token (JWT) are decrypted using the base64url algorithm.

note

If an error occurs during the decryption, the user is redirected to the /logout page. An error is added to the Exception Log (sys_exception_log).

2. The system checks the IdP certificate by the unique key ID (kid) retrieved from the Header for decrypting the Signature. If a matching certificate is not found, the system parses the values of the URL IdP and Realm fields of the OIDC Setting related record and makes a GET request to /certs.

note

If the second search does not find a certificate for kid, the user is redirected to the /logout page. An error is added to the Exception Log (sys_exception_log).

JWT validation and Signature verification

---

When a certificate with the kid is found for the JWT and Signature validation, the system sets parameter values ​​to the array of variables to validate and verify these parameters and received tokens (id_token and access_token). Using both valid tokens and a public certificate, the system verifies the Signature.

note

If at least one of the tokens is not valid, the user is redirected to the /logout page. An error is added to the Exception Log (sys_exception_log).

Authorization

---

After a successful JWT validation, the system checks on the server side the value of the Login column in the Employee (employee) table against the corresponding value from Keycloak.

Keycloak returns email or username values in lower case. You can define if the case sensitivity should be enabled in the simple.login.username.sensitivity.enabled system property. If the property is set to true, the case of the login symbols is checked at an authorization attempt, and the users with upper symbols in their login will not be authorized via Keycloak since it only returns values in lower case.

Example: There is a user with the user1 username in Keycloak. The table below explains system behavior in different scenarios depending on the value of the simple.login.username.sensitivity.enabled system property. Each tab corresponds to the SimpleOne login of a user attempting to log in, and the third tab illustrates the system response when two users with similar usernames, but with different cases, attempt to authorize at the same time.

User1

simple.login.username.sensitivity.enabled	Result
false	The values in the system and from Keycloak are the same. The user is authorized.
true	The values in the system and from Keycloak do not match. The user is not authorized.

user1

simple.login.username.sensitivity.enabled	Result
false	The values in the system and from Keycloak are the same. The user is authorized.
true	The values in the system and from Keycloak are the same. The user is authorized.

Two users with similar usernames: User1 и user1

simple.login.username.sensitivity.enabled	Result
false	The values of both usernames match the value from Keycloak. As a result, none of the users is authorized, the system displays an error.
true	When checking the values, the username User1 does not match the value from Keycloak. The system checks the value of the next user – user1 who logs in because the values match.

Create users

---

The system signs up users in SimpleOne automatically if they already have an account in Keycloak and the Enable user creation checkbox is selected in OIDC Setting. The server side script handles the preferred_username and email fields from the valid JWT.

A user is created in SimpleOne through the mapping of the following fields:

Keycloak field	SimpleOne field	Data type
preferred_username	username	string
given_name	first_name	string
family_name	last_name	string
email	email	string

If authorization fails, the user receives an authorization error notification and is redirected to the /logout page.

tip

If a user does not have an account in Keycloak but has an account on the SimpleOne instance, the following URL <instance.simpleone.ru>/side-door can be used for authorization.