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 and onwards
• 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 Auth0 Platform

1. If you use Auth0 Platform, you can refer to this section. Else, you can skip this section and refer to the next section, Setting up OKTA Platform.
   
2. Login at https://developer.okta.com/login/.
3. Go to Applications > Applications and click on Create Application. Choose the Regular Web Application.
   
4. After creating the application, go to Addons, and activate the SAML2 WEB APP.
   
   
5. Under Settings, add the Application Callback URL which has the format of
   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. 
   Modify the Settings value to your desired login credentials and map it properly in the plugin configuration for Configure User Attributes, for example:
   

   {
     "mappings": {
       "email": "email",
       "user_id": "user_id",
       "name": "name",
       "given_name": "firstName",
       "family_name": "lastName"
     },
     "passthroughClaimsWithNoMapping": true,
     "mapUnknownClaimsAsIs": false,
     "signatureAlgorithm": "rsa-sha256",
     "digestAlgorithm": "sha256",
     "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
     "nameIdentifierProbes": [
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
     ],
     "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
   }

   Remember to scroll down to save the settings changed.

   
6. Under Usage, click on the Download Auth0 certificate to fill the IDP Certificate config, and click on Download for Identity Provider Metadata to fill the Metadata config. . 
   

Setting up OKTA Platform

1. Create a Developer Account at Okta and complete the signup process. This article will use Workforce Identify Cloud Account for this setup. You must have a work email to use this method.
   
   
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/service
   
   
   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.

1. User Attribute Update Enabled
   You may want to check on User Attribute Update Enabled so that whenever a user logs in via SSO, Joget will update the existing user’s profile fields (based on your configured attribute mappings) with the latest values from the Identity Provider, keeping Joget in sync with your directory.

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.

Configure Notifications

Configure Notification Email Provider. This plugin supports SMTP or Microsoft Graph API for Email Notification. For setting up Microsoft Graph API, you can refer to this KB Knowledge Base > OAuth Email Tool.

Fields to configure:

• Notification Email Provider: How notification emails are sent. 
  • SMTP
  • Microsoft Graph API (Mail.Send)

If Notification Email Provider is SMTP (refer to Knowledge Base > General Settings):

• From: Sender address for notification emails.
• SMTP Host: Host name of the SMTP server.
• SMTP Port: Port of the SMTP server.
• Security: Connection encryption for the SMTP server.
• SMTP Username: Username for signing in to the SMTP server, if it requires one.
• SMTP Password: Password for the SMTP username.

If Notification Email Provider is Microsoft Graph API (Mail.Send):

• Tenant ID: Directory (tenant) ID of the Microsoft Entra ID tenant.
• Client ID: Application (client) ID of the Entra ID app registration that has the Mail.Send application permission.
• Client Secret: Client secret created for the app registration.
• Send Mail Endpoint: Graph endpoint for sending mail. {from} is replaced with the From address. Default value: https://graph.microsoft.com/v1.0/users/{from}/sendMail.
• Token URL: OAuth 2.0 token endpoint. {tenant} is replaced with the Tenant ID. Change it only for sovereign clouds. Default value: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
• Scope: OAuth scope requested for the token. Default value: https://graph.microsoft.com/.default.
• From: Sender address for notification emails. With Graph, this must be a licensed mailbox in the tenant.

For both types Notification Email Provider:

• CC: Extra addresses copied on every notification, separated by commas.
• HTML Content?: Sends the message body as HTML instead of plain text.
• User Creation (Subject): Subject of the email sent when a new user account is created.
• User Creation (Message): Body of the email sent when a new user account is created.
• Password Reset (Subject): Subject of the email sent when an admin resets a user's password.
• Password Reset (Message): Body of the email sent when an admin resets a user's password.
• Forgot Password (Subject): Subject of the email with the reset link that a user asks for from the login page.
• Forgot Password (Message): Body of the forgot password email. It must include the reset link.
• Account Lockout (Subject): Subject of the email sent when an account is locked after too many failed logins.
• Account Lockout (Message): Body of the email sent when an account is locked.

Download plugin

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