Service Provider (SP) Initiated SAML Directory Manager

Introduction

The SAML Service Provider Directory Manager plugin enables seamless Single Sign-On (SSO) integration with Joget using various Identity Providers (IdPs). It enhances the user experience by allowing SSO through an IDP, such as Okta, improving security.

Plugin information

• Plugin: SAML Service Provider Directory Manager
• Compatible with: Joget DX 8
• Status: Released

Get started

Prerequisites

Before using the plugin, you will need:

1. OKTA Developer Account: You need an account with your chosen Identity Provider (IDP). In this article, you will use Okta as the IDP. Set up App integration and obtain the IDP metadata and certificate. Learn more from the Okta Documentation and Identity Providers (IdPs): What They Are and Why You Need One.
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. 
   Go to Settings > General Settings and scroll to the API Domain/IP Whitelist section.
   
   
   • API Domain Whitelist  (Separated by ';'): Domain whitelist to allow API calls to Joget Workflow. Separated by semicolon.
     
     Example
     "localhost;www.joget.org”, or "*" to allow from everywhere.
     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.
     
     Example
     "localhost; 192.168.101.10; www.joget.org ”, or "*" to allow from everywhere.
     In a production environment, do not use "*".
     Doing so will allow anyone to call all JSON APIs from the Joget server.
3. Licensed Users: 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.
   

Where to get the plugin

You can get the plugin from the JogetOSS GitHub Repository.

How to install

1. Download the plugin JAR file from the releases page.
2. Go to Settings > Manage Plugins > Upload Plugin.
3. Once uploaded, the plugin will be available in your Joget environment.

How to use it

Setting up OKTA

1. Create a Developer Account at Okta and complete the signup process. This article will use Workforce Identify Cloud Account for this setup.
   
   
2. Login at https://developer.okta.com/login/.
   
3. Go to Applications > Create App Integration in Okta.
   
4. Choose SAML 2.0.
   
5. After selecting SAML 2.0, pick a meaningful app name to represent Joget.
6. If you do not want this app to appear in Okta's end-user interfaces, you may click the Do not display application icon to users.
   
7. Add SSO URL and SP Entity ID.
   
   
   You will need a Single sign-on URL & Audience URI (SP Entity ID). Key in both fields https://[server]:[port]/jw/web/json/plugin/org.joget.marketplace.SpSamlDirectoryManager/service and replace the server and port with actual server credentials. For example localhost:8080
   
   This article used localhost as server and 9443 as port, e.g. https://localhost:9443/jw/web/json/plugin/org.joget.marketplace.SpSamlDirectoryManager/servicen
   
   
   Only change the server and port setting
8. Change Name ID format onto EmailAddress.
   
9. Scroll down to Attribute Statements (optional) and complete the attribute mappings. The mappings are needed to identify the users who will be logging in.
   
   
   
   Attribute Statements
   Click Add Another to create an extra attribute statement.
   • firstName: user.firstName
   • lastName: user.lastName
   • email: user.email
     Complete the rest of the steps by clicking on Next and Finish. For your testing, you may choose I'm an Okta customer adding an internal app.
10. Getting IDP Metadata and Certification
    
    IDP Metadata and Certificate
    You will need IDP Metadata and a Certificate to configure this plugin in later steps. 

11. Edit the app integration that you have just created on Okta.
    

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

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

14. Add users to App Integration. To do so, go to Applications > Assignments > Assign.
    

    

    Once assigned, the selected users can SSO into Joget using their Okta identity.

Plugin Setup

1. Once the plugin is uploaded, go to Settings > Directory Manager Settings.
2. Choose SAML Service Provider Directory Manager-8.0.0 and click Select. 
   
3. Open the certificate with your text editor, copy the value and paste it into Joget.
   
4. Paste the content into Metadata in Joget.
   
   
   User Provisioning 
   You may want to check on User Provisioning Enabled so that if it is the first time a user SSO into Joget, a user account will be created in Joget, and the user will be able to continue logging in to Joget.

Configure the user attributes

Configure User Attributes based on the mappings below.

Fields to configure:

• First Name Attribute: firstName
• Last Name Attribute: lastName
• Email Attribute: email

The field value corresponds with the Name column that was declared in step 9 in the setting Okta.

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.

Performing single sign on

1. To log in using this plugin, you must log in from Joget.
2. Go to the Joget Login Page. You will see the following login screen, which has a button to perform SSO using OKTA.
   
   Login Screen
   The login screen may differ, as shown below, depending on the App Center, but the login button will be shown.
   
3. The user will be redirected to Okta after clicking the blue login button.
   
   Upon successfully logging in to Okta with your registered email, you will be redirected back to Joget and logged in.

Download plugin

• SP SAML Directory Manager
• SP SAML Directory Manager - Releases