Documentation forWeb Help Desk
Thinking of upgrading to the cloud? Learn more about migrating from Web Help Desk to Service Desk.

Deploy SSO with SAML 2.0

WHD supports SAML 2.0 authentication, allowing users to authenticate via a SAML 2.0-compliant external Identity Provider (IdP). Configuration instructions vary based on your version of WHD:

See the following sections:

Configure SSO in WHD 2026.1 and earlier

Customers using WHD 2026.1 and earlier can configure SSO using Active Directory Federation Services (AD FS) to enable users who log in to the Microsoft Exchange server to be automatically logged in to WHD.

Before you begin

  1. Enable automatic login through Microsoft Windows. Add the AD FS logon URL to the local Intranet sites in Internet Explorer through Tools > Internet options or through your corporate group policy.

  2. Set up your SAML server. Use an identity repository, such as AD FS or Light Directory Access Protocol (LDAP), in the remote login URL for your SAML server.

  3. Enable SSL in your Web Help Desk installation. Use a trusted certificate or create your own certificate.

    When you create or generate a certificate, ensure that:

    • The certificate is generated in the proper order.

    • The Common Name (CN) certificate attribute only contains the fully-qualified domain name (FQDN) with no descriptions or comments. The exact value of this field is matched against the domain name of the server to verify its identity.

    See Working with Keys and Certificates for information about trusted certificates.

  4. Configure Web Help Desk and the AD FS settings separately.

    For information about configuring SSO with SAML using AD FS, see the AD FS 2.0 documentation located on the Microsoft TechNet website.

Step 1: Configure Web Help Desk for AD FS

In the following settings, replace mydomain.com with your domain name.

  1. Log in to Web Help Desk as an administrator.

  2. Click Setup > General > Authentication.

  3. Click the Authentication drop-down menu and select SAML 2.0.

  4. In the Sign-in page URL field, enter:

    https://adfs.<mydomain.com>/adfs/ls

    To bypass external authentication, add the following to your login URL:

    ?username=<username>&password=<password>

  5. Click Upload to apply a verification certificate and enable SSL.

    Apply the same certificate used to sign the assertion in the AD FS 2.0 Relying Party (RP) setting.

  6. In the Logout URL field, enter the following URL or leave this field blank to use the Web Help Desk default logout page:

    https://adfs.<mydomain.com>/adfs/ls

    Web Help Desk redirects users to this page to log out.

  7. Import the certificate into the Web Help Desk trust store (cacerts).

    1. Upload the certificate into the Web Help Desk Admin Console.

    2. Stop and restart Web Help Desk.

    3. Open a Run dialog box and execute:

      C:\Program Files\WebHelpDesk\Portecle.bat

    4. Click File > Open Keystore file and navigate to:

      C:\Program Files\WebhelpDesk\bin\jre\lib\security

    5. Select All Files, select cacerts, and then click Open.

    6. Enter the following default password:

      changeit

      All common Certificate Authority (CA) certificates are displayed in the file.

    7. Select Tools > Import Trusted Certificates.

    8. Locate and select the exported file, and click Import.

      If the Import Trusted Certificate window opens, click OK.

      The exported certificate details are displayed.

    9. Click OK, and then click Yes.

    10. Enter a certificate name alias that is displayed in the list of common CA certificates, and click OK.

      The certificate alias does not affect the setup.

    11. Click OK.

      The imported certificate is displayed in the list.

    12. Select File > Save Keystore.

      If you cannot save the file and an error message is displayed:

      1. Open Portecle as an Administrator by navigating to the location of the Portecle.bat file.

      2. Right-click the file and select Run as Administrator.

      3. Start Web Help Desk.

Step 2: Configure SAML 2.0 on the AD FS server

All entries are case sensitive. To prevent system errors, enter the information as displayed in the following steps.

  1. Enter the following AD FS 2.0 RP settings:

    • Identifier: <mydomain.com>/helpdesk/WebObjects/Helpdesk.woa

    • Signature: Enter the name of the certificate you uploaded to Web Help Desk in step 5 of the Web Help Desk SAML configuration instructions.

    • Endpoint: Binding: POST, URL: <server IP address>/helpdesk/WebObjects/Helpdesk.woa

    • Detail: Secure hash algorithm SHA-1

  2. Enter the following AD FS 2.0 Log Out settings:

    • Identifier: https://<mydomain.com us>/helpdesk/WebObjects/Helpdesk.woa

    • Signature: Use the same certificate as in step one.

    • Endpoint: SAML Logout, Binding: POST, URL:

      • https://<ADFS_Server_fqdn>/<domain_name>/adfs/ls/?wa=wsignout1.0

    • Detail: Secure hash algorithm SHA-1

  3. Enter the following AD FS 2.0 Claim Mapping settings:

    • Attribute store: Active Directory

    • LDAP attribute: a user name or email address.

    • Outgoing claim type: NameID

Migrate SSO configuration to WHD 2026.2 and later

If you are upgrading from the classic interface available in WHD 2026.1 or earlier to the modern interface, your existing SAML settings are migrated automatically during the upgrade. However, you must update your IdP configuration as the Service Provider (SP) endpoints have changed.

Update your IdP

The SP endpoints have changed in the modern WHD interface, so you must update the following items in your IdP:

Setting Classic interface value Modern interface value
Entity ID/Identifier https://<mydomain.com>/helpdesk/WebObjects/Helpdesk.woa https://<mydomain.com>/saml2/service-provider-metadata/whd-sp
ACS URL (Reply URL) https://<mydomain.com>/helpdesk/WebObjects/Helpdesk.woa https://<mydomain.com>/login/saml2/sso/whd-sp
Logout URL https://<mydomain.com>/helpdesk/WebObjects/Helpdesk.woa https://<mydomain.com> or your IdP's logout endpoint

AD FS users:

  1. In the AD FS Management console, navigate to Relying party trusts and locate your existing WHD trust.

  2. Right-click and select Properties.

    1. On the Identifiers tab, remove the classic interface value (https://<mydomain.com>/helpdesk/WebObjects/Helpdesk.woa) and add the modern interface value (https://<mydomain.com>/saml2/service-provider-metadata/whd-sp).

    2. On the Endpoints tab, remove the previous SAML Assertion Consumer endpoint. Add a new endpoint with the following properties:

      • Type: SAML Assertion Consumer
      • Binding: POST
      • URL: https://<mydomain.com>/login/saml2/sso/whd-sp

  3. Verify your Claim issuance rules are still intact. They should be unchanged.

As an alternative, you can delete the previous Relying party trust and re-create it by importing the new SP metadata URL: https://<mydomain.com>/saml2/service-provider-metadata/whd-sp.

Entra ID users:

  1. In the Azure portal, navigate to Microsoft Entra ID > Enterprise applications. Select your existing WHD application.

  2. Go to Single sign-on > SAML > Basic SAML configuration > Edit. Update the following fields:

    • Identifier (Entity ID): https://<mydomain.com>/saml2/service-provider-metadata/whd-sp
    • Reply URL (ACS URL): https://<mydomain.com>/login/saml2/sso/whd-sp

  3. Save your updates. No changes are needed for certificates or attribute mappings.

Okta users:

  1. In the Okta Admin Console, navigate to Applications and select your existing WHD application.

  2. Under the General tab, select SAML settings > Edit. Update the following:

    • Single sign-on URL: https://<mydomain.com>/login/saml2/sso/whd-sp
    • Audience URI (SP Entity ID): https://<mydomain.com>/saml2/service-provider-metadata/whd-sp

  3. Save your updates. Attribute statements remain unchanged.

IdP metadata URL:

As an alternative, you can configure the IdP metadata URL in WHD.

  1. Log in to WHD as an administrator. Navigate to Setup > General > Authentication. Enter your IdP metadata URL:

    • AD FS: https://adfs.<mydomain.com>/FederationMetadata/2007-06/FederationMetadata.xml
    • Azure AD: Copy the App Federation metadata URL from the SAML configuration page.
    • Okta: Copy the Metadata URL from the Sign on tab.

  2. Save. The sign-in URL field will auto-populate from the metadata.

Configure SAML 2.0 in WHD 2026.2 and later

Before you begin

Beginning with 2026.2, the WHD modern interface supports SAML 2.0 authentication through SAML 2.0-compatible Identity Providers (IdPs). Prerequisites for SSO include the following:

  • WHD must be accessible over HTTPS. A SAML 2.0-compliant IdP must be configured.
  • You must have administrator access to WHD in order to configure authentication settings.
  • The WHD server must be able to reach the IdP metadata URL, and users' browsers must be able to reach both WHD and IdP.

Step 1: Gather your IdP information

Information Description Example
IdP metadata URL URL that provides the IdP's SAML metadata XML https://adfs.<mydomain.com>/FederationMetadata/2007-06/FederationMetadata.xml
Tip: Using the IdP metadata URL is recommended as it auto-discovers the sign-in URL, signing certificate, and other settings automatically. Changes on the IdP side are picked up automatically within 5 minutes.
IdP Sign-in URL IdP's SSO endpoint https://adfs.<mydomain.com>/adfs/ls
IdP signing certificate x.509 certificate used by the IdP to sign SAML assertions .cer or .pem file

Step 2: Configure SAML 2.0 in WHD 2026.2 and later

  1. Log in to WHD as an administrator, then navigate to Setup > General > Authentication. From the Authentication method dropdown, select SAML 2.0. Use one of these two methods to configure SAML authentication:

    1. Option A: IdP metadata URL (recommended)

      1. In the IdP metadata URL field, enter your IdP's metadata URL:

        • AD FS example: https://adfs.<mydomain.com>/FederationMetadata/2007-06/FederationMetadata.xml
        • Entra ID example: https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml
        • Okta example: https://yourorg.okta.com/app/<app-id>/sso/saml/metadata

      2. When a valid metadata URL is provided, the Sign-in URL field is disabled.

      3. Save your configuration.

    2. Option B: Manual configuration

      1. If your IdP does not expose a metadata URL, leave the IdP metadata URL field empty.

      2. In the Sign-in page URL field, enter your IdP's SSO login endpoint:

        • AD FS: https://adfs.<mydomain.com>/adfs/ls
        • Azure AD: https://login.microsoftonline.com/<tenant-id>/saml2

      3. Upload the verification certificate by clicking Upload certificate and selecting the IdP's x.509 signing certificate file in .cer, .pem, or .crt format. After upload, the certificate details will be displayed.

      4. Save your configuration.

Step 3: Configure your IdP

  • Configure your IdP by registering WHD as a Relying Party (RP)/Service Provider (SP) in your IdP. The required SP information is available directly in the WHD authentication settings.

    Field Description Value
    SP entity ID Unique identifier for WHD as a Service Provider https://<mydomain.com>/saml2/service-provider-metadata/whd-sp
    ACS URL Where the IdP sends the SAML response https://<mydomain.com>/login/saml2/sso/whd-sp
    SP metadata URL Used by your IdP for automatic SP configuration https://<mydomain.com>/saml2/service-provider-metadata/whd-sp

    AD FS users:

    1. In the AD FS Management console, click Add relying party trust and select Claims aware.

    2. Choose the configuration method.

      • Import metadata: Enter WHD's SP metadata URL (https://<mydomain.com>/saml2/service-provider-metadata/whd-sp).
      • Manual: Enter the SP settings from the table above.

    3. Configure the Relying party trust settings.

      • Identifier (Entity ID): https://<mydomain.com>/saml2/service-provider-metadata/whd-sp

      • Endpoint:

        • Type: SAML Assertion Consumer
        • Binding: POST
        • URL: https://<mydomain.com>/login/saml2/sso/whd-sp
      • Signature algorithm: SHA-256 (recommended) or SHA-1

    4. Configure Claim issuance policy.

      1. Attribute store: Active Directory

      2. Add the following claims mappings:

        LDAP attribute Outgoing claim type
        SAM-Account-Name or User-Principle-Name Name ID
        E-Mail-Addresses emailaddress
        Given-Name givenname
        Surname surname

    5. Save your configuration.

    • Entra ID users:

    1. In the Azure portal, navigate to Microsoft Entra ID > Enterprise applications. Click New application > Create your own application. Select Integrate any other application you don't find in the gallery (Non-gallery).

    2. Go to Single sign-on > SAML. Configure Basic SAML configuration:

      • Identifier (Entity ID): https://<mydomain.com>/saml2/service-provider-metadata/whd-sp
      • Reply URL (ACS URL): https://<mydomain.com>/login/saml2/sso/whd-sp
      • Sign-on URL: https://<mydomain.com>

    3. Configure Attributes & claims:

      1. Ensure user.userprinciplename or user.mail is mapped to Name ID (NameIdentifier).

      2. Add the following additional claims:

        Claim name Source attribute
        emailaddress user.mail
        givenname user.givenname
        surname user.surname

    4. Download the Certificate (Base64) from the SAML signing certificate section.

    5. Copy the Login URL from the Set up section. This is your IdP sign-in URL.

    6. Copy the App Federation metadata URL. Use this as the IdP metadata URL in WHD.

    Okta users:

    1. In the Okta Admin Console, navigate to Applications > Create app integration. Select SAML 2.0, then click Next.

    2. Configure SAML settings:

      • Single sign-on URL: https://<mydomain.com>/login/saml2/sso/whd-sp
      • Audience URI (SP Entity ID): https://<mydomain.com>/saml2/service-provider-metadata/whd-sp
      • Name ID format: EmailAddress or Unspecified
      • Application username: Email

    3. Add attribute statements.

      Name Value
      emailaddress user.email
      givenname user.firstName
      surname user.lastName

    4. Click Next. Select I'm an Okta customer adding an internal app, then click Finish.

    5. Navigate to the Sign on tab. Copy the Metadata URL to use in WHD.

    Step 4: Test your configuration

    1. Use the Test button (if available) on the WHD Authentication settings page to validate the SAML configuration.

    2. Open a new browser window or an incognito/private session. Navigate to your WHD URL (https://<mydomain.com>). You are automatically redirected to your IdP's login page.

    3. Authenticate with your IdP credentials. After successful authentication, you are redirected to WHD and logged in automatically.

      To bypass SAML and log in directly with WHD credentials, use https://<mydomain.com>/login?username=<username>&password=<password>.

    • Optional configuration

    Environment variables

    The following environment variables can be set in conf/application.properties or via the conf/whd.env file

    Variable Description Default
    SAML_FRONTEND_BASE_URL Base URL of the frontend. This is set to your public WHD URL in production. http://localhost:3000
    SAML_BASE_SUCCESS_URL Base URL used for SAML success redirects. https://localhost:8443/

    Configure logout behavior

    When using SAML, logging out of WHD will end the WHD session. To enable Single Logout (SLO), configure the logout URL in the Authentication settings to point to your IdP's logout endpoint.

    • AD FS: https://adfs.<mydomain.com>/adfs/ls/?wa=wsignout1.0
    • Entra ID: https://login.microsoftonline.com/<tenant-id>/saml2

    User auto-creation

    WHD automatically creates user accounts when a user authenticates via SAML for the first time. The following attributes from the SAML assertion are used to populate the user profile:

    SAML attribute names (Checked in order) WHD field
    emailaddress, email, mail, EmailAddress Email
    givenname, givenName, given_name, GivenName First Name
    surname, familyName, family_name, Surname Last Name
    displayname, name, fullName Display Name

    The Name ID from the assertion is used as the login identifier.

    LDAP sync on login

    If the LDAP/AD directory sync is configured alongside SAML, WHD will perform a background attribute sync for the user on each SAML login, keeping user profile data up to date.