SAML2 Log In Flow

When correctly configured, the login flow for this plugin is as follows:

1. From the login page the user selects ‘Connect via SAML2’ (this step can be bypassed, using the Forced Redirection configuration setting)
2. The user is brought to their institution’s login page, and will be prompted to enter their NetID and password.
3. Their institution’s IdP authenticates the user and sends the Pressbooks service provider a set of claims about the authenticated user.
4. 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.
5. 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 to samAccountName or equivalent. This can be sent with the FriendlyName uid)
• Strongly recommends: urn:oid:0.9.2342.19200300.100.1.3 (with a value corresponding to email-address, or equivalent. This can be sent with FriendlyName mail). 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 to eduPersonPrincipalName or equivalent). Upon the first launch for a given user, if we cannot match the urn: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:

1. 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 attribute urn:oid:0.9.2342.19200300.100.1.1)
2. If uid is not found, we try to find a matching user by searching for a match between the urn:oid:0.9.2342.19200300.100.1.3 (email) attribute and the email addresses for existing users.
3. 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.
4. If no matching user is found through any of these methods, we create a new user.