Knowledge Base
  • Select Role
  • English
  • Login

Joget SSO to Active Directory with Kerberos

This guide provides step-by-step instructions on integrating Joget with Microsoft Active Directory for Single Sign-On (SSO) using Kerberos. Kerberos, developed by the Massachusetts Institute of Technology (MIT), facilitates SSO in client-server environments. 

Test environment setup for SSO integration with Joget and Microsoft active directory

This test environment setup describes the specific scenario used to configure and implement Single Sign-On (SSO) authentication between Joget and Microsoft Active Directory using Kerberos. It includes details of the Joget server and client and the names and configurations of the Windows server required for testing. These details ensure you can configure and verify SSO authentication in your tests.

Test environment

  • Joget Server: Joget DX 8 Enterprise on Apache Tomcat 9 and Java 11
  • Windows Server: Windows Server 2022 Datacenter on VirtualBox within a NAT Network.
  • Windows Client PC: Internet Explorer 11 on Windows 10, also on VirtualBox within a NAT Network. 

Test settings

  • Windows Server COMPUTER NAME: WIN-TKDH9LCHUUO
  • WINDOWS DOMAIN: windows.local
  • DOMAIN USER: joget
  • JOGET DOMAIN: joget.windows.local

This setup assumes prior knowledge of basic Windows Server and Windows 10 system and network administration. It is tested within a VirtualBox environment and may require adjustments for other setups.

Kerberos SSO installation setup

To set up and install Kerberos for Single Sign-On (SSO), follow these detailed steps to guide you through the process. You will learn how to configure Kerberos in your environment to enable single sign-on authentication in your applications.

Configure el centro de distribución de claves Kerberos (KDC) de Windows server

  1. Go to Server Manager > Add roles and features to install the DNS Server.
  2. In the Network and Sharing Center, set the Preferred DNS server to 127.0.0.1.<
  3. In DNS Manager, right-click the server name and select Configure a DNS Server to create a forward lookup zone for windows.local.

  4. In the windows.local DNS zone, add an A record for joget to point to the Joget server IP.
  5. Verify connectivity with ping joget.windows.local.
  6. Use Active Directory Users and Computers to create a domain user named joget.
  7. Execute in PowerShell: setspn -s HTTP//{JOGET DOMAIN} {DOMAIN USER}  e.g setspn -s HTTP/joget.windows.local joget
  8. In PowerShell, check that the SPN has been registered by running the following command:
    setspn -L joget

    The output should display:

    Registered ServicePrincipalNames for CN=Joget,CN=Users,DC=windows,DC=local:
         HTTP/JOGET.WINDOWS.LOCAL

Setup Joget server for Kerberos

  1. Edit the /etc/hosts file (for Linux or macOS) or the C:\Windows\System32\drivers\etc\hosts file (for Windows) and add the server IP. For example:
    192.168.56.102        windows.local win-tkdh9lchuuo win-tkdh9lchuuo.windows.local
    Note: This step is not necessary if the Joget Server is using the Windows Server as the DNS server.
  • Using Windows
    1. In PowerShell on the Windows Server, generate a keytab file using the Ktpass tool:
      ktpass -out joget.keytab -mapuser joget@WINDOWS.LOCAL -pass Pass@word1 -crypto all -ptype KRB5_NT_PRINCIPAL -princ HTTP/joget.windows.local@WINDOWS.LOCAL

    2. Transfer joget.keytab to Joget server (e.g., C:\Joget-DX8-Enterprise\wflow\joget.keytab).
    3. Visit the official Oracle website to download JDK 8.
    4. Install JDK 8 following the provided installation instructions.
    5. Locate the tomcat-run.bat file in your Tomcat installation directory.
    6. Open the file in a text editor and update the JAVA_HOME variable to point to your JDK 8 installation path.
    7. Save the changes.
    8. Create a krb5.ini file under C:\Windows folder with these configurations:
      [libdefaults]
default = WINDOWS.LOCAL
default_realm = WINDOWS.LOCAL
dns_lookup_realm = true
dns_lookup_kdc = true

[realms]
WINDOWS.LOCAL = {
    kdc = WIN-TKDH9LCHUUO.WINDOWS.LOCAL:88
    default_domain = WINDOWS.LOCAL
}

[domain_realm]
.windows.local = WINDOWS.LOCAL
windows.local = WINDOWS.LOCAL
  • Using Linux
    1. Install the krb5-user package, open a terminal and install the Kerberos 5 user applications package:
       
      sudo apt-get install krb5-user
    2. During installation, configure the realm as WINDOWS.LOCAL and the Key Distribution Center (KDC) as WIN-TKDH9LCHUUO.WINDOWS.LOCAL:88.
    3. Run the following command to obtain a Kerberos ticket:
      kinit joget@WINDOWS.LOCAL
      Note: Ensure the domain is in UPPER CASE. This command should execute without errors, confirming your credentials are recognized.
    4. Check the settings in the /etc/krb5.conf file to ensure they match the following:
      [libdefaults]
default = WINDOWS.LOCAL
default_realm = WINDOWS.LOCAL
dns_lookup_realm = true
dns_lookup_kdc = true

[realms]
WINDOWS.LOCAL = {
    kdc = WIN-TKDH9LCHUUO.WINDOWS.LOCAL:88
    default_domain = WINDOWS.LOCAL
}

[domain_realm]
.windows.local = WINDOWS.LOCAL
windows.local = WINDOWS.LOCAL
      Note: The domain and realm entries must be in UPPER CASE.
    5. Use ktutil to create a keytab file that will be used by Joget for authentication:
      ktutil
ktutil: add_entry -password -p HTTP/JOGET.WINDOWS.LOCAL@WINDOWS.LOCAL -k 1 -e arcfour-hmac-md5
Password for HTTP/JOGET.WINDOWS.LOCAL@WINDOWS.LOCAL:
ktutil: wkt /etc/joget.keytab
    6. To list the Service Principal Names (SPNs) in the keytab, use:
      ktutil
ktutil: rkt /etc/joget.keytab
ktutil: list
      Ensure that the SPNs are correctly listed, which confirms the keytab file is properly configured.
  • Using MacOS
    1. Open a terminal and execute the following command to obtain a Kerberos ticket:
      kinit joget@WINDOWS.LOCAL
      Note: Ensure the domain is in UPPERCASE. The command should execute without errors, or may simply issue a warning about the use of a weak encryption type.
    2. Ensure the configuration in the /etc/krb5.conf file matches the following:
      [libdefaults]
default = WINDOWS.LOCAL
default_realm = WINDOWS.LOCAL
dns_lookup_realm = true
dns_lookup_kdc = true

[realms]
WINDOWS.LOCAL = {
    kdc = WIN-TKDH9LCHUUO.WINDOWS.LOCAL:88
    default_domain = WINDOWS.LOCAL
}

[domain_realm]
.windows.local = WINDOWS.LOCAL
windows.local = WINDOWS.LOCAL
      Note: Both the domain and realm names must be in UPPERCASE.
    3. Use ktutil to create a keytab file that Joget will use for authentication:
      ktutil -k joget.keytab add -p HTTP/JOGET.WINDOWS.LOCAL@WINDOWS.LOCAL -e arcfour-hmac-md5 -V 1
    4. To list the Service Principal Names (SPNs) in the keytab, use:
      ktutil -k joget.keytab list
    5. Check that the SPNs are correctly listed, confirming the keytab file is properly configured.
    6. Keep a copy of the generated joget.keytab file, ideally at the path /etc/joget.keytab.

Configure Kerberos directory manager plugin

  1. Download the Kerberos Directory Manager plugin from the Joget Marketplace and upload it in Settings > Manage Plugins. 

  2. In Settings > Directory Manager, select the Kerberos Directory Manager plugin, and key in the appropriate values in the configuration: 

    • Service Principal: HTTP/JOGET.WINDOWS.LOCAL.

    • Path to Keytab File: /etc/joget.keytab (Linux) or C:/Joget-DX8-Enterprise/wflow/joget.keytab (Windows).

    • Debug Enabled: View debugging messages in the logs.
      Remember to configure the LDAP Directory Manager as external directory manager to retrieve users from Active Directory.
  3. In Settings > General Settings, set the API Domain Whitelist to * (or to the specific API domain) to allow SSO requests to the Kerberos Directory Manager.

Set up client PC for SSO

  1. Ensure that the Windows Server is reachable on the network from the Client PC.
  2. Set the DNS server to the IP address of the Windows Server. 
  3. Ping the windows domain name to test. 
  4. Right-click on This PC in File Explorer and choose Properties.
  5. Click Change settings next to the computer name.
  6. Click Change and set the domain, for example, windows.local. Enter the domain administrator login when prompted.
  7. Restart after successful domain join and log in as a domain user.
  8. In Internet Explorer, click Internet Options > Security > Local intranet site > Advanced and add the Joget domain, for example, http://joget.windows.local.
  9. Using the Kerberos Directory Manager plugin approach, access http://joget.windows.local/jw/web/json/plugin/org.joget.plugin.kerberos.KerberosDirectoryManager/service to log in automatically.

    Note that for the SSO to work properly:

    • The client PC and Joget server must reside on different machines.
    • The Windows server and client PC must reside on the same Windows domain.

Additional Resources

Explore these additional resources to deepen your understanding of Kerberos authentication. From introductory articles to comprehensive guides, these resources cover various aspects of configuring and integrating Kerberos in different environments, including Windows Server, Java, Spring, Apache Tomcat, and LDAP. Additionally, you'll find related articles, and practical insights to enhance your knowledge and implementation of Kerberos SSO.

Introduction to kerberos

Configuring kerberos on windows server

Integrating kerberos with java and spring

Integrating kerberos with apache tomcat and LDAP

Related articles

Created by Julieth Last modified by Aadrian on Dec 13, 2024
Tags:
Previous Joget SSO with OpenID Connect NextJoget SharePoint SSO Integration