Installing CAS

Installing CAS root
Drupal Version

Editor's Note: If you are using Drupal Express (Drupal 10 or Drupal 7), then CAS is already installed as part of your Drupal Express installation.  You may want to look at the sections here about configuring CAS, should you want to customize your configuration, but you do not need to go through any of the installation processes.

There are two components needed to add CAS support to a Drupal website: the phpCAS Library, and two supporting Drupal modules.

phpCAS Library

This library is only needed for Drupal 7.  If you are installing the CAS module for Drupal 10, you can skip this section.

  1. Download and install the current, stable version of the phpCAS Library.  As of 2019, the current version was phpCAS 1.3.8 – if you are using and older version, you should consider upgrading as soon as possible to get the latest security patches.
  2. Install it under the sites/all/libraries/ directory of your Drupal site.  Rename the top level directory to CAS so that you have the CAS.php file inside of sites/all/libraries/CAS/

Drupal Modules

You will need to configure CAS to talk to the Georgia Tech CAS service.

  1. Log into the special original user account (user #1) that you setup when creating your Drupal site.  This is the main administrative account that has full power over everything in your site.  If this account is the same as someone's GT Account Username, you should rename the account to something else (good names are "root" or "admin", which make it easy to identify the account later on.
  2. For Drupal 10, download and install the External Authentication and CAS modules into your Drupal site's sites/all/modules/ directory, or if your site supports it, install them via the Install Module option in the Modules section of your site's administrative controls.
  3. For Drupal 7, download and install the Libraries and CAS modules into your Drupal site's sites/all/modules/ directory, or if your site supports it, install them via the Install Module option in the Modules section of your site's administrative controls.
  4. Go to the Modules page of your site's administrative controls and enable (turn on) both modules.  Once you have enabled these modules DO NOT LOG OUT OF THE SITE until you have finished the remaining steps.  Otherwise, you will find yourself locked out of your site!
  5. For Drupal 7 only, go to the Permissions page of your site's administrative controls (found under the People section), and make sure that the following permissions are enabled for the highest level user role in your site (commonly "administrator", or for sites using the GT Profile, "super administrator") (Don't forget to save your changes!) :
    • CAS -> Administer CAS
    • User -> Administer Permissions
    • User -> Administer Users
  6. Go to the CAS settings page of your site's administrative controls (found under the Configuration -> People section) and configure your CAS settings (see Drupal version specific links below for more details).
  7. Add a new user to the site with the username and "CAS username" both being the same as your GT Account Username.  Set the other fields as needed (enter a random value for the password field) and give the account the highest access level available (usually 'administrator').  Don't forget to save the new account.
  8. In a different web browser from the one in which you are currently using (or via your browser's private browsing feature), browse to your Drupal site and verify that you can login with your personal GT Account Username and password.  You should not see the normal Drupal login prompt - if you are prompted at all, you should be taken to the Georgia Tech Login service and then brought back to the Drupal site after you've successfully logged in to your GT Account.
  9. Repeat step #7 above for each user who should have access to the site, setting the access level as appropriate for the individual user.

CAS Configuration Guides

Configure CAS (Drupal 10)

Configure CAS (Drupal 10) root
Drupal Version

The following settings should be adequate for most Georgia Tech developers using Drupal version 10.

The CAS configuration page can be found on the black administration toolbar under Configuration -> People -> CAS

Alternatively, you can access the configuration page by adding "/admin/config/people/cas" to the end of your site's front page URL.

CAS Server

  • Version — 3.0 or higher
  • HTTP Protocol — HTTPS (secure)
  • Hostname — sso.gatech.edu
  • Port — 443
  • URI — /cas
  • SSL Verification — Verify using your web server's default certificate authority (CA) chain.

All other sections are optional, but you will want to either:

  • Enable Login link enabled under the GENERAL SETTINGS section (to show a CAS login link on the regular Drupal login form/page).  This could be combined with the GATEWAY feature to speed up login for users already logged into their GT Account.
  • Post a link to /caslogin to your front page
  • Configure the FORCED LOGIN section, should you want to have visiting a path like /user automatically to log the user into CAS

NOTE: The Drupal 8 CAS module originally used a different login path (/caslogin) from what CAS used in Drupal 6 and 7, which was /cas .  However,  the module now supports both URL paths, though it considers /cas to be a legacy path.

An explanation on GATEWAY: this feature will check to see if the user is already logged into his/her GT Account and if so log him/her into the website.  If the user is not already logged in, then the user will simply access the site as a guest (anonymous) user.  For this reason, you must also enable the login link setting or post a login link to your front page to allow users to log into the site when they are not already logged into their GT Account.  (All GATEWAY does is to save users the trouble of selecting a login link when they've already logged into their GT Account.)

Important: If you turn on both GATEWAY logins and Auto register users, then every Georgia Tech user who visits your site and is already logged into their GT Account will have a Drupal account created for them on your site.  This can result in your site ending up with thousands of user accounts, which can be a headache when it comes to managing the accounts of users who actually have special editing privileges on your site.  In general, you really don't want to configure a site this way unless you specifically want to allow all Georgia Tech community members to be able to create content and/or post comments to existing content.  An example of this kind of usage is this Georgia Tech Drupal community site.

The FORCED LOGIN feature will require every visitor to have a Drupal account on your site and will log the visitor into their account when first accessing the site in a browser session.  Visitors who do not have a Drupal account will be denied access to the site.  You probably do not want to enable this for the whole site (unless the site is meant to be a private intranet), but it can be useful to enable FORCED LOGIN for subsections of a site (e.g. "/admin/*" to automatically force login when trying to access any administrative page.)

Configure CAS (Drupal 7)

Configure CAS (Drupal 7) root
Drupal Version

The following settings should be adequate for most Georgia Tech developers using Drupal version 7.

The CAS configuration page can be found on the black administration toolbar under Configuration -> People -> CAS Settings

Alternatively, you can access the configuration page by adding "/admin/config/people/cas" to the end of your site's front page URL.

CAS Server

  • Version — 3.0 or higher
  • Hostname — sso.gatech.edu
  • Port — 443
  • URI — /cas
  • Certificate Authority PEM Certificate — /etc/pki/tls/certs/ca-bundle.crt

Login Form

  • Add CAS link to login forms — Make CAS login default on login forms
  • CAS login invitation — Log In
  • Drupal login invitation — default
  • Redirection notification message — You will be redirected to the secure GT login page.
  • Successful login message — Logged in via GT as %cas_username.

User Accounts

  • Automatically create Drupal accounts — unchecked/checked
    (Whether a Drupal account is automatically created the first time a CAS user logs into the site. If disabled, you will need to pre-register Drupal accounts for authorized users.)
  • Email address: username@ — gatech.edu
  • Roles — authenticated user
  • Users cannot change email address — checked
  • Users cannot change password — checked

Redirection

  • Check with the CAS server to see if the user is already logged in? — unchecked
  • Require CAS login for — specific pages
    (Enter one page per line as Drupal paths. The '*' character is a wildcard. Example paths are 'contact' for the site-wide contact form, 'user' for the sitewide login page, 'forms/*' for every form you create under this fake directory.)
  • Excluded pages — default

Login/Logout Destinations

  • Initial login destination — https://yoursite.gatech.edu/
    (Drupal path or URL. Enter a destination if you want the user to be redirected to this page on their first CAS login. An example path is "<front>" for the front page, or "user" for the user's page.)
  • Logout destination — <none>
  • Change password URL — https://passport.gatech.edu/
  • Registration URL — blank

Miscellaneous & Experimental

  • Initialize CAS as proxy — unchecked
  • CAS debugging output filename — leave blank