Configure SSO for a Single Institution
Pressbooks can be intregrated with your institution’s SAML2 single sign-on service (Shibboleth, Microsoft ADFS, Azure, etc.). This guide chapter describes configuration options for a single Pressbooks network and a single IdP. If you’d like to connect your Pressbooks networks to multiple IdPs (if you’re a network manager for a consortium, for example), please view our guide chapter about OIDC.
Setting this up may require assistance from someone who manages Identity and Access Management at your institution. You may want to refer them to Requested Attributes and User Identification Mechanism sections of this chapter.
SAML2 Log In Flow
When correctly configured, the login flow for this plugin is as follows:
- From the login page the user selects ‘Connect via SAML2’ (this step can be bypassed, using the Forced Redirection configuration setting)
- The user is brought to their institution’s login page, and will be prompted to enter their NetID and password.
- Their institution’s IdP authenticates the user and sends the Pressbooks service provider a set of claims about the authenticated user.
- Upon receiving the expected claims, Pressbooks checks to see whether a matching user exists. If a matching user is found, the user is logged in as this person.
- If no matching user is found, Pressbooks either creates a new account for this user or refuses access, depending on the configuration setting.
The video below shows this login flow for a test user using the SAMLtest service as the IdP.
SAML2 Settings Page
After our SAML2 SSO plugin has been activated on your network by Pressbooks support staff, network managers will see a SAML2 in their Network Admin dashboard under Network Admin > Integrations > SAML2. This leads to the SAML2 settings page (located at https://[YOURNETWORKURL]/wp/wp-admin/network/admin.php?page=pb_saml_admin).
Your network’s Service Provider (SP) metadata can be viewed and downloaded from the hyperlink that appears at the top of this settings page within “Metadata XML Configuration”:
Automatic Configuration
You can automatically configure this plugin by entering your IdP’s Metadata URL in the IdP Metadata URL and clicking Save Changes. When supported by your IdP, this will automatically populate the required fields by reading the values provided by your IdP.
Manual Configuration
If your IdP does not provide a metadata URL, or the automatic configuration does not correctly populate the fields, you can configure the plugin manually. To complete manual configuration, supply the relevant values for the following fields from your IdP metadata:
- EntityID
- SingleSignOnService
- SingleLogoutService [optional]
- X509Certificate
Configuration Settings
If the user does not have a Pressbooks Account
This setting controls what happens after Pressbooks receives the identity claims for a user who has been authenticated by your IdP.
If you would like all users from your institution(s) to have accounts created in Pressbooks the first time they login with their institutional credentials, select Add New User from the dropdown menu. This option allows your institution to use SSO as a method of self-registration.
If you would like only pre-existing users to be able to access the Pressbooks network via SSO, select Refuse Access from the dropdown menu. If you select this option, any person who does not already have an account created will be denied access to the network until a network manager creates an account for them. If an account is manually created for them, they can log in with their institutional credentials per normal.
Bypass
This setting controls whether or not the “Limited Email Registrations” and “Banned Email Domains“ settings will be consulted for users who are logging into your site via SSO.
If this field is checked, users who have been authenticated by your IdP will be handled according to your “If the user does not have a Pressbooks account” option you’ve selected, no matter what settings you have set up for your network. This is the recommended option for most users.
If this field is unchecked, Pressbooks’ Network settings for both authorized and banned email domains will be applied and enforced even for users who have authenticated via your IdP.
Forced redirection
This setting allows you to hide the default Pressbooks login page and send users directly to your insitution’s IdP login page. The setting is turned off by default.
If unchecked, the “Sign In” link from the network website homepage will bring 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 institution’s SAML2 login page.
If checked, the “Sign In” link will bring the user directly to their institution’s IdP login page.
Customize Button Text
This setting allows you to customize the label of the “Connect via SAML2” button displayed on the standard Pressbooks login page. Many networks choose to use a more recognizible phrase like ‘Login with your NetID’. If Forced Redirection is checked, then this field is disabled.
Requested Attributes
The plugin looks for the following Attributes in the Response:
- Requires:
urn:oid:0.9.2342.19200300.100.1.1
(with a value corresponding tosamAccountName
or equivalent. This can be sent with the FriendlyNameuid
) - Strongly recommends:
urn:oid:0.9.2342.19200300.100.1.3
(with a value corresponding toemail-address
, or equivalent. This can be sent with FriendlyNamemail
). If no value is available we fall back to uid@127.0.0.1 - Optional:
urn:oid:1.3.6.1.4.1.5923.1.1.1.6
(with a value corresponding toeduPersonPrincipalName
or equivalent). Upon the first launch for a given user, if we cannot match theurn:oid:0.9.2342.19200300.100.1.3
value to the email address of an existing user, we’ll attempt to look for an existing user whose email address matches the value of this attribute.
User identification mechanism
When a user logs into Pressbooks via SAML2, we will attempt to find an existing user corresponding to the user who is logging in. If we do not find a matching user, the SAML2 plugin will either create a new user or refuse access (depending on how you have configured the plugin).
Our user matching flow is as follows:
- We search the user meta for existing users to see whether we have matching metadata from a previous SSO login (we check to find any users
where wp_usermeta.meta_key = pressbooks_saml_identity and wp_usermeta.meta_value = uid
(uid = the mandatory requested attributeurn:oid:0.9.2342.19200300.100.1.1
) - If
uid
is not found, we try to find a matching user by searching for a match between theurn:oid:0.9.2342.19200300.100.1.3
(email) attribute and the email addresses for existing users. - If no match is found, we try to find a matching user by comparing the optional
urn:oid:0.9.2342.19200300.100.1.3
(ePPN) attribute to existing users’ email addresses. - If no matching user is found through any of these methods, we create a new user.
Notes about user identification:
wp_usermeta.meta_key
andwp_usermeta.meta_value
are set by the SAML2 plugin upon user matching or new user creation. As a result, subsequent logins by a newly created 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.
- Pressbooks usernames are never used for matching purposes.