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 #
Use one of these plugins:
- OneLogin’s WordPress SAML
- Human Made’s WordPress Simple SAML
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.
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.
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 two 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 existingroles 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 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.
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.