Deploy SSO with CAS 2.0

The Central Authentication Service (CAS) is a single sign-on (SSO) protocol that enables a user to access multiple applications using one set of credentials. This protocol works in conjunction with the CAS server, which handles all the user connections to your Microsoft Exchange and LDAP servers.

On this page

Upgrade to WHD with CAS already configured (2026.2 .1 and later)

If you are upgrading to the modern interface (WHD 2026.2.1 and later) with CAS 2.0 authentication already configured in your WHD database, your existing CAS settings are migrated automatically during the upgrade. You must update the CAS server configuration due to changed callback URLs.

What is migrated automatically

The database migration runs automatically when the modern interface is opened for the first time against your existing database. In the migration process, the following settings are preserved:

• CAS login URL (CAS_LOGIN_URL)
• CAS validate URL (CAS_VALIDATE_URL)
• Verification certificate (CAS_VERIFICATION_CERT)
• Authentication method (EXTERNAL_AUTH_PARAM_TYPE = 5)
• Logout URL

Update your CAS server

After upgrading, you must update the CAS server's service registry to allow the new WHD callback URL.

Setting	Classic interface value	Modern interface value
Service URL (Callback)	https://<mydomain.com>/helpdesk/WebObjects/Helpdesk.woa	https://<mydomain.com>/api/v1/auth/cas/callback
Logout URL	https://<mydomain.com>/helpdesk/WebObjects/Helpdesk.woa	https://<mydomain.com> or CAS server's logout endpoint

Update the CAS service registry

1. Locate your CAS server's service registry configuration.

   • JSON service registry: Edit the service JSON files in /etc/cas/services/.
   • Database service registry: Update the RegexRegisteredService table.
   • YAML service registry: Edit the YAML files in the services directory.

2. Update the registered service URL pattern to match the new WHD callback.

   JSON example (/etc/cas/services/WHD-NextGen-10000001.json):

      {
        "@class": "org.apereo.cas.services.CasRegisteredService",
        "serviceId": "^https://<mydomain.com>/api/v1/auth/cas/callback.*",
        "name": "Web Help Desk NextGen",
        "id": 10000001,
        "evaluationOrder": 1
      }

3. If using a wildcard pattern, ensure it covers the new URL path: https://<mydomain.com>/.

4. Restart the CAS server or reload the service registry for changes to take effect.

CAS server deployed in WHD Tomcat

The WHD modern interface no longer uses Apache Tomcat. If your CAS server was deployed as a WAR file inside the classic interface, take the following steps:

1. Deploy the CAS server separately: Install a standalone CAS server (Apereo CAS 6.x or 7.x recommended) on the same or a different server.

2. Migrate your configuration: Transfer your deployerConfigContext.xml, cas.properties, and LDAP settings to the new CAS deployment.

3. Update your WHD configuration: Update the CAS login URL and CAS validate URL in WHD to point to the new CAS server location.

Post-migration verification

After upgrading to the modern interface and updating the CAS service registry, verify the following:

• WHD is running and accessible over HTTPS.

• The CAS server registry has been updated with the new callback URL.

• In an incognito/private browser, navigate to WHD. You should be redirected to the CAS login page.

• After authenticating, you are redirected to WHD, where you are logged in.

• Existing tech and client accounts can log in via CAS.

• The verification certificate (if uploaded) is showing correctly in the WHD authentication settings.

Deploy CAS in WHD 2026.2.1 and later

Before configuring WHD

Before configuring CAS 2.0 in WHD, ensure that you meet the prerequisites:

• You must have a running CAS 2.0-compatible server (Apereo CAS 5.x, 6.x, or 7.x). The CAS server must be configured with an identity repository, such as LDAP, Active Directory, or database.

• Both the WHD and CAS servers should be accessible over HTTPS. Caddy handles TLS termination for WHD automatically.

• The WHD server must be able to reach the CAS server's /serviceValidate endpoint (server-to-server), and users' browsers must be able to reach both the WHD and CAS servers.

• You must have administrator or tech access to WHD in order to configure authentication settings.

• Optional, but recommended: If the CAS server uses a self-signed or internal CA certificate, upload the certificate to WHD for ticket validation.

Step 1: Gather your CAS server information

To configure WHD, collect the following information from your CAS server deployment:

Field	Description	Example
CAS login URL	The CAS server's login endpoint	https://cas.<mydomain.com>/cas/login
CAS validate URL	The CAS server's ticket validation endpoint	https://cas.<mydomain.com>/cas/serviceValidate
CAS logout URL (optional)	The CAS server's logout endpoint	https://cas.<mydomain.com>/cas/logout
CAS server SSL certificate	Certificate used by the CAS server, if self-signed or internal CA	.cer, .pem, or.crt file

Common CAS URL patterns

CAS server version	Login URL	Validate URL	Logout URL
Apereo CAS 5.x/6.x/7.x	https://<cas-host>/cas/login	https://<cas-host>/cas/serviceValidate	https://<cas-host>/cas/logout
Legacy CAS 3.x	https://<cas-host>/cas/login	https://<cas-host>/cas/serviceValidate	https://<cas-host>/cas/logout
Custom context	https://<cas-host>/<context>/login	https://<cas-host>/<context>/serviceValidate	https://<cas-host>/<context>/logout

Step 2: Configure CAS 2.0 in the WHD modern interface (2026.2.1 and later)

1. Log in to WHD as an administrator/tech.e

2. Navigate to Setup > General > Authentication. From the Authentication method dropdown, select CAS 2.0. The CAS configuration panel displays the following fields:

   Field	Description	Example
   CAS login URL	The CAS server's login page URL. Unauthenticated users will be redirected here.	https://cas.<mydomain.com>/cas/login
   CAS validate URL	The CAS server's ticket validation endpoint. WHD sends the service ticket here for server-side validation.	https://cas.<mydomain.com>/cas/serviceValidate
   Verification certificate	Upload the CAS server's SSL certificate if it uses a self-signed or internal CA certificate.	Upload .cer, .pem, or .crt file

3. Input the appropriate information in each field.

   • In the CAS login URL field, enter the CAS server login endpoint: https://cas.<mydomain.com>/cas/login.

   • In the CAS validate URL field, enter the CAS server's ticket validation endpoint: https://cas.<mydomain.com>/cas/serviceValidate.

   • Optional: Upload the verification certificate.

     • If your CAS server uses a self-signed certificate or a certificate from an internal CA, click Upload certificate.

     • Select the CAS server's SSL certificate file in .cer, .pem, or .crt format.

   • Optional: Configure the Logout URL to redirect users to the CAS logout page when they log out of WHD, using https://cas.<mydomain.com>/cas/logout.

4. Save your configuration.

Step 3: Register WHD as a service in your CAS server

For the CAS server to recognize WHD as an authorized service, register the WHD callback URL in your CAS server's service registry.

The service (callback) URL that the CAS server must allow is https://<mydomain.com>/api/v1/auth/cas/callback.

Configuration by CAS server type

• Apereo CAS (JSON service registry)

  Create or update a service definition file in /etc/cas/services/:

  WHDNextGen-10000001.json
  {
    "@class": "org.apereo.cas.services.CasRegisteredService",
    "serviceId": "^https://<mydomain.com>/api/v1/auth/cas/callback.*",
    "name": "Web Help Desk NextGen",
    "id": 10000001,
    "description": "Web Help Desk NextGen Service Provider",
    "evaluationOrder": 1,
    "attributeReleasePolicy": {
      "@class": "org.apereo.cas.services.ReturnAllAttributeReleasePolicy"
    }
  }
  

  Use ReturnAllAttributeReleasePolicy to release user attributes to WHD for user auto-creation.

• Apereo CAS (YAML service registry)

  Create or update a service definition file:

  WHDNextGen-10000001.yml
  
      !<CasRegisteredService>
  serviceId: "^https://<mydomain.com>/api/v1/auth/cas/callback.*"
  name: "Web Help Desk NextGen"
  id: 10000001
  description: "Web Help Desk NextGen Service Provider"
  evaluationOrder: 1
  attributeReleasePolicy: !<ReturnAllAttributeReleasePolicy> {}

• Apereo CAS (Database/JPA service registry)

  Insert or update the service record:

  INSERT INTO RegexRegisteredService (expression, name, enabled, ssoEnabled, evaluationOrder, id)
  VALUES ('^https://<mydomain.com>/api/v1/auth/cas/callback.*',
          'Web Help Desk NextGen', 1, 1, 1, 10000001);

• Legacy CAS 3.x (In-memory)

  If using the default in-memory service registry, update deployerConfigContext.xml:

  <bean class="org.jasig.cas.services.RegexRegisteredService"
        p:id="10000001"
        p:name="Web Help Desk NextGen"
        p:serviceId="^https://<mydomain.com>/api/v1/auth/cas/callback.*"
        p:enabled="true"
        p:ssoEnabled="true"
        p:evaluationOrder="1" />

LDAP configuration on CAS server

If your CAS server authenticates against LDAP/Active Directory, ensure the following settings are configured on the CAS server:

Setting	Description	Example
LDAP URL	LDAP server address	ldap://dc.<mydomain.com>:389 or ldaps://dc.<mydomain.com>:636
Base DN	LDAP search base	DC=<mydomain>,DC=com
Bind DN	LDAP service account	cn=admin,DC=<mydomain>,DC=com
User filter	How users are matched	sAMAccountName=%u or uid=%u

Step 4: Test the configuration

1. Open a new browser window or an incognito/private session. Navigate to your WHD URL at https://<mydomain.com>. You should be automatically redirected to the CAS server login page.

2. Enter your LDAP/AD credentials on the CAS login page. After successful authentication, the CAS server redirects back to WHD with a service ticket. WHD validates the ticket and logs you in automatically.

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
CAS_APP_BASE_URL	Base URL of the WHD backend, used to build the CAS service callback URL	http://localhost:8080
SAML_FRONTEND_BASE_URL	Base URL of the frontend for SSO callback redirect	http://localhost:3000

Example production configuration:

properties
# CAS SSO Configuration
cas.application.base-url=https://helpdesk.<mydomain.com>
saml.application.frontend-base-url=https://helpdesk.<mydomain.com>

# CAS redirect paths (defaults are usually fine)
# cas.redirect.success-path=/login
# cas.redirect.failure-path=/login?error=cas

Logout URL

When using CAS, logging out of WHD will end the WHD session. To enable CAS single logout (SLO), configure the Logout URL in the Authentication settings to point to the CAS server's logout endpoint: https://cas.<mydomain.com>/cas/logout. When a user logs out of WHD, they are redirected to the CAS logout page, which can optionally sign them out of all CAS-connected applications.

User auto-creation

WHD automatically creates user accounts when a user authenticates via CAS for the first time. The CAS-authenticated username (from the service ticket validation response) is used as the login identifier.

• CAS callback passes only CAS_AUTHENTICATED_USERNAME into external auth resolution.
• Auto-created user profile for CAS primarily uses fallback logic from login identifier.
• CAS assertion attribute map is collected in CasAuthResult but not used in current create-user flow.

CAS attribute	WHD field
email or mail	Email
givenName or firstName	First Name
sn or lastName	Last Name
displayName	Display Name

LDAP sync on login

If LDAP/AD directory sync is configured in WHD alongside CAS, WHD performs a background attribute synchronization for the user on each CAS login, keeping user profile data up to date with the directory.

SSL certificate trust

WHD uses a composite trust manager for CAS server communication. An uploaded verification certificate, if provided, is trusted first. System CA certificates are always trusted. If your CAS server uses a self-signed or internal CA certificate, upload it to WHD.