CAS
Provides Central Authentication Service (CAS) single sign-on authentication for Drupal websites.
cas
Install
composer require 'drupal/cas:^2.3'
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.
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
Technical Details
Admin Pages 2
/admin/config/people/cas
Configure CAS server connection, authentication behavior, user account handling, error messages, and advanced options for CAS single sign-on authentication.
/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 2
Hooks 8
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 7
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 6
- 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.