Nametag Integration for Apereo CAS

Overview

The Nametag integration for Apereo CAS adds high-assurance, self-service password reset and lost-MFA-device reset to your self-hosted Apereo CAS single sign-on server. When a user needs to recover their account, CAS delegates the “prove it’s really you” step to Nametag (government-ID + liveness). After a successful verification, CAS itself performs the reset against your backing store (LDAP/AD/JDBC) — Nametag never stores or receives your users’ PII, and no PII is written into CAS.

Because CAS is open-source software you host yourself, connecting is a credential exchange rather than a hosted sign-in: you give Nametag your CAS URL, and Nametag gives you OpenID Connect credentials plus a configuration snippet to paste into your CAS overlay. You never paste a Nametag API key into the console.

How it works

1. A user starts recovery — from the Nametag recovery microsite or from CAS itself (/login?doChangePassword=true, or the Account Profile “remove device” action).
2. CAS (via pac4j) redirects the user to the Nametag OpenID Provider to verify their identity.
3. The user completes Nametag verification. Nametag mints a short-lived, ES256-signed id_token carrying only a verified-subject identifier and an assurance level — no PII.
4. The Nametag recovery module in your CAS overlay validates that id_token against the Nametag OIDC discovery and JWKS endpoints. Validation is fail-closed: if the token is missing, expired, wrong-issuer, below the required assurance, or the JWKS endpoint is unreachable, recovery is denied.
5. On success, CAS runs the reset itself: its password-management flow resets the password, or its device registry removes the lost MFA device so the user re-enrolls.

Prerequisites

Before setting up the integration, ensure you have:

1. An active Nametag account with the Apereo CAS integration enabled for your tenant.
2. An Apereo CAS 7.x deployment built with the WAR overlay pattern (or CAS Initializr). CAS 6.6+ works for the delegated-OIDC path — see version caveats below.
3. The delegated-authentication module (cas-server-support-pac4j-webflow) and the password-management module (cas-server-support-pm-webflow, plus a backend such as -pm-ldap or -pm-jdbc) in your overlay. For lost-MFA reset, the Account Profile Management feature enabled.
4. Access to edit your overlay and redeploy CAS.

Step 1 — Start setup in the Nametag console

1. In the Nametag console, go to Integrations → Add integration.
2. Choose Apereo CAS.
3. The setup wizard opens and shows all steps up front.

Step 2 — Connect your CAS server

1. Enter your CAS base URL (for example https://cas.university.edu/cas).
2. Nametag registers your CAS as a delegated OpenID Connect client and shows a client ID, a client secret (copy it now — it is shown once), and your issuer / discovery URL.

Step 3 — Add the Nametag module to your CAS overlay

1. Select Download module in the wizard to get cas-server-support-nametag-recovery-1.0.0.jar, place it in your overlay (for example libs/), and reference it as a file dependency:

   implementation files("libs/cas-server-support-nametag-recovery-1.0.0.jar")
   

2. Add the configuration the wizard generated for your tenant. Store the client secret as an environment variable or secret, not in plain configuration. The wizard fills in the exact issuer and client-id for your connection:

   cas.authn.nametag.enabled=true
   cas.authn.nametag.issuer=<issuer shown in the wizard>
   cas.authn.nametag.client-id=<client id shown in the wizard>
   cas.authn.nametag.client-secret=${NAMETAG_CLIENT_SECRET}
   cas.authn.nametag.assurance-level=nametag.high
   cas.authn.nametag.actions=password_reset,mfa_device_reset
   

   The module discovers the Nametag authorize, token, and JWKS endpoints from the issuer’s /.well-known/openid-configuration document, so you only need the issuer.

3. Rebuild and redeploy your CAS server.

Step 4 — Scope and coverage

Choose which users the integration applies to. The default is all CAS users; narrow by attribute or group if your deployment resolves them.

Step 5 — Recovery actions & assurance

• Password reset — after verification, CAS resets the password against LDAP/AD/JDBC.
• Lost MFA device reset — after verification, the module removes the registered authenticator so the user re-enrolls.
• Minimum assurance — verifications below this level are rejected and recovery is denied.

Step 6 — Review and activate

Confirm the summary and select Activate. Activation respects your tenant feature flag. Nothing is live until both the Nametag apereocas feature flag and cas.authn.nametag.enabled=true are set — the integration ships dark on both sides.

Managing the integration

From Integrations → Apereo CAS you can see connection status and recent recoveries, edit scope/actions/assurance, re-fetch the configuration snippet, rotate the client secret (update ${NAMETAG_CLIENT_SECRET} in CAS afterward), or disconnect (which revokes the issued credential).

Version caveats

• CAS 7.x — fully supported.
• CAS 6.6+ — delegated-OIDC recovery works; Account Profile Management for MFA-device removal is firmer in 7.x, so test lost-MFA reset before relying on it.
• CAS below 6.6 — not recommended; upgrade first.

Privacy & security

• No PII is stored in CAS or sent to CAS — only a signed verified-subject identifier and an assurance signal cross the boundary.
• Two credentials are kept distinct: the OIDC client credential authenticates your CAS to Nametag; the id_token proves the user to your CAS. Treat the client secret like any credential and rotate it on schedule.
• id_token validation is fail-closed — if the Nametag discovery/JWKS endpoint is unreachable, recovery is denied rather than allowed.
• Recovery requests expire after roughly 168 hours; a user who starts but doesn’t finish must restart.

Troubleshooting

• Connection verification fails — confirm CAS redeployed with the module, cas.authn.nametag.enabled=true, and that the client ID / secret / issuer match the console. Confirm CAS can reach the Nametag discovery and JWKS URLs.
• Recovery denied for a legitimate user — check the assurance threshold, that the action is enabled, and that the request hasn’t expired.
• Nothing happens on “forgot password” — confirm the pac4j and pm-webflow modules are present and the recovery entry point (doChangePassword or the microsite) is wired.