Keycloak (API Connector)
- Joachim Maksim (Unlicensed)
- Silje Birkeland Eriksen
- Mari Fuglem
Start setup in Kantega SSO Enterprise
To add a Keycloak API Connector, navigate to KSSO and click Cloud provisioning. Select Keycloak in the “API Connectors” section of the dropdown.
The below form should appear:
As shown in the screenshot, you will need some items (which we will grab and make notes of during the setup).
Go to Keycloak to get the setup needed!
Configure Keycloak
EXTERNAL
Configure realm in Keycloak
Log into the Keycloak console. Select the Keycloak realm you wish to connect to, or if necessary, create a new realm.
If you have multiple realms, you can select a realm using the dropdown in the upper left corner of the Keycloak console. In the image below, the realm is set to “Master”.
Navigate to the Realm settings page (found in the menu on the left-hand side). Copy the name (not the display name) of the realm and paste it into the Realm field on the KSSO Keycloak API Connector setup page.
Realm name is case sensitive!
Use admin-cli in Keycloak
In the left-hand navigation menu, click Clients. From the list of clients, locate and click on the client named admin-cli.
In the admin-cli client configuration screen, click the Settings tab (this is usually selected by default). Scroll down to the Capability Config section. Ensure that the option Client authentication is enabled (toggle is switched ON).
Navigate to the Credentials tab. In the Client Authenticator dropdown, ensure the selected option is Client Id and Secret. Below the dropdown, find the Client Secret field. Click Copy (or manually copy the value, depending on your Keycloak version). Paste this value into the Client Secret field on the KSSO Keycloak API Connector setup page.
Return to the Settings tab. Find the Client ID field (usually at the top of the page). Copy the Client ID value. Paste this value into the Client ID field on the KSSO Keycloak API Connector setup page.
Client ID is case sensitive!
Configure user in Keycloak
Retrieving user credentials
To configure a user for use with the Keycloak API Connector, navigate to the Users page from the left-hand menu in the Keycloak Admin Console. You can either select an existing user from the list or create a new one by clicking the Add user button. When creating a user, make sure to enter a unique username along with an email address, first name, and last name. These fields are required for the authentication process to work properly.
Once the user is created or selected, ensure they are enabled. Copy the username and paste it into the Username field in the KSSO Keycloak API Connector setup page.
Next, go to the Credentials tab under the user’s profile. Press the Set password button, and enter a new password it in both the Password and New password Confirmation fields. Make sure the Temporary option is toggled off to prevent the user from being forced to change the password at next login. Save the password and copy it into the Password field in the KSSO Keycloak API Connector setup page.
Username and password are case sensitive!
Configuring user permissions
To ensure the user has the appropriate permissions to access the Keycloak admin API, specific roles must be assigned.
In the user's profile, navigate to the Role Mappings tab and click the Assign Role button. In the filter dropdown to the left, select Filter by Clients.
From the list of available roles, assign the following role:
view-users
Assigning the view-users role implicitly grants the user additional effective roles, including:
query-groups
query-users
Configure URI Scheme in Keycloak
The URI scheme defines how the Keycloak API is accessed and typically includes two components:
Host — The domain or IP address where Keycloak is hosted. This may include a port (e.g., :8080) if Keycloak is not running on the default HTTP or HTTPS port.
Base Path — If Keycloak is deployed under a specific path (e.g., /auth), that path must be included.
For example:
http://localhost:8080
http://keycloak.example.com
http://keycloak.example.com/auth
Enter the URI into the Keycloak URI scheme field on the KSSO Keycloak API Connector setup page.
Finding the URI scheme in Keycloak
If you're unsure of your Keycloak URI scheme, you can easily locate it through the Keycloak Admin Console:
From the left-hand menu, navigate to Realm Settings.
In the General tab (selected by default), locate the Endpoints section.
Click on OpenID Endpoint Configuration.
This will open a new tab displaying a JSON object containing various endpoint details. Look for the value associated with the issuer key. This value will look something like:
https://keycloak.example.com/realms/my-realm
To determine your URI scheme, remove the realm-specific part of the path. Specifically, remove everything from realms/{realmid} onward. The remaining portion is your URI scheme.
To exemplify, if the issuer value is:
https://keycloak.example.com/realms/master
the URI Scheme is:
https://keycloak.example.com
Complete the setup in Kantega SSO Enterprise
Check that everything looks good in KSSO Keycloak API Connector setup page and submit your setup
Add user directory
A user directory must be created to hold users and groups from Keycloak. Verify the configuration before adding the user directory. Check “Use nested groups” if you use nested groups in Keycloak.
