Single Sign On (SSO, not to be confused with Jetpack SSO) is possible for clients using an identity provider (IdP) that supports SAML (or Security Assertion Markup Language). We do not support other SSO technologies at this time. We also cannot install any middleware required in some Shibboleth configurations. Most IdPs can support SAML.
Setting up the IdP
SAML IdP’s require you to register the VIP Go application as a service provider. They have different ways of approaching this but the purpose is to:
- Set up the application as a legitimate service provider.
- Tell the IdP where and how to communicate with your VIP Go application.
- Generate the certificate and URLs the IdP will use to send and encrypt communication with the VIP Go application.
Most IdPs have an application creation here’s the documentation for creating custom applications on major IdPs:
You will need:
- The ACS location, usually
example.com/wp-login.php/?saml_acs(where example.com is your domain)
- The entity-id:
Once you create your SAML application, the IdP will provide the following:
- Entity ID (a unique URL)
- Single Sign-on URL
- X.509 Certificate to setup WordPress.
Setting up WordPress
Use one of these plugins:
- Human Made’s WordPress Simple SAML
- OneLogin’s WordPress SAML
Human Made WordPress Simple SAML
Human Made’s WordPress Simple SAML plugin stores the SAML configuration in code and facilitates SAML without extra settings screens. Because of how Human Made approached this and how our platform works, we require some extra code in your theme’s functions.php file. If you need help generating this code, reach out, and we’ll provide the code for use with this plugin. The helper code handles configuring the IdP and mapping your roles. Your developers will want to take a close look at this before launch. Loading the SAML configuration from an XML file provided by your IdP is currently not supported on VIP Go.
Onelogin’s WordPress SAML
OneLogin’s WordPress SAML plugin is managed through a settings page where you can fully configure your system. If you’re using this plugin, make sure you also have our helper plugin installed to your
client-mu-plugins directory so that cookies and other SSO settings are appropriately handled by our Varnish cache.
Options and Settings
You can mostly choose how to configure your own SSO. Some settings may be dictated by your IdP. Some are required by VIP. If you’re doing a lot of custom configuration, we highly recommend you thoroughly test your SSO setup on your VIP Go application before launch.
Here are our recommended settings (these are under the “Options” heading of the OneLogin plugin):
- Create user if not exists: This causes WordPress to create local accounts for users that sign in over SSO. Required
- Update user data: This causes user attributes like first name, last name, and email address to change on WordPress when they change in your IdP. Recommended
- Single Log Out: only useful if the client’s IdP supports it. Not recommended
- Keep Local login: This will enable the standard login form on WordPress. Required
- Alternative ACS Endpoint: Not supported
- Match WordPress account by: You can choose how to match your users to their IdP accounts.
There are many additional options and settings. For the most part, you shouldn’t need to change these unless your IdP requires it.
Notes on role mapping
You’ll need to know the format of the attributes in your IdP that correspond to the following basic parts of a WordPress user profile:
- First name
- Last name
IdP roles typically don’t match WordPress’s. Clients will need to map their IdP’s roles to the roles on their Go application. Client’s do not need to map every role, and more than one role can be mapped to a given WordPress role. Any users without a match will be assigned the default role, “Subscriber.”
Multiple IdP role assignments
If a user has more than one role, the plugin will choose a assign based on the lowest match in a ranking defined by the client. Here’s an example to illustrate how this works:
A news organization has users grouped into six roles: developer, editor, writer, advertising, marketing, and new-hire. You have the following mapping for your roles
- Administrator: developer
- Editor: editor
- Author: writer, advertising, marketing
- Contributor: new-hire
“Contributor” has the lowest value in the ranking.
When a new writer is hired, they are both a “writer” and “new-hire” in the IdP. The plugin resolves this conflict by assigning the lowest-ranked role, in this case, “Contributor”. With “Update user data” enabled, their role should promote to “Author” once the new-hire role is removed.
We can help clients determine the lowest-risk ranking for this setting that works for their organization. We should strongly advise against setting “Administrator” as the lowest.
Preventing unauthenticated site access with SSO
The only way to make a VIP Go site private is by requiring SSO authentication across the entire site. To do this, use the OneLogin plugin and enable the following:
- Force SAML Login
- Prevent use of
?normal(under custom actions and links)
VIP support users can still access the site because the helper plugin disables SSO for proxied requests.
Requiring SSO to login
We require the creation of local accounts on the WordPress install so that we can more easily troubleshoot when users are having problems. This doesn’t prevent the client from requiring SSO to log in. If the client requires SSO for all logins from their users, enable the following options in the OneLogin plugin’s settings:
- Prevent reset password: This will prevent users from resetting their WordPress account passwords.
- Prevent change password: This will prevent users from changing their WordPress password.
- Prevent change mail: This will prevent users from changing the email address in their WordPress account profile.
We have a few recommendations for clients to test their SSO configuration before launch.
- Create test users within the IdP, create one for each role that mapped to WordPress to make sure users have the right role when they sign in.
- Test any known role conflicts to make sure they are resolved as you expected.
- Test whether users can successfully log in and out without affecting other SSO sessions in their organization
Test content protections
- If the entire site requires authentication, make sure clients verify by anonymously access the site
- Make sure all login requests go through the single sign-on process.