Introduction & Setup

Introduction

The CAS module allows users your on your site to authenticate using your institution's Central Authentication Service (CAS) server. These users will not use Drupal's standard login form, but they will have Drupal user accounts associated with them.

How It Works

CAS authentication is quite simple:

1. User visits /cas or /caslogin on your site (both paths do exactly the same thing)
2. User is redirected to your CAS server for authentication
3. User enters their credentials on the CAS server login page*
4. User is redirected back to your website with a special ticket appended to the URL
5. The CAS module validates that ticket by making a back-end HTTPS request to the CAS server, which returns the username of the user (and optionally some user attributes)
6. The CAS module checks if a local Drupal account with that username exists, and if so, logs them in.

* If the user already has an active session with your CAS server, they will not be asked for their credentials again.

Basic Setup

After enabling the module, there is just one configuration page to visit:

Configuration > People > CAS (/admin/people/cas)

The configuration form is organized with the most important settings at the top and the lesser used features towards the bottom. All form fields are descriptive and should be mostly self-explanatory.

The minimum required configuration is the CAS server settings at the top of the form. These settings tell the module how to communicate with the CAS server.

Allowing Users to Authenticate

Users cannot authenticate with CAS by default. This is by design and is a security feature. The module does not assume that a the user accounts on your Drupal site are the same people that can authenticate with your CAS server. A "johndoe" user on your site may not be the same as "johndoe" on your CAS server.

To allow existing users to log in via CAS, edit their user account and check the box "Allow user to log in via CAS". You'll then be asked to provide the CAS username for this user. In many cases, this CAS username is the same as their Drupal username, but having this field separate allows for some flexibility. For example, a Drupal user account "johndoe" can have a CAS username "jdoe". When the user logs into the CAS server with their "jdoe" username, Drupal will map it to the "johndoe" Drupal user account.

User Account Handling

As a site administrator, you will typically want to enforce some rules on user accounts that are allowed to login via CAS. By default, the CAS module will prevent users from:

• Logging in using Drupal's user login form (if they knew their local Drupal password)
• Changing their email address
• Using the password reset form to change their Drupal password

All of these settings can be disabled if you'd like in the "User Account Handling" section of the CAS settings form.

Automatically Registering Users

You can configure the CAS module to automatically create a Drupal user account for users when they log in via CAS and a Drupal account with their CAS username does not already exist.

Visit the CAS Settings form and enable "Automatically register users" within the "User Account Handling" section. You'll then be prompted to specify how the email address for the user should be handled. Normal Drupal user accounts require an email, so the CAS module enforces this as well. Many CAS servers will provide an attribute during authentication with the user's email address. You can configure the module to use the value of that attribute as the email. Or, you can use the simple configuration of just providing a hostname and assigning an email as username@yourhostname.com.

Since Drupal also required passwords on user accounts, the CAS module will generate a 30-character long random password for users that are automatically registered. The user is never intended to use this password, since they will be always be logging in via CAS.

Finally, you can automatically assign one or more user roles to users that are automatically registered via CAS.

Note that if your CAS server sends attributes during authentication, you can use the CAS Attributes module to assign roles and other user field values based on CAS attributes.

Logging In

Users can log in to your site with CAS a number of ways:

1. Visit /cas
2. Visit /caslogin (exact same behavior as above)
3. Visit /user/login and configure CAS to display a CAS login link on the page (See "General Settings" on the CAS settings form)

After a user logs in via CAS, they are returned to the homepage of your site by default. However, you can override this by setting a special "returnto" parameter in the login URL. For example: https://sample.com/caslogin?returnto=/some/other/page. Drupal's standard method for returning users to some other page via the "destination" query param does not currently work, but may after #3150047: Deprecate the special "returnto" parameter and add support for "destination" instead is addressed.

Forcing Login

The CAS module can be configured to automatically force anonymous users to login when they visit certain one or more paths on your site. While not recommended, this can be used to create a rudimentary restricted area of your site. It's not recommended because the CAS module will not prevent such pages from appearing in your Drupal search index or appearing in menus or views.

The CAS module also integrates very well with the Redirect 403 to User Login module. This module allows site admins to redirect anonymous users to login anytime they'd normally try and visit a restricted URL. Setup this module with the following settings:

1. Check "Redirect user to the page they tried to access after login"
2. Set "Path to user login form" to "/cas"
3. Set "Destination parameter override" to "returnto"

When setup as above, anonymous users that visit restricted pages will be redirected to login with CAS and then returned to the page they originally tried to visit.

Logging Out

Drupal's normal log out behavior works just fine for users that have authenticated via CAS, but there is a consideration to make with regards to their CAS server session. When logging a user out of your Drupal site, you may also want to log them out of their CAS session.

There's two options for this:

1. Create a logout link on your site to the path /caslogout. This special path will first end the user's local Drupal session, and then redirect them to the CAS server logout page.
2. Visit the CAS Settings page and enable "Drupal logout triggers CAS logout" within the "Log Out Behavior" section. This overrides Drupal's normal logout URL (/user/logout) to log them out of CAS after their local session was ended.

It makes the most sense to use option #2 unless you need to maintain the normal Drupal logout behavior /user/logout for some reason.

CAS Single Log Out/Single Sign Out

The CAS protocol supports a feature called Single Log Out. When a user ends their session on the CAS server, the CAS server will (if configured to do so) send a logout request to every application that the user logged into during that CAS session. The applications are supposed to receive such requests and terminate the user's local session. This allows the user to log out of all applications in one action.

The CAS module optionally supports accepting such log out requests from the CAS server. It can be enabled on the CAS Settings page within the "Log Out Behavior" section. However, it is not recommended to enable it, because doing so means the CAS module will store unhashed user session IDs in the database. See #2583363: Decide what to do about single log out for more information.