Introduction
Keycloak is an open source identity and access management platform, and it provides support for standard protocols like OpenID Connect, OAuth 2.0, and SAML.
In this tutorial, SAML will be used in Keycloak to enable Single Sign-On (SSO) capability with Joget.
This tutorial serves only as a general guide, using minimal-required configurations on Keycloak to enable SSO via SAML protocol with Joget.
To use Keycloak in a production environment, please see Configuring Keycloak for production or other relevant Keycloak guides.
Prerequisites
- Joget server
- Docker
Tutorial Steps
1. Keycloak Installation
To quickly get started on Keycloak and for ease of testing, we recommend installing Keycloak via Docker in your local development environment.
Do follow the guide until the part where you have successfully created a sample user in Keycloak & verify by logging in with this new user credentials in the Keycloak Account Console.
At this point of time after completing the Keycloak installation tutorial, you should have these ready in Keycloak:
- A separate realm called myrealm
- A sample user created and verified able to login
Tip
If your Joget instance currently does not have a license, it is limited to free first 3 users only, sorted alphabetically.
For ease of testing, you can create a sample user with username of cactus-jim for example.
Important Note
In this tutorial, it is presumed that the Keycloak instance will be running and exposed on the same host machine running your Joget instance.
In this case, since the default bundled Tomcat server hosting the Joget platform operates on port 8080 by default, do ensure the deployed Keycloak container does not clash with the same host port.
For example, you can map Keycloak container to expose on host port 8500 or any other non-clashing port instead.
2. Plugin Installation
- Download the SAML Directory Manager Plugin from the Joget Marketplace, and upload the plugin .jar file into your Joget instance.
This plugin's source code is also available in JogetOSS Github. Projects under JogetOSS are community-driven and community-supported, and you are welcome to contribute to the projects. - Then, in Admin Bar → Settings → General Settings → API IP Whitelist, do whitelist external IP addresses. For now, you can allow all public users (using * symbol to indicate "allow all").
This is to allow end user browsers to communicate with the SAML plugin.
- Save the settings.
3. Plugin Configuration
- In Admin Bar → Settings → Directory Manager Settings → Select Plugin, select SAML Directory Manager to start configuring the plugin.
- Copy both values of Entity ID and ACS URL, and temporarily save these values in a convenient place for later use.
These values are required in order to create a valid client in Keycloak.
Do also ensure User Provisioning Enabled option is checked. This will automatically create user accounts for SSO users that does not exist yet in Joget.
- Next, you'll need the IDP Certificate value from Keycloak in order to finish configuring the SAML Directory Manager plugin.
Log into your Keycloak Admin Console, ensure you are currently in myrealm, then go to Realm Settings → Keys, and copy the RS256 Certificate value.
- Paste the RS256 Certificate value in the IDP Certificate field.
- The SAML Directory Manager plugin is a superset of Security Enhanced Directory Manager plugin.
Hence, the remainder of the plugin configurations (e.g.: Default Directory Password Policy, Notification, etc.) is identical, and you can refer to the Security Enhanced Directory Manager documentation. - Save the plugin configuration.
From here onwards, the only remaining configurations to perform are on the Keycloak Admin Console side.
4. KeyCloak Configuration
Creating a client in Keycloak will enable the SSO from the keycloak application.
Open the Keycloak admin console -> Clients-> Create
Please use the following configurations:
Client ID: SAML JOGET API URL
Name: Optional
Description: Optional
Enabled: ON
Consent Required: OFF
Login Theme: Optional
Client Protocol: SAML
Include AuthnStatement: ON
Include OneTimeUse Condition : OFF
Sign Documents: OFF
Sign Assertions: ON
Signature Algorithm: RSA_SHA256
SAML Signature Key Name: CERT_SUBJECT
Canonicalization Method: EXCLUSIVE
Encrypt Assertions: OFF
Client Signature Required: OFF
Force POST Binding: OFF
Front Channel Logout: OFF
Force Name ID Format: ON
Name ID Format: username
Root URL: EMPTY
Valid Redirect URIs: https://joget-Server-URL/jw
Base URL: EMPTY
Master SAML Processing URL: SAML JOGET API URL
IDP Initiated SSO URL Name: SAML JOGET API URL
To test configuration, you can copy the target IDP initiated SSO URL and paste it in incognito mode of browser and login to keycloak, If all is good you will be redirected to Joget home page with login.
The final configuration is the configure the fields.
Open the Mapper tab on the client configuration. Add the Built-in mappings 
You need to define the names for each option so joget will be able to handle the values
Mapping Name | SAML Attribute Name |
X500 surname | User.LastName |
X500 givenName | User.FirstName |
X500 email |
Optional Modifications
Addon SSO button on login page
You can also allow end users to SSO via Keycloak with a convenient button in your Joget login page.
Edit the App Center app, navigate to UI builder -> Settings -> Login Page UI --> Custom HTML (After Login Form), then paste in the code snippet below.
<div class="custom-logins" style="place-items: center; width: 100%;">
<hr>
<a href='{Your-target-IDP-initiated-SSO-URL}' class='btn' style="display: block; width: 100%;">Login with Keycloak</a>
</div>
<script>
$(document).ready(function() {
const customLogins = $("div.custom-logins").detach();
$('#loginForm table').after(customLogins);
});
</script>
Result:
