CAS
cas
Provides Central Authentication Service (CAS) single sign-on authentication for Drupal websites.
Overview
The CAS module implements the Central Authentication Service (CAS) protocol, a single sign-on / single sign-off protocol for the web that permits users to access multiple applications while providing their credentials only once to a central CAS Server application.
Using a single sign-on service like CAS is beneficial because it provides convenience (users don't need to remember credentials for multiple web services) and security (the Drupal website never sees a user's password). This module implements version 1, 2, and 3 of the CAS protocol.
Key capabilities include automatic user registration, forced login on specific pages, gateway authentication for seamless login when users already have an active CAS session, single logout support, CAS proxy functionality, and extensive customization through events that other modules can subscribe to.
Install
composer require 'drupal/cas:^2.3'
Features
- Single Sign-On (SSO) authentication via CAS protocol versions 1.0, 2.0, and 3.0
- Automatic user registration for first-time CAS logins with configurable email assignment strategies
- Forced login feature to require CAS authentication on specific pages or paths
- Gateway login (auto login) for users with existing active CAS sessions without forcing authentication
- Single logout (SLO) support to log users out of Drupal when they log out of the CAS server
- CAS proxy support for accessing CAS-protected resources from other services
- Prevention of normal Drupal login for CAS users (recommended security feature)
- Restricted password and email management for CAS users
- Automatic role assignment during user registration
- Configurable error messages with token replacement support
- Debug logging for troubleshooting CAS authentication issues
- Bulk user creation for pre-registering CAS users
- CAS username management on user profile forms for administrators
- Integration with the 'r4032login' module for seamless access-denied-to-login flow
- Event-driven architecture allowing other modules to hook into the authentication process
- Client-side and server-side gateway redirect methods
- Drupal 7 to Drupal 10+ CAS user migration support
Use Cases
Enterprise Single Sign-On
Deploy CAS authentication for an organization where users authenticate once with their corporate credentials and gain access to the Drupal site along with other CAS-enabled applications. Enable 'Prevent normal login' and 'Restrict password management' for security, and configure automatic user registration to streamline onboarding.
University Portal Integration
Integrate a Drupal site with a university's existing CAS infrastructure. Students and staff log in using their university credentials. Use the CAS Attributes module to automatically assign roles based on attributes like department or student status returned by the CAS server.
Intranet with Seamless Authentication
Configure gateway login for an intranet site where users who are already authenticated to the organization's CAS server are automatically logged into Drupal without any additional action. This provides a seamless experience for internal users.
Restricted Content Access
Use forced login on specific content paths (like /admin or /private/*) to require CAS authentication for accessing sensitive areas while keeping other parts of the site publicly accessible. Combine with the r4032login module for automatic authentication on access denied pages.
Multi-site SSO with Single Logout
Enable single logout (SLO) so that when users log out of the CAS server or any other CAS-enabled application, they are automatically logged out of the Drupal site as well, maintaining consistent session state across all applications.
Proxy Authentication for Web Services
Configure CAS proxy functionality to allow the Drupal site to access other CAS-protected resources (like web services or APIs) on behalf of the authenticated user, using proxy tickets obtained during the initial authentication.
Pre-provisioned User Accounts
Use the bulk add CAS users feature to pre-register user accounts with specific roles before users authenticate for the first time. This is useful for course enrollment systems or employee onboarding where accounts need to exist before first login.
Tips
- Always use HTTPS for CAS server communication in production environments to protect authentication tickets
- Install the Token module to see available tokens for customizing error messages with dynamic values like the CAS login URL
- Use debug logging temporarily during initial setup to diagnose configuration issues, but disable it in production to keep logs clean
- The /caslogin path (or /cas legacy path) can be linked from anywhere on your site to trigger CAS authentication
- Add a 'destination' query parameter to the /caslogin URL to redirect users to a specific page after authentication: /caslogin?destination=/node/123
- Consider using the CAS Attributes module if your CAS server returns user attributes that should be mapped to Drupal fields or roles
- For high-traffic sites using gateway login, prefer the client-side redirect method to maintain page caching compatibility
- Set a login failure page to prevent redirect loops when forced login is enabled and authentication fails
Dependencies
Related Projects
Allows user attributes and roles to be set based on attributes provided by the CAS server during authentication. Enhances auto-registration with field mapping capabilities.
Core dependency that provides the underlying external authentication framework and authmap table for storing CAS username associations.
Integration allows access denied pages to automatically trigger CAS authentication, providing a seamless login experience when users try to access restricted content.
When enabled, CAS adds an 'Add CAS user(s)' menu item to the People admin menu for quick access to bulk user creation.
When enabled, displays available token tree for customizing error messages with CAS-specific tokens like [cas:login-url].
Admin Pages
| Title | Path | Description |
|---|---|---|
| CAS settings | /admin/config/people/cas |
Configure CAS server connection, authentication behavior, user account handling, error messages, and advanced options for CAS single sign-on authentication. |
| Bulk Add CAS Users | /admin/people/create/cas-bulk |
Pre-register one or more CAS users by providing their CAS usernames, allowing them to log in using CAS before they authenticate for the first time. |
Permissions
| Permission | Description |
|---|---|
|
Required to access and modify CAS configuration settings at /admin/config/people/cas. This is a core Drupal permission. |
|
Required to access the bulk add CAS users form at /admin/people/create/cas-bulk and to manage CAS username associations on user profile forms. This is a core Drupal permission. |
Hooks
| Hook | Description |
|---|---|
hook_cron |
Cleans up stale proxy granting tickets (older than 1 hour) and expired single logout session mapping data based on configured lifetime. |
hook_user_role_delete |
Removes deleted roles from the auto-assigned roles configuration to prevent configuration errors. |
hook_user_logout |
Removes session data from the cas_login_data table when a user logs out of Drupal. |
hook_form_user_form_alter |
Adds CAS username fields to the user entity form, allowing administrators to associate CAS usernames with Drupal accounts. |
hook_form_user_login_form_alter |
Adds a CAS login link to the standard Drupal login form when configured, and prevents CAS users from using normal login. |
hook_form_user_pass_alter |
Adds validation to the password reset form to prevent CAS users from resetting their Drupal password when restricted. |
hook_validation_constraint_alter |
Replaces core's ProtectedUserFieldConstraint with a decorated version that skips validation when restricted password management is enabled for CAS users. |
hook_menu_links_discovered_alter |
Adds 'Add CAS user(s)' menu item to the People admin menu when the Admin Toolbar Tools module is enabled. |
Troubleshooting
Enable debug logging in Advanced settings to see detailed error messages. Common causes include incorrect CAS server hostname/port, SSL certificate verification failures, or network connectivity issues between the Drupal server and CAS server.
If using a self-signed certificate or private CA, either add the CA certificate to your web server's trust store, or configure a custom CA certificate path in the CAS settings. Never disable SSL verification in production.
Verify that roles are selected in 'Automatically assign roles on user registration' setting. For attribute-based role assignment, install and configure the CAS Attributes module.
Ensure the gateway recheck time is not set to 'Every page request' when using client-side redirect method. Also verify that gateway paths are correctly configured and not including CAS-related paths.
Verify that your CAS server supports SLO and is properly configured to send logout requests. Check that the cas_login_data table is being populated (session IDs are stored). Note: SLO requires storing un-hashed session IDs.
Enable 'Restrict password management' in User Account Handling settings. This prevents CAS users from using the forgot password functionality.
Ensure the user account has a CAS username association in the authmap table. Administrators can set this on the user profile form by enabling 'Allow user to log in via CAS' and providing the CAS username.
Security Notes
- Single logout (SLO) stores session IDs un-hashed in the database, which is a deviation from Drupal's default session security hardening. Only enable SLO if required by your organization's authentication policy.
- Never disable SSL certificate verification in production environments. This makes the site vulnerable to man-in-the-middle attacks.
- The 'Prevent normal login for CAS users' setting is strongly recommended to ensure CAS users cannot bypass CAS authentication even if they know their randomly-generated Drupal password.
- Proxy functionality should only be enabled when necessary, and proxy chains should be strictly configured to allow only trusted proxy servers.
- Debug logging should never be enabled in production as it may log sensitive authentication information to the Drupal watchdog.
- CAS users' Drupal passwords are randomly generated 30-character strings. While theoretically brute-forceable, preventing normal login eliminates this attack vector entirely.