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 following system properties. Depending on the values of these properties, the user is redirected to the corresponding URL:

   • simple.sso.active
   • simple.welcome_page.url
   • simple.sso.priority_over_welcome_page
   /login

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

   /ssoLoginUrl

   simple.sso.active	simple.welcome_page.url	simple.sso.priority_over_welcome_page
   true	false	false
   true	false/null	true
   true	true (the value is specified)	true

   /welcomePageUrl

   simple.sso.active	simple.welcome_page.url	simple.sso.priority_over_welcome_page
   false	true (the value is specified)	false
   false	true	true
   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 and 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, 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 simple.welcome_page.url system property specifies the URL of the Keycloak authorization widget, the user is redirected to Keycloak or the /logout page. The error is written 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. The error is written to the Exception Log (sys_exception_log).

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

note

If the parameter values do not match, the user is redirected to the /logout page. The error is written 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 decryption, the user is redirected to the /logout page. The error is written to the Exception Log (sys_exception_log).

2. The system finds the IdP certificate by the unique key ID (kid), which is 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. The error is written to the Exception Log (sys_exception_log).

JWT validation and Signature verification

---

When a certificate with the kid is found for 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. The error is written to the Exception Log (sys_exception_log).

Authorization

---

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

caution

Keycloak returns email or username values in lower case. For example, the value for the cases below is user1.

Possible cases:

User1

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

user1

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

Two users with similar usernames: User1 и user1

Ignore case sensitivity	simple.login.username.sensitivity.enabled	Result
Yes	true	The values of both usernames match the value from Keycloak. As a result, none of the users is authorized, the system displays an error.
No	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 field mapping:

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.