Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Introduction

...

The 'SAML Service Provider Directory Manager' plugin facilitates effortless Single Sign-On (SSO) integration with Joget by enabling compatibility with various Identity Providers (IdPs). With this plugin, users can seamlessly authenticate and access Joget through their chosen IdP, enhancing the user experience and security of the platform.

Plugin Info

Plugin Available in the Bundle:

  1. SAML Service Provider Directory Manager

This plugin bundle is compatible with Joget DX 8.

Expected Outcome

To successfully perform Single Sign On (SSO) to Joget using Identity Provider (IDP). For this article we are using OKTA as Identity Provider.

Getting Started

Prerequisites

1. OKTA Developer Account

The prerequisite for this plugin is to have a account with desired Identify Provider (IDP) and setup the App integration and obtain the IDP metadata and certificate. In this article we will using OKTA as the Identity Provider.

Please refer to following to read and understand more on Okta.

Okta
Identity Providers (IdPs): What They Are and Why You Need One
Okta Documentation

2. API Domain/IP Whitelist

To ensure the successful operation of this plugin, it is essential to whitelist the domains or IP addresses of the host. Typically, this involves adding the IP address or domain name of your Joget application server to the whitelist. To access this section of Joget, go to Settings → General Settings and scroll down till you see API Domain/IP Whitelist section.

Image Added

Figure 1: API Domain/IP Whitelist


NameDescription
API Domain Whitelist (Separated by ';')

Domain whitelist to allow API calls to Joget Workflow. Separated by semicolon.

Info
titleExample

"localhost;www.joget.org;dev.joget.org”, or "*" to allow from everywhere.

Warning

In a production environment, do not use "*".

Doing so will allow anyone to call all JSON APIs from the Joget server.

API IP Whitelist (Separated by ';')

IP address whitelist to allow API calls to Joget. Separated by semicolon.

Info
titleExample

"localhost; 192.168.101.10; www.joget.org;dev.joget.org ”, or "*" to allow from everywhere.

Warning

In a production environment, do not use "*".

Doing so will allow anyone to call all JSON APIs from the Joget server.

3. Licensed Users

Please review the Licensed Users in the License section of Joget. If you surpass the allowed user limit, you won't be able to log in to Joget following the Single Sign-On (SSO) process.

Image Added

Figure 2: Licensed Users

Setting up OKTA

1. Create a OKTA Developer Account

Create Developer Account at https://developer.okta.com/signup/ and compete the signup process. For this the setup in this article, we will  be using Workforce Identify Cloud Account.

Image Added

Figure 3: Okta Developer Account Sign up

2. Login to OKTA Developer Account

Login at https://developer.okta.com/login/

3. Create App Integration

Go to your Okta developer account, and navigate to Applications > Create App Integration.

Image Added

Figure 4: Okta Developer Dashboard - Creating App Integration

4. Choose

Figure 1: Login screen

Image Removed

Figure 2: Login page using Okta IDP

Upon successfully login in with your register email you would be redirected to your Joget DX.

Download Plugin

Please visit https://github.com/jogetoss/sp-saml-directory-manager to download the plugin.

Setting up

...

SAML 2.0.

Image Modified

Figure 35: App Integration - SAML 2.0


After selecting SAML 2.0, we have to give an app name and pick a meaningful app name to represent Joget.

You may click on "Do not display application icon to users" if you do not want this app to appear in Okta's end user interfaces.

Image Modified

Figure 46: General Settings sectionTo fill up the section in figure 5, to ease out the process. We have to upload the sp-saml-directory manager jar file onto our Joget DX 8 first.


In the next screen, we will be required to provide SSO URL and SP Entity ID.

Image Modified

Figure 47: SAML Settings section
Upon uploading go into System Settings and Directory Manager Settings and select the SAML Service Provider Directory Manager like in Figure 5. Upon selecting, it will lead you to the image as Figure 6.

Image Removed

Figure 5: Select Plugin

Image Removed

Figure 6: Plugin Configuration

Here we will need Single sign-on URL & Audience URI (SP Entity ID). Please key in the following in both the fields

[server]:[port]/jw/web/json/plugin/org.joget.marketplace.SpSamlDirectoryManager/service

Replace the server and port with actual server credentials. For example localhost:8080

For this article we are using localhost as server and 9443 as port, e.g. https://localhost:9443/jw/web/json/plugin/org.joget.marketplace.SpSamlDirectoryManager/service

** Only change the server and port setting.


As you can see you the plugin has shown you your Entity ID and ACS URL so that you could use. Copy the value and past it under Single sign-on URL, Audience URI, and Default RelayState. Change Name ID format onto EmailAddress.Upon completing that section it would look as below image in figure 7.
Image Removed

Image Added

Figure 78: SAML Setting (General)


Scroll a bit below and you would stumble upon down to Attribute Statements (optional) . Just and fill up the text boxes as below and we are good to go.
Below value is needed so that attribute mappings. The mappings are needed to identify the users that will be logging into our systemin.


Image Modified
Figure 89: Attribute Statements
Upon filling up everything under general for the necessary stuff. You could preview the SAML Assertion. If you are happy we could go to the next page.

Image Removed

Figure 9: SAML Assertion


Info
titleAttribute Statements

Click Add Another to create an extra attribute statements.

NameValue

firstName

user.firstName

lastName

user.lastName

email

user.email

Complete the rest of the steps by clicking on Next and Finish. You may choose "Upon clicking next just Click on I'm an Okta customer adding an internal app, and This is an internal app that we have created.

That is all for the Okta configuration. At least we have setup Okta IDP. But we are not quite there yet. Upon finishing, we need to copy two more information.
Which is, the certificate and the metadata. Below is where you could locate it.

...

Figure 10A: Metadata URL

Image Removed

Figure 10B: Metadata Value

Image Removed

" for your testing purpose.

4. Getting IDP Metadata and Certification

In this, we will get IDP Metadata and Certificate.

Info
titleIDP Metadata and Certificate

We will need IDP Metadata and Certificate to configure this plugin in later steps. 


Edit the app integration that we have just created on Okta.

Image Added

Figure 10: Obtaining Metadata


Copy the Metadata URL and open it in a new window. Copy the entire content.

Image Added

Figure 11: Metadata


Scroll down to look for SHA-2 cert and download certificate.

Image Added

Figure 12Figure 11A: Download Certificate


Image Modified

Figure 11B13: Okta Certificate

5. Add users to App Integration

We will need to assign user(s) to the app. Navigate to Applications > Assignments > Assign.

Image Added

Figure 14: Assign Users to App

Once assigned, the selected users are now able to SSO into Joget using their identity in Okta.

We are done with setting up OKTA Developer Account and obtains the required items such as IDP Metadata and Certificate. We will not proceed to setup this plugin in Joget.

Plugin Setup

1. Obtain the Plugin

Get the plugin jar file from https://github.com/jogetoss/sp-saml-directory-manager

2. Upload the Plugin

Upload the plugin jar file in Joget by going to Settings → Manage Plugins → Upload Plugin

3. Plugin Configuration

Once the plugin in uploaded, go to Settings → Directory Manager Settings → choose SAML Service Provider Directory Manager - 8.0.0 and click Select. 

Image Added

Figure 15: Select Plugin


Open the certificate with your favourite text editor and copy the value . Upon copying those value, you could insert those value in Figure 6.
Only copy the highlighted data in Figure 10. You have to click on User Provisioning Enabled, this is because upon enabling this the user that sign in
would be registered onto the system. If not the data wouldn't be able to be capture and leads to different behaviour. Figure 12 would be how it would look like
after completing the action. Upon clicking Submit you would landed onto the page in figure 13. You have to make sure the data is the same as in figure 8.
The first name and the e-mail attribute is mandatory.
Image RemovedFigure 13: Configure User Attributes
One last step that we need to do is assign user in Okta like in figure 14. Upon creating the user you need to assign the newly registered account to the
newly created App and we are good to go.
Image RemovedFigure 14: Add Person
Image Removed

Figure 15: Assign to People

and paste it into Joget.

Image Added

Figure 16: Paste the Cert Content


Paste the content into Metadata in Joget.

Image Added

Figure 17: Paste Metadata

Info
titleUser Provisioning

You may want to check on User Provisioning Enabled so that if it is the first time an user SSO into Joget, an user account would be created in Joget and the user would be able to continue to log in to Joget.


Configure the user attributes.

Image Added

Figure 18: Configure User Attributes

Configure User Attributes based on the mappings below.

NameValue

First Name Attribute

firstName

Last Name Attribute

lastName

Email Attribute

email

The "Value" here corresponds with "Name" column that we have declared in Figure 6 earlier.

Configure the Login Button. This login button will be shown at the Joget Login Screen to enable use to perform Single Sign On (SSO) using OKTA.

Image Added

Figure 19: Configure Login Button


Up to this point, we have successfully created app integration in Okta and configured the
SAML Service Provider Directory Manager - 8.0.0 plugin in Joget.

Performing Single Sign On

To login using this plugin, you have to logout from Joget. Go to Joget Login Page, you will see the following login screen with the login button to perform SSO using OKTA.

Info
titleLogin Screen

Login screen may differ as show below depending on the App Center but login button will be shown.


Image Added

Figure 20: Joget Login screen


Upon clicking on the blue login button, the user will be redirected to Okta.

Image Added

Figure 21: OKTA Login Screen


Upon successfully login in Okta with your registered email you would be redirected back to Joget and will be logged in.

Source Code and Plugin Download

...

  1. Please visit https://github.com/jogetoss/sp-saml-directory-manager for the plugin's source code.
  2. You can find the latest release at https://github.com/jogetoss/sp-saml-directory-manager/releases .
  3. Upload the plugin to your Joget by navigating to Settings > Manage Plugins > Upload Plugin as admin.