VIP Go platform specific
This document is for sites running on VIP Go.
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 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 #
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 ensuring 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 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
- 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 password.
- 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. One way this can be implemented is by checking for requests from the Automattic network, as described here.
QA Recommendations #
We have a few recommendations for clients to test their SSO configuration before launch.
Check users #
- 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.