pressbooks/pressbooks-saml-sso

Shibboleth Single Sign-On integration for Pressbooks.

1.0.3 2019-05-13 19:05 UTC

README

Contributors: conner_bw, greatislander
Tags: pressbooks, saml, saml2, sso, shibboleth
Requires at least: 5.2
Tested up to: 5.2
Requires PHP: 7.1
Stable tag: 1.0.3
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html

SAML2 Single Sign-On integration for Pressbooks.

Description

Packagist GitHub release Travis Codecov

Plugin to integrate Pressbooks with a SAML2 single sign-on service. (Shibboleth, Microsoft ADFS, Google Apps, Etc.)

Users who attempt to login to Pressbooks are redirected to a Shibboleth or SAML2 Identity Provider. After the user’s credentials are verified, they are redirected back to the Pressbooks network. If we match a Pressbooks user by UID (stored in user_meta table), the user is recognized as valid and allowed access. If no match, then try to match a Pressbooks user by email (and store a successful match in user_meta table for next time). If the user does not have an account in Pressbooks, a new user can be created, or access can be refused, depending on the configuration.

Limitations: This plugin does not enable authentication with multilateral Shibboleth. For use in a non-federated, bilateral configuration, with a single IdP.

Installation

composer require pressbooks/pressbooks-saml-sso

Or, download the latest version from the releases page and unzip it into your WordPress plugin directory: https://github.com/pressbooks/pressbooks-saml-sso/releases

Then, create the necessary certificates:

cd vendor/onelogin/php-saml/certs
openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out sp.crt -keyout sp.key

Then, activate and configure the plugin at the Network level.

Security Considerations

Generating certificates in vendor/onelogin/php-saml/certs, without further changes, will expose them to malicious users (Ie. https://path/to/vendor/onelogin/php-saml/certs/sp.crt). Furthermore, your certificates are at risk of being deleted when updating packages using composer update or similar commands. A competent sysadmin must make sure certificates are not accessible from the internet nor deleted. It is highly recommended that you pass your certificates via configuration variables. Example:

add_filter( 'pb_saml_auth_settings', function( $config ) {
	$config['sp']['x509cert'] = file_get_contents( '/path/to/sp.key' );
	$config['sp']['privateKey'] = file_get_contents( '/path/to/sp.crt' );
	return $config;
} );

Or:

define( 'PHP_SAML_SP_KEY_PATH', '/path/to/sp.key' );
define( 'PHP_SAML_SP_CERT_PATH', '/path/to/sp.crt' );

IdP Setup

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. Your metadata XML can be downloaded from this page.

The plugin requires the Assertion elements of the Response to be encrypted.

The plugin requires the Assertion elements of the Response to be signed.

The plugin looks for the following Attributes in the Response: (For compatibility with a broader range of IdPs we use the FriendlyName parameter.)

  • Requires: uid (urn:oid:0.9.2342.19200300.100.1.1, samAccountName, or equivalent)
  • Strongly recommends: mail (urn:oid:0.9.2342.19200300.100.1.3, email-address, or equivalent) If no value is available we fall back to uid@127.0.0.1
  • Optional: eduPersonPrincipalName (urn:oid:1.3.6.1.4.1.5923.1.1.1.6, or equivalent) Upon the first launch for a given user, if mail cannot match an existing person, and this value is present, we'll try to use it.

The email can be filtered, example: add_filter( 'pb_integrations_multidomain_email', function( $email, $uid, $plugin ) { /* Custom use case, return $email */ }, 10, 3 );

Because this plugin uses the fabulous onelogin/php-saml toolkit, many other configuration variables can be tweaked.

Screenshots

SAML2 Administration.

Metadata XML.

Changelog

1.0.3

Upgrade Notice

1.0.3

  • Pressbooks SAML2 Single Sign-On requires Pressbooks >= 5.8.0