OIDC Log In Flow

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

1. From the login page the user selects ‘Institutional Login’ (this step can be bypassed, using a configuration setting)
2. The user is brought to a “Where Are You From” (WAYF) wayfinder tool which allows them to select their institution. They should select the institution for which they have login credentials.
3. Once they have entered their institution, they will be redirected to their institution’s login page, and will be prompted to enter their NetID and password.
4. Their institution’s IdP authenticates the user and sends the Pressbooks service provider a set of claims about the authenticated user.
5. Pressbooks checks the security domain from this claim against a lise of approved security domains for this particular network. If a match is found, Pressbooks then checks to see whether a matching user exists. If a matching user is found, the user is logged in as this person.
6. 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.

Configuration Settings

High-level configuration of the OIDC SSO plugin will be handled by the Pressbooks support team. However, Network Managers can configure a few additional settings as they prefer after the integration has been completed. To navigate to the OIDC settings page, go to the Network Admin dashboard. Then, select Integrations > OIDC from the left sidebar menu. The OIDC settings page can be found at located at https://[YOURNETWORKURL]/wp-admin/network/admin.php?page=pb_oidc_admin

If the OIDC User does not have a Pressbooks account

This setting controls what happens if Pressbooks receives an authenticated user from an authorized institution. 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.

Forced Redirection 

This setting allows you to hide the default Pressbooks login page and send users directly to the insitutional IdP wayfinder page. The setting is turned off by default.

If unchecked, users will see the standard Pressbooks sign in form and can choose whether to sign in with their Pressbooks credentials or with their institutional credentials. To log in with their institutional credentials, the user would need to click Institutional Login. 

If Forced Redirection is checked, the sign in menu link would then direct users automatically to the Institutional Login wayfinder. To enable forced redirection, select the checkbox next to “Hide the Pressbooks login page” and save your changes.

Customize Button Text

This setting allows you to change the OIDC login button text from the default ‘Institutional Login’ value to a phrase of your choosing.

Exchanging Metadata

OIDC establishes a multilateral SSO connection in which the the central consortium Pressbooks network at permits institutional logins from several different IdPs (each being an institution). In order for this SSO process to work smoothly for users, Pressbooks needs to be registered as an authorized Service Provider (SP) with each Identity Provider (IdP), and each IdP needs to be registered with our platform. This typically involves the exchange of metadata.

From the Pressbooks side, we send the IAM contact at each institution our SP metadata file. If the IdP is already registered with a Federation like eduGAIN, InCommon, or CANARIE, we can typically access their IdP metadata there (as Pressbooks is a member of both CANARIE and eduGAIN). If the IdP is not a member of an identity federation, Pressbooks staff can manually register the IdP metadata for use with our service provider. We can accept either URL endpoints or the SAML metadata document itself for an institution’s IdP.

Requested Claim Values

Each participating IdP must release a set of requested claims so that Pressbooks can verify an authenticated user and perform the necessary checks before making an authorization decision. Each IdP must release the following claims:

1. An email address (i.e. fakeuser@email.university.edu) with the claim name urn:oid:0.9.2342.19200300.100.1.3. If no email address is provided, a noreply value will be supplied instead, and no user matching with existing Pressbooks users will be possible.
2. The user’s eduPersonPrincipalName (EPPN i.e. mynetid@university.edu) with the claim name urn:oid:1.3.6.1.4.1.5923.1.1.1.6. This claim be a scoped value with an unique identifier for the user [i.e. mynetid] and the unique security scope for the IdP [i.e. @university.edu]. If this value is not provided, we may not be able to check the user’s security domain against our allowlist which will result in their being refused access to the network.
3. [Optional] The users’s membership role (i.e. student@university.edu) with the claim name urn:oid:1.3.6.1.4.1.5923.1.1.1.9

Once the service provider & IdP information has been registered on both ends, and the proper claim values are being sent forth, the SSO flow should work in accordance with the configuration settings selected for a given network.