Setting up Shibboleth authentication within your Illinois Framework Drupal site

Login Error - updated 2/7/24

If you're seeing an error message when trying to log into your site, it appears that version 4.6.11 of the library simplesamlphp/saml2 has an issue. Downgrading the version to 4.6.10 fixes the error. Do do that, from your project folder, run the command:

composer require simplesamlphp/saml2:4.6.10

Clear the cache on your site, and you should be able to log into your site again.

SimpleSAML PHP 1.19 update / PHP 8 - updated 10/13/22

The release of PHP 8 required the update of SimpleSAMLPHP to version 1.19, which will require changes to the ~/illinois_framework/composer.json file.

Under the repositories section of your composer.json, you should see a line

"url": "/var/simplesamlphp-1.18"

Change that line to

"url": "/var/simplesamlphp-1.19"

Finally, save the changes to you composer.json and update your website.

Auto redirect to login - updated 3/4/22

The 2.1 release includes a plugin that will auto redirect users needing authentication to the login page. Set this redirection to use the campus Shibboleth login, go to Admin Toolbar -> Configuration -> Basic site settings and update the "Path to user login form" field to "/saml_login". You go directly there using https:///admin/config/system/site-information.

Instructions to set up Shibboleth authentication

The Illinois Drupal Framework project has coordinated with the cPanel hosting team to make getting Shibboleth authentication as easy as possible. Follow the steps below after installing the framework onto your cPanel site. With the below configuration, any valid user with a NetID will be able to log into your site and automatically create an account. That user will not have any additional permissions such as editing rights. To give that user additional permissions, you will need to find them on the People admin page and assign them a role like administrator or editor.

1. Open up a cPanel Terminal session or SSH into your site

2. CD to your project directory ~/illinois_framework

3. Run the below command to fetch the Drupal module simpleSAMLphp Authentication

    composer require drupal/simplesamlphp_auth:^4.0 -W
   

4. SimpleSAMLPHP is already set up and configured in cPanel on web.illinois.edu. The command below tells composer where to find it.

    composer config repositories.simplesamlphp '{"type": "path", "url": "/var/simplesamlphp-2.1.0"}'
   

5. Next, run composer update -W so that composer will find and use the cPanel version

6. Log into your framework site as an administrator

7. From the admin toolbar, click on "Extend"

8. Search for "Simplesaml" in the list of modules

9. Click the box next to "SimpleSAMLphp Authentication"

10. Click the "Install" button at the bottom of the page

11. After installing the module, go to the configuration page by going to Configuration->People->SimpleSAMLphp Auth Settings

12. Click on the "User info and synching" tab

13. Set the first two fields to "uid" ("SimpleSAMLphp attribute to be used as unique identifier for the user" and "SimpleSAMLphp attribute to be used as username for the user"

14. Check "Automatically enable SAML authentication for existing users upon successful login" on the same page and click "Save Configuration"

15. Click on the "Local Authentication" tab

16. Uncheck "Allow SAML users to set Drupal passwords" and click "Save Configuration"

17. Click on the "Basic Settings" tab

18. Check "Activate authentication via SimpleSAMLphp"

19. Change "Federated Log In Link Display Name" to "University of Illinois Login" and click "Save Configuration" You should now be able to authenticate using the UIUC Shibboleth login system! If you go to /user/login for your site, you should see a "University of Illinois Login" button. Clicking on that will take you to the Shibboleth login page.