Keycloak Integration with OpenID Connect
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:
- Navigate to Single Sign-On (SSO) → OIDC Settings.
- Click New and fill in the fields.
- Click Save or Save and exit to apply the changes.
OIDC Setting form fields
| Field | Mandatory | Description |
|---|---|---|
| Name | Y | Specify a name of the connection. |
| URL IdP | Y | 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}} |
| Realm | Y | Specify the name of the Keycloak realm. |
| Client ID | Y | Specify the application name that is registered in Keycloak. |
| User field | Y | Specify a field in the User (user) table containing information for user identification. Available options:
|
| Ignore case sensitivity | N | Select the checkbox to ignore a user login and email case during the authorization. |
| Redirect URI | Y | 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. |
| Active | N | Select the checkbox to activate the connection.
|
| Enable user creation | N | Select the checkbox to enable the autoprovision. Users that have no user accounts in SimpleOne, but are authorized in Keycloak, are automatically signed up in the instance. |
| Script | Y | 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. |
-
If the Ignore case sensitivity checkbox is not selected and the simple.login.username.sensitivity.enabled property is set to true, the check is case-sensitive.
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:
Keycloak returns johndoe@mail.com, so user 2 is authorized.
-
If the Ignore case sensitivity checkbox is selected and the simple.login.username.sensitivity.enabled property is set to true, none of the users are authorized.
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 signed up. If the corresponding certificate was not found, the certificates are automatically updated.
IdP Certificate form fields
| Field | Description |
|---|---|
| kid | The unique ID of the certificate key. |
| Realm | The name of the Keycloak realm. |
| JSON | JSON that contains the information about the public certificate. |
Update algorithm
After starting the process of updating certificates, the following happens:
- A GET /certs request is sent based on the URL IdP and Realm fields.
- Depending on the value of the kid field:
- new certificates are added.
- existing ones are not updated.
- 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.