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. |
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.
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. |
At this point of time after completing the Keycloak installation tutorial, you should have these ready in Keycloak:
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. |
| General settings | |
|---|---|
| Client ID | (Paste in the Entity ID copied from the SAML Directory Manager plugin) Example: http://localhost:8080/jw/web/json/plugin/org.joget.plugin.saml.SamlDirectoryManager/service |
| Name | --OPTIONAL-- |
Description | --OPTIONAL-- |
Always display in UI | Off |
Access settings | |
Root URL | --blank-- |
Home URL | --blank-- |
Valid redirect URIs | (Base URL of your Joget instance) Example: http://localhost:8080/jw |
Valid post logout redirect URIs | --blank-- |
IDP-Initiated SSO URL name | (Paste in the ACS URL copied from the SAML Directory Manager plugin) Example: http://localhost:8080/jw/web/json/plugin/org.joget.plugin.saml.SamlDirectoryManager/service |
IDP Initiated SSO Relay State | --blank-- |
Master SAML Processing URL | (Paste in the ACS URL copied from the SAML Directory Manager plugin) Example: http://localhost:8080/jw/web/json/plugin/org.joget.plugin.saml.SamlDirectoryManager/service |
SAML capabilities | |
Name ID format | username |
Force name ID format | On |
Force POST binding | Off |
Force artifact binding | Off |
Include AuthnStatement | On |
Include OneTimeUse Condition | Off |
Optimize REDIRECT signing key lookup | Off |
Allow ECP flow | Off |
Signature and Encryption | |
Sign documents | Off |
Sign assertions | On |
Signature algorithm | RSA_SHA256 |
SAML signature key name | CERT_SUBJECT |
Canonicalization method | EXCLUSIVE |
Login settings | |
Login theme | --OPTIONAL-- |
Consent required | Off |
Display client on screen | Off |
Consent screen text | --blank-- |
Logout settings | |
Front channel logout | Off |
| Signing keys config | |
|---|---|
| Client Signature Required | Off |
| Encryption keys config | |
| Encrypt assertions | Off |
Default. No change. |
| Default. No change. |
| Default. No change. |
|
Mapping Name | SAML Attribute Name |
|---|---|
X500 surname | User.LastName |
X500 givenName | User.FirstName |
X500 email |
In the final phase, we should test if SAML SSO works with Keycloak & that Joget is able to correctly retrieve the sample user data from Keycloak as well.
To manually emulate an idP-initiated SSO login, we simply need to find the target IDP initiated SSO URL and test this URL in our browser.
The format of the target IDP initiated SSO URL is as such below.
Do refer to your overall Keycloak & Joget client configurations to fill in the blanks.
{server-root}/realms/{realm}/protocol/saml/clients/{client-id} |
An example of the fully-qualified URL will look as such below:
http://localhost:8500/realms/myrealm/protocol/saml/clients/http%3A%2F%2Flocalhost%3A8080%2Fjw%2Fweb%2Fjson%2Fplugin%2Forg.joget.plugin.saml.SamlDirectoryManager%2Fservice |
For the {client-id}, since the client ID itself is a URL, this value need to be in a URL-encoded format. You can use various free online tools to help convert to the URL-encoded value. |
Finally, you can navigate to this fully-qualified URL via an incognito tab in your browser.
You should see the Keycloak login page, and upon successful login, you will be redirect to the Joget App Center, and thus indicate this exercise is completed successfully.
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:
