EID authentication for Drupal on Pantheon
By default, Drupal site accounts use a local username/password combination for authentication. Sites may switch to EID authentication using the university’s Enterprise Authentication system as detailed below.
Table of Contents
- Integrating Enterprise Authentication
- Quarterly user review
- Restricting access by university affiliation
IMPORTANT: Pantheon and Drupal do not natively support restriction of content based on EID's, roles, or affiliations. For more information about how to implement content restrictions based on EID, see "Restricting access by affiliation," below.
Integrating Enterprise Authentication
1. Request integration
ITS must add metadata about your Pantheon site for it to leverage Enterprise Authentication. To start this process, fill out the Pantheon SAML Integration request form, which will create a support ticket in ServiceNow. Turnaround time for Enterprise Authentication integration requests is 2-3 business days.
2. Add the "Pantheon SAML Integration" plugin
ITS maintains a Composer plugin that facilitates Enterprise Authentication integration. In the local directory where you installed your site (see above), run the following:
composer require utexas/pantheon_saml_integration "^3 || ^4"
These are dependencies downloaded by the above package:
After the Composer process completes, make sure to version control and deploy to Pantheon.
3. Configure the module
Navigate to Configuration > SimpleSAML php Auth Settings (/admin/config/people/simplesamlphp_auth). The available configuration options are below, with notes:
- Activate authentication via SimpleSAMLphp. Leave this checked.
- Installation directory. This is Pantheon environment specific and cannot be changed.
- Authenticaton source for this SP. This is Pantheon environment specific and cannot be changed.
- Federated Log In Link Display Name. This text is displayed on /user as a link to the UTLogin URL callback and may be changed.
- Login path. This path cannot and should not be changed.
- Register users (i.e., auto-provisioning). This generally should be left unchecked. Auto-provisioning accounts will add any user who logs in via the federated login path as an "authenticated user," which, depending on your site permissions schema, may unintentionally open content to visitors, and at the very least, will make quarterly user review (see below) rather daunting.
Quarterly user review
It is the site owner's responsibility to periodically review the users who have access to the site, and when necessary, remove or adjust the privileges of any users who should no longer have access to the site. This review should be performed at least once every 3 months.
To begin this process, a user with the "Administer users" permission should navigate to the "People" page (/admin/people) from the admin menu, and review for their "Active" status as well as their currently authorized roles:
If a user no longer needs access to your site, we recommend both removing all of their roles, and disabling the account.
The "People" page listing on UT QuickSites instances shows the users' UT EID and official UT email address. If you cannot recognize the identity of a user directly from the EID or email address, you can search for a user by EID in the UT Directory or the UT Community EID Listing (EID login required).
If a user does not show up in the UT Directory when searching by the UT EID, you should probably assume that this user is no longer affiliated with UT Austin, and block their account as a precautionary measure until their identity can be confirmed.
The UT Community EID Listing does include EIDs of users who are not actively affiliated with UT Austin, and can potentially provide more clues to a user's identity.
Blocking User Accounts and Removing Roles
First, click the "edit" button in the "Operations" column for the user you want to disable:
Next, change the user status setting from "Active" to "Blocked," and uncheck all roles:
There are multiple click-paths that can be used to block a user or to completely delete the account.
Full account deletion is not necessary, and forces the site manager to make decisions about how to handle content that was authored by the user being deleted. We recommend blocking user accounts and removing all roles as the simplest solution for de-authorizing users who no longer should be able to access a site.
Restricting access by university affiliation
It is possible to restrict access to all or part of a Drupal site based on visitors’ affiliation with the University of Texas. This can meet the needs of a departmental staff intranet or a website that needs to restrict a subset of pages to current and incoming students.
How to request integration
Restricting access to content based on University affiliation is optional functionality that must be enabled by ITS. It is only available for sites hosted on Pantheon. To initiate a request for this capability, email email@example.com with subject line “Request for EID-restricted content”. Include the name or domain of the site in your email body.
- Anonymous user: a user who is viewing a website without being logged in to that site.
- Authenticated user: a user who has logged into a Drupal site using their UT EID credentials.
- Drupal user role: A collection of Drupal permissions which can be assigned to one or more users.
- EID affiliation: An affiliation specifies a person’s relationship (or relationships) to the university in broad terms. At any point in time, an individual may have no defined relationship, one defined relationship, or many defined relationships with the university. See https://ut.service-now.com/sp?id=kb_article&number=KB0014971 for more information.
Design and behavior
- This solution protects pages created in Drupal. It does not protect files uploaded to a Drupal site, such as PDFs or MS Office documents. ITS recommends the use of a file-sharing platform such as Box or SharePoint for sharing documents instead of uploading them to your Drupal site. Both platforms support restricting access to current UT affiliates.
- University affiliations are broad categories, such as “Current Staff” or “Prospective Student.” Content cannot be restricted, for example, to students enrolled in a specific program. For a complete list of EID affiliations, see https://ut.service-now.com/sp?id=kb_article&number=KB0014971.
- The site will automatically create a new Drupal user account, upon sign-in, for anyone who holds an allowed affiliation. Site managers do not need to create accounts beforehand.
- Each time a visitor signs in, the Drupal roles are updated based on the visitor’s current university affiliations.
- Drupal user roles are associated with EID affiliations to be used for restricting content access.
- ITS recommends setting up one Drupal user role per EID affiliation to be used (e.g., a "Current student" user role for the "Current student" EID affiliation, a "Current faculty" user role for the "Current faculty" EID affiliation).
- All Drupal content types on the site are eligible for setting access rules by role.
- A special permission allows higher level site roles such as site managers and content editors to always bypass the page restriction rules while they are logged in to prevent getting locked out from editing.
Restricting access to specific pages
To restrict access to a page, go to the page's "Edit" screen. Open the "Page access" vertical tab in the right sidebar. After selecting the checkbox labeled "Protect access by role," the content editor will be able to select which roles can access this page:
NOTE: Roles with the permission to bypass content restrictions are automatically excluded from the list of roles to select. In most cases, the "Content editor" and "Site manager" roles should not be seen here.
After saving the page, the current restrictions will be shown in a confirmation message:
Menu links for pages which have been restricted to a specific role or roles will be visible to all users, but will display with a lock icon in the title:
Resulting behavior for site visitors
- When anonymous users visit restricted pages, they will automatically be directed to the UT EID login page. After successful authentication, they will be redirected back to the site.
- If the authenticated user does not have any of the affiliations configured for use with the site, they will be immediately logged out and their Drupal user account deleted.
- If the authenticated user does have an affiliation supported by the site but not one configured for the page they were trying to view, they will see an "Access denied" message.
- Menu links for pages which have been restricted to a specific role or roles will be visible to all visitors and will display with a lock icon in the title.
- Links which directly reference files in the filesystem on the same host as the Drupal site will NOT automatically be restricted. For secure file sharing, use a dedicated file sharing platform such as Box or SharePoint. Both platforms support restricting access to current UT affiliates.
- Media items (such as images) embedded on restricted pages will be restricted using the same rules as the page on which they are embedded. However, the files associated with the media items should be assumed to be accessible by anyone who has the URL directly to the file, since these links bypass Drupal.
- Users who sign in to view restricted content will have a permanent Drupal user account created on the site, with user roles matching their current UT EID affiliations. This may result in many users on the site.
- The Drupal "Views" module honors these access restrictions in the same way that it does with Drupal's other built-in permissions, meaning that restricted content will not be visible in lists of content created using Views for users who are not already authenticated. For example, if a news article is restricted by role, that article will not display for unauthenticated users in news listing blocks or on the news listing page.