CAS Single Sign-On

Central Authentication Service (CAS) based single sign-on is the main method of doing authentication via GT Account Usernames for Drupal website logins.  Once users have logged into the GT CAS system, they can access any Georgia Tech website that utilizes CAS without having to enter their GT Account Username again, as long as they don't completely close their browser or clear their browser's cookie cache.

    Category: 

    Installing CAS

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

    phpCAS Library

    1. Download and install the current, stable version of the phpCAS Library.  As of early 2017, the current version was phpCAS 1.3.4 – 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. 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.
    3. 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!
    4. 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
    5. Go to the CAS settings page of your site's administrative controls (found under the Configuration -> People section) and configure your CAS settings.
    6. In a different web browser from the one in which you are currently using, browse to your Drupal site and try to login with your personal GT Account Username and password.
    7. In your original browser, still logged in as User #1, go to the People page of your site's administrative controls.
    8. Select the edit option next to your personal GT Account Username (i.e. jdoe3), and then give yourself the highest level user role in your site. and then select the Save button at the bottom of the page.

    CAS Configuration Guides

    Category: 

    Configure CAS (Drupal 6)

    Drupal 6 CAS Settings

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

    The CAS configuration page can be found at: http://yoursite/admin/user/cas

    CAS Server Settings

    • CAS version — 2.0 or higher
    • CAS server — login.gatech.edu
    • CAS port — 443
    • CAS URI — cas
    • Check to see if a user is already logged in? — The function of this setting is unclear. It doesn't seem to do anything, but we (Communications & Marketing) leave it unchecked.
    • CAS PEM certificate verification — Do not verify the certificate
    • CAS PEM Certificate (phpCAS 0.6 or greater) — leave blank
    • Initialize CAS as proxy — unchecked
    • CAS PGT storage file format — Plain Text
    • CAS PGT storage path — leave blank
    • Enable CAS Single Sign Out (CAS server 3.1 or greater) — unchecked
    • CAS debugging output filename — leave blank

    User Account Settings

    • Is Drupal also the CAS user repository — unchecked
    • If Drupal is not the user repository, should cas hijack users with the same name? — You will probably want this box checked. This will allow you to create people's Drupal accounts before they log in. If you leave it unchecked, you will need to make user the following box is checked and you will have to get people to log in before you configure their accounts.
    • Should Drupal user accounts be automatically created? — If you want any GT user to be able to log into your site, you will want this box checked. If you want to pre-approve selected users, you will want to uncheck this box and make sure the previous box is checked. Warning: if you leave both this box and the previous box unchecked, there will be no way for CAS to associate its users with Drupal accounts.
    • Email Domain — mail.gatech.edu
    • Users cannot change email address — Checked, unless you want users to be able to use non-GT addresses.
    • Users cannot change password — checked
    • Auto-assign users to the role(s) — This is entirely up to you. Be warned, however: if you are allowing accounts to be created automatically and you are automatically endowing them with godlike powers, well, you might as well leave your house keys hanging from your mailbox while you're at it.

    Redirection Settings

    • Require CAS login for — You may specify protected pages if you have some portion of your site that is to be password-protected. If you are merely using CAS to authenticate site administrators, you make leave these fields blank.
    • Force redirection on initial login — If you want all users directed to a particular page upon login, check this box and enter the path in the following field.
    • Successful login message — We recommend the default unless you have specific other needs.
    • Redirect user on logout — https://login.gatech.edu/cas/login

    Miscellaneous Settings

    • Change password URL — https://passport.gatech.edu/
    • Registration URL — leave blank

    Login Form Settings

    • Add CAS link to login forms — Make CAS login default on login forms
    • CAS login invitation — default
    • Drupal login invitation — default
    • Redirection notification message — default
    Category: 

    Configure CAS (Drupal 7)

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

    The CAS configuration page can be found at: http://yoursite/admin/config/people/cas

    CAS Server

    • Version — 2.0 or higher
    • Hostname — login.gatech.edu
    • Port — 443
    • URI — /cas
    • Certificate Authority PEM Certificate — leave blank

    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 sitewide 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://cool.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
    Category: 

    Redirect to GT Logout System

    Drupal and CAS utilize different logout functions. Using http://yoursite/logout will only log the user out of your site and not CAS.

    Using http://yoursite/caslogout will log the user out of your site and redirect the user to the logout page for CAS.

    The best method I have found to send users to the CAS logout page without hunting down and changing every script that calls logout is to setup logout as an alias for caslogout.

    Setting up the Alias

    • Goto: /admin/build/path/add in Drupal 6 (that's admin/config/search/path/add in Drupal 7)
    • Enter "caslogout" in the Existing system path field
    • Enter "logout" in the Path alias field
    • Click the CREATE NEW ALIAS button.

     

    Category: 

    CAS Logout Error

    Courtesy of Doug Curtis in OIT:

    People are receiving a 500 error when using the "GT Logout" link on a Drupal page.  It looks like the problem is that the Drupal CAS module is appending the "service=" query string to the end of the CAS logout url.  The GT CAS server will accept "url=" query string but it doesn't accept the "service=" query string. Previously, the CAS service would quietly ignore appended query strings it didn't recognize but that isn't currently the case.

    The way to fix this is to leave the "Logout destination" field blank in the phpCAS module's settings.  The "Logout destination" is supposed to be used to specify a url to redirect the user to after the user has been logged out.  It is NOT supposed to be the url for logging out of CAS.  By leaving the field blank, the application will be logged out of CAS but the user will still be authenticated in CAS.

    Category: 

    Update CAS library to latest version

    Step by step instructions on how to update your phpCAS library to the most current, secure version.

    For this example, we will update from version 1.3.2 to version 1.3.3. But the same steps should apply to updating between any versions of the phpCAS library (which allows logins with GTaccounts to our drupal sites).

    1. Download the latest version from http://downloads.jasig.org/cas-clients/php/current/
    2. If you don't want to use ssh/command line, "extract" the files from this compressed archive on your computer (Windows users can use the free 7-zip program to do so), which will create a folder called "CAS-1.3.3", that has another "CAS-1.3.3" and a "package.xml" file inside it.
    3. Change the name the second "CAS-1.3.3" folder (that is inside the other) to "CAS".
    4. Zip up that re-named "CAS" folder...usually by right-clicking and choosing either "Compress 'CAS'" or "Send to" > "Compressed (zipped) folder".
    5. Now that you have a friendly zipped file, named "CAS.zip", find where the CAS library lives on your server. The best practices location on a Drupal site is under the "sites/all/libraries" folder (which often requires you to add the "libraries" module to your Drupal site, first).
    6. Then, turn on your TEST site's maintenance mode (because, of course, you are not trying this out on your live site). For Drupal 7, you can enable this at: admin/config/development/maintenance
    7. Delete the current version of phpCAS that lives at "sites/all/libraries", so that there is no "CAS" folder anymore.
    8. Upload your new "CAS.zip" file to your Test site's libraries folder, so that it looks like this: "sites/all/libraries/CAS.zip".
    9. Check the box next to CAS.zip in your web hosting panel and then, from the menu of options at the top of your file list, choose "More" > "Extract Files" and then click "Okay".
    10. Once you see your new "CAS" folder, you can then delete the "CAS.zip" file from this directory and your library has been updated.
    11. Remove your Test site from maintenance mode and make sure it works correctly.
    12. If all goes well, follow the same process on your Live site.

     

    Category: 

    Using CAS to deliver GTED attributes

    CAS is capable of delivering some GTED attributes for the person logging in to Drupal, as part of the login process.  This means you don't have to configure and maintain an LDAP module nor manage an LDAP service account (read: no need to keep up with an expiring service account password).

    While GT's CAS service will provide authentication for any site within the ".gatech.edu" domain, by default it won't release any attributes.  You'll have to request what attributes your application needs by filling out this web form: https://iam.gatech.edu/gted/data_steward_request.html.  (Note that this is the same web form that you use to request a GTED LDAP service account.)  Make sure you specify CAS authentication and whatever data you need under Data Request.  Also, for the URL for your application, you'll want to specify something like "http://yoursite/**".  The double-asterisk is critical.

    Once that has been approved and CAS has been set up, configure Drupal to talk to CAS just as it's documented here on previous pages, except for the CAS Server Version, which needs to be set to "SAML Version 1.1".  If the user's email address is one of the attributes you're requesting from CAS, then you'll want to leave the email address field under User Accounts blank.

    Now, under the "Attributes" tab, click on the "CAS Attribute Tokens" button (not the "LDAP Attribute Tokens" if you have that).  It should show you a list of attributes Drupal is getting from CAS.  You may have to log out and log back in.  If you don't see the list, you may have to work with whoever handled your data steward request, sometimes these things take a bit of tweaking to get right.

    Still on the "Attributes" tab, click on the "Settings" button.  You'll want Drupal to "Fetch CAS Attributes" "everytime a CAS user logs in" because, well, people's data changes all the time.  You'll probably also want to always "Overwrite existing values" from attributes, to make sure Drupal doesn't store any old data.  Under CAS ATTRIBUTE MAPPINGS, specify "[cas:name]" for the Username field and "[cas:attribute:email_primary]" (assuming you requested that) as the E-mail address field.

    Category: