Pressbooks SAML SSO

Table of Contents

Plugin to integrate Pressbooks with a SAML2 single sign-on service. (Shibboleth, Microsoft ADFS, Azure, etc.)

Limitations: This plugin is restricted to non-federated, bilateral configuration with a single IdP only.

This documentation is up to date as of version 1.6.1 of the Pressbooks SAML2 Single Sign-on plugin.

Installation / Activation

Get the plugin here: https://github.com/pressbooks/pressbooks-saml-sso.

The SAML2 SSO plugin is installed and activated on the network level. Follow the steps in the README file. Be sure to correctly install, configure, and secure the security certificates.

Admin interface description

Upon activation of the plugin, a submenu item (“SAML2”) is added to the Network Admin interface under “Integrations”. This leads to the SAML2 settings page:

Screenshot 1

Your network's Service Provider (SP) metadata can be viewed and downloaded from the hyperlink that appears at the top of this settings page:

Screenshot 2

Required Settings

The following information is required for the SAML IdP you want to integrate with Pressbooks:

Decide the response if the SAML2 user does not have a Pressbooks account: Refuse Access OR Add New User

Note: If the Network Setting for "Allow New Registrations" is set to "No Registrations Allowed", the SAML2 "Add New User" setting will bypass the Network Settings and register new users. For detailed behaviour on new user handling, see the section Details of settings behaviour: Add New user / Refuse access behaviour below.

Optional settings:

By default, this plugin requires the Assertion elements of the Response sent by the Identity Provider (IdP) to be both encrypted and signed. If you are self-hosting a Pressbooks network, you can change these settings with a filter, for example:

add_filter( 'pb_saml_auth_settings', function( $config ) {
	$config['security']['wantAssertionsEncrypted'] = false;
	$config['security']['wantAssertionsSigned'] = false;
	return $config
} );

Details of settings behaviours:

Bypass domains behaviour:

If the Bypass option is OFF: Pressbooks' Network settings for both authorized and banned email domains will be applied and enforced.

If the Bypass option is ON: The "Limited Email Registrations" and "Banned Email Domains" lists will not be applied or enforced in the case of SAML2 logins. For example, a user will still be created even if the email domain entered in SAML2 settings matches a Banned Email Domain.

Forced Redirection behaviour:

If Forced Redirection is OFF, the "Sign In" link from the network website homepage brings the user to the Pressbooks login page, where a "Connect via SAML2" button will appear in the login form. Clicking on this button will bring the user to the login page for the configured IdP.

If Forced Redirection is ON, the "Sign In" link will bring the user directly to the login page for the configured IdP.

Add New User / Refuse Access behaviour:

  1. If no Pressbooks user exists for this SAML2 user
  1. If there is an existing Pressbooks user for this SAML2 user

Customize Button Text

The button can accept multiple lines of text. Add a <br /> tag in the button text to insert a line break.

Requested Attributes

The plugin looks for the following Attributes in the Response:

User identification mechanism

When a user logs into Pressbooks via SAML2, the SAML2 plugin will attempt to find an existing user corresponding to the user who is logging in. If it does not find the user, the SAML2 plugin will either create a new user or refuse access (depending on which option has been selected).

The user matching mechanism is as follows:

  1. Plugin tries to find a user where wp_usermeta.meta_key = pressbooks_saml_identity and wp_usermeta.meta_value = uid
    • Where uid is the unique ID sent by the Identity Provider with the required attribute name urn:oid:0.9.2342.19200300.100.1.1
  2. If uid is not found, try to find a matching user by comparing the recommended urn:oid:0.9.2342.19200300.100.1.3 (email) attribute to existing users' email address.
  3. If no match is found, try to find a matching user by comparing the optional eurn:oid:0.9.2342.19200300.100.1.3 (ePPN) attribute to existing users' email addresses.
  4. If no matching user is found through any of these methods, create a new user.
    • wp_usermeta.meta_key and wp_usermeta.meta_value are set by the SAML2 plugin upon user matching or new user creation to ensure that subsequent logins by this user will follow case #1 above even if the user changes their email address.

Network admins who have manually created or plan to manually create new users in Pressbooks should take care to use the correct user email address for these manually created accounts so that the SAML2 plugin can properly match this user if they subsequently attempt to log in via SAML2.

Note: Pressbooks usernames are never used for matching purposes.