Skip to main content
Version: 1.21.3

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
    simple.sso.activesimple.welcome_page.urlsimple.sso.priority_over_welcome_page
    falsefalsefalse
    falsefalsetrue
  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).

  1. 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).

  1. 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:

Ignore case sensitivitysimple.login.username.sensitivity.enabledResult
Yestrue/falseThe values in the system and from Keycloak are the same. The user is authorized.
Notrue/falseThe values in the system and from Keycloak do not match. The user is not authorized.

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 fieldSimpleOne fieldData type
preferred_usernameusernamestring
given_namefirst_namestring
family_namelast_namestring
emailemailstring

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.