OpenID Connect is a user identity mechanism built on top of the OAuth 2.0 protocol that provides modern, secure and intuitive single sign-on (SSO) for end-users using the identity provider (IdPs) – Keycloak.

Role required: admin.

Set up OIDC

To create an OpenID Connect, complete the following steps:

  1. Navigate to Single Sign-On (SSO) → OIDC Settings.
  2. Click New and fill in the fields.
  3. Click Save or Save and exit to apply the changes.

OIDC Setting form fields

FieldMandatoryDescription
NameYSpecify a name of the connection.
URL IdPY

Specify the URL of the authorization server. For example, https://kk-your-instance.simpleone.ru/. 

The link redirecting from the instance to authorization in Keycloak will look like this:

https://{{keycloak_url}}/realm/{{realm}}/protocol/{{protocol}}/auth?response_type=id_token&id_token={{token}}&client_id={{kk_client_id}}>&redirect_uri={{redirect_uri}}&scope={{scope}}&state={{state}}&nonce={{nonce}}


RealmYSpecify the name of the Keycloak realm.
Client IDYSpecify the application name that is registered in Keycloak.
User fieldY

Specify a field in the User (user) table containing information for user identification. Available options:

  • Email
  • Login
Ignore case sensitivityN

Select the checkbox to ignore a user login and email case during the authorization.

However, Keycloak always returns data in lower case. In case there are users with the same emails but in a different case, Keycloak authorizes the one whose email matches the returned data.

SimpleOne has two users with similar emails:

  1. JohnDoe@mail.com
  2. johndoe@mail.com

Keycloak returns johndoe@mail.com, so user 2 is authorized.

  • If the checkbox is selected and the simple.login.username.sensitivity.enabled property is set to true, none of the users will be authorized.


Redirect URIY

Specify a callback link. After a user is authorized in Keycloak, it redirects the user to the specified link and adds the following parameters to the link: id_token, access_token, session_state, state, token_type, expires_in.

Backlink example with Keycloak:

https://{{redirect_uri}}#state={{state}}&session_state={{session_state}}&id_token={{id_token}}&access_token={{access_token}}&token_type=Bearer&expires_in={{expires_in}}

When the checkbox is selected and the value in the Redirect URI field differs from the value of the simple.welcome_page.url property, the value of the property is updated.

ActiveN

Select the checkbox to activate the connection.

  • Only one connection record can be active. After the current record is saved, the previous active record is deactivated.
  • If the Active checkbox is cleared, the value of the simple.welcome_page.url system property becomes empty by default.


Enable user creationNSelect the checkbox to enable the autoprovision. Users that have no user accounts in SimpleOne, but are authorized in Keycloak, are automatically sign up in the instance.
ScriptY

Add a script to set the user field mapping between Keycloak and the SimpleOne instance. There is a default script that maps two mandatory fields: email and login. 


Keycloak and SimpleOne instances must have TLS/SSL certificates configured to connect on port 443.

IdP Certificates

All generated public certificates for connections are stored in the IdP Certificates (idp_certificate) table. The certificates with a unique URL IdP and Realm for each OIDC Setting record can be found in the related list on the form.

You can only update certificates for an active OIDC setup using one of the following methods:

  • By clicking Update certificates on the OIDC Setting form.
  • When a user is authorized or sign up. If the corresponding certificate was not found, the certificates are automatically updated.

IdP Certificate form fields

FieldDescription
kidThe unique ID of the certificate key.
RealmThe name pf the Keycloak realm.
JSONJSON that contains the information about the public certificate.

Update algorithm

After starting the process of updating certificates, the following happens:

  1. A GET /certs request is sent based on the URL IdP and Realm fields.
  2. Depending on the value of the kid field:
    1. new certificates are added.
    2. existing ones are not updated.
    3. those certificates that are not in the request response are removed and stored in Record Deletion Log.

If the values of the OIDC Setting fields are set incorrectly, the system displays the following message:

The update of the certificates is failed. Check the settings of the connection.

Check the settings and try again.

When an OIDC Setting record is deleted, the system checks whether there are records with similar URL IdP and Realm values. If there is no matching record, the related certificates are removed.