Single Sign On (SSO)

Single Sign On (SSO, not to be confused with Jetpack SSO) is possible for clients using any 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 IdP’s can support SAML.

Setting up the Identity provider(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

Here’s the documentation for creating custom applications on most major IdP’s:

Okta

OneLogin

Google G Suite

Microsoft Azure Active Directory

SecureAuth

MiniOrange

Auth0

You will need:

• The ACS location, usually example.com/wp-login.php/?saml_acs (where example.com is your domain)
• The entity-id: php-saml

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

In order for our team to continue to provide support for your application, we have the following requirements:

• You must configure your SSO plugin to create local user accounts
• If you force SSO for all users, you must provide a way for support users to circumvent the SSO flow on login
• If you force SSO on all pages of the site, you must expose the XML-RPC endpoints to Jetpack requests

To allow users to circumvent the SSO flow, the easiest way is to provide a url parameter like wp-login.php?normal that directs users to the wp-login form. A more secure way is to detect if a user is accessing the site through VIP’s proxy servers.

Use one of these plugins:

• OneLogin’s WordPress SAML
• Human Made’s WordPress Simple SAML

OneLogin’s WordPress SAML plugin

OneLogin’s WordPress SAML plugin works with any IdP and is managed through a settings page where you can fully configure your application. If you’re using this plugin, make sure you also have our helper plugin installed to your client-mu-plugins directory which takes care of some of the required details above and also ensures cookies and other SSO settings pass through our cache layers.

Options and Settings

You can mostly choose how to configure your own SSO. Some settings may be dictated by your IdP. 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 non 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
• 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.

WordPress Simple SAML plugin

Human Made’s WordPress Simple SAML plugin also works with any IdP but 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.

Notes on role mapping

Sometimes the role sent by an IdP doesn’t match a role in the WordPress install. If this is the case, you have three options for resolving the mismatch. Any users without a matching role will be assigned the default, usually “Subscriber.”

• Create roles in your WordPress application that match your IdP.
• Create roles in your IdP that match roles in WordPress.
• Map your IdP’s roles to existing roles in WordPress. You do not need to map every role, and more than one role can be mapped to a given WordPress role.

Preventing unauthenticated site access with SSO

The only way to make a VIP Go site “private” is by requiring SSO authentication to access any page on your entire site. To do this, use the OneLogin plugin and enable the “Force SAML Login” option. You must still provide a method for VIP Support to circumvent SSO to access the site.

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 account passwords.
• Prevent change mail: This will prevent users from changing the email address in their WordPress account profile.

Exceptions for VIP Support

• VIP Support must have a way to login, bypassing SSO. This can be done by checking for and allowing requests when true === A8C_PROXIED_REQUEST by using the utility function is_proxied_request().

QA Recommendations

We have a few recommendations for clients to test their SSO configuration before launch.

Check users

• Create test users within the IdP, one for each role that’s 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 accessing the site.
• Make sure all login requests go through the single sign-on process.