How to Properly Setup SAML Single Sign-On (SSO) in WordPress

How to Properly Set Up SAML Single Sign-On (SSO) in WordPress (2023)

Does your organization use a single sign-on (SSO) solution to manage user access to web applications? Do you want to allow users to log into your WordPress site using their existing SSO credentials?

Implementing SSO in WordPress offers significant benefits in terms of user experience and security. It spares users from having to create and remember yet another username and password combo. SSO also allows administrators to maintain control over user accounts and authentication policies through a central identity provider.

In this guide, we‘ll walk through how to properly set up Security Assertion Markup Language (SAML), one of the most popular SSO standards, in WordPress. We‘ll cover what you need to know in 2023, including:

• An overview of SAML and its advantages for WordPress
• Step-by-step instructions for two methods of enabling SAML in WordPress
• Tips and best practices to ensure a smooth and secure SSO experience

Whether you‘re connecting WordPress to Google Workspace, Azure AD, Okta, or another identity provider, this post will help you get SAML SSO up and running on your site. Let‘s jump in!

Understanding SAML and Its Benefits

SAML is an open standard that allows users to access multiple web applications using a single set of login credentials. It works by establishing trust between a service provider (SP) and an identity provider (IdP).

In the context of WordPress SSO:

• Your WordPress site functions as the service provider. It consumes identity information from the IdP to authenticate users.
• The identity provider is a third-party platform that manages user identities and access, such as Google Workspace, Azure AD, Okta, OneLogin, etc.

Here‘s a simplified overview of the SAML authentication flow:

1. A user tries to access your WordPress site and clicks on the SSO login link/button.
2. WordPress sends an authentication request to the identity provider.
3. If the user isn‘t already logged into the IdP, they are prompted to enter their SSO credentials.
4. After successful authentication, the IdP sends a SAML assertion (a signed XML document) back to WordPress.
5. WordPress validates the SAML assertion and logs the user into the site. Additional logic may be performed, such as creating a new WordPress user account or updating an existing one.

Advantages of SAML SSO for WordPress include:

• Improved user experience: Users can access your WordPress site with a single click, without needing to enter a separate username and password. This is especially convenient if they are already logged into the identity provider.
• Enhanced security: SAML uses secure tokens and digital signatures to protect user credentials and prevent unauthorized access. It reduces the risk of password-related vulnerabilities, such as weak or reused passwords.
• Centralized user management: Administrators can manage user accounts, access rights, and authentication policies through the identity provider. Any changes are automatically propagated to WordPress and other connected applications.
• Reduced support costs: With fewer passwords to manage, users are less likely to run into login issues or require password resets. This can help reduce the workload on your support team.

Now that we understand the basics of SAML and why it‘s beneficial, let‘s look at how to actually implement it in WordPress.

Method 1: Using the miniOrange SAML Single Sign On Plugin

The simplest way to add SAML capabilities to WordPress is by using a plugin. In this method, we‘ll use the free miniOrange SAML Single Sign On plugin, which supports a wide range of identity providers.

Step 1: Install and Activate the Plugin

1. Log into your WordPress admin dashboard and navigate to "Plugins" → "Add New".
2. Search for "miniOrange SAML" in the plugin repository.
3. Locate the miniOrange SAML Single Sign On plugin and click "Install Now".
4. After installation, click "Activate" to enable the plugin.

Step 2: Configure WordPress as the Service Provider

1. In your WordPress admin sidebar, navigate to "miniOrange SAML 2.0 SSO" → "Plugin Configuration".
2. Under the "Configure Service Provider" section, select your identity provider from the dropdown menu. If you don‘t see your IdP listed, choose the "Custom IDP" option.
3. Scroll down and click on "Download metadata file". This XML file contains information about your WordPress SAML configuration that you‘ll need to provide to the identity provider.
4. Take note of the "SP-EntityID / Issuer" and "ACS URL" values shown on the page. You‘ll need these when configuring the IdP.

Step 3: Configure the Identity Provider

The exact steps for configuring the IdP vary depending on the platform you‘re using. Generally, you‘ll need to:

1. Log into your identity provider‘s management console.
2. Navigate to the application or SSO settings.
3. Add a new SAML application or custom service provider.
4. Enter a name for the application (e.g., "WordPress").
5. Upload the metadata file you downloaded from WordPress, or manually enter the SP-EntityID / Issuer and ACS URL values.
6. Map user attributes (such as first name, last name, email) to the corresponding WordPress user fields.
7. Assign users or groups who should have access to the WordPress application.
8. Save your configuration and take note of the IdP-provided metadata file or XML configuration.

Step 4: Complete the WordPress SAML Configuration

1. Return to the miniOrange SAML plugin configuration page in WordPress.
2. Under the "Configure Identity Provider" section, upload the metadata file provided by your IdP or paste in the XML configuration.
3. Click "Save" to apply the settings.
4. Navigate to the "Attribute/Role Mapping" tab and review the attribute mappings. Adjust them if necessary to match your IdP‘s configuration.
5. Under "Role Mapping", specify the default WordPress role to assign to users who log in via SSO.
6. Click "Save" to store your attribute and role mapping settings.

Step 5: Add a SAML Login Link

1. In WordPress, navigate to "Appearance" → "Widgets".
2. Drag and drop the "Identity Provider Login" widget to your desired widget area (e.g., sidebar).
3. Optionally, customize the login link text and style.
4. Click "Save" to update the widget.

Your WordPress site should now be fully set up to accept SAML logins. To test it out, visit your site and click on the SAML login link you just added. You should be redirected to your identity provider to authenticate and then smoothly logged into WordPress.

Method 2: Manual SAML Configuration

For more advanced users or specific IdP integration scenarios, you may need to configure SAML manually in WordPress, without the aid of a plugin. This method requires editing WordPress files and functions, so make sure to back up your site first.

Step 1: Generate SSL Certificate and Key

SAML communication requires a secure connection over HTTPS. If your WordPress site doesn‘t already have an SSL certificate, you‘ll need to generate one. You can either:

• Purchase an SSL certificate from a trusted certificate authority (CA) and install it on your web server, or
• Use a free option like Let‘s Encrypt to generate and install an SSL certificate automatically.

Consult your web hosting provider‘s documentation for specific instructions on installing SSL.

Step 2: Configure WordPress as the Service Provider

1. Open your WordPress wp-config.php file and add the following constants to enable SAML:

define(‘SAML_ENABLED‘, true);
define(‘SAML_SP_ENTITY_ID‘, ‘urn:wordpress:mysite‘);
define(‘SAML_SP_ACS_URL‘, ‘https://mysite.com/wp-login.php?saml_sso‘);
define(‘SAML_SP_CERT_PATH‘, ‘/path/to/sp.crt‘);
define(‘SAML_SP_KEY_PATH‘, ‘/path/to/sp.key‘);

Replace mysite and mysite.com with your own site‘s details, and update the paths to your SSL certificate and key files.

2. In your WordPress theme‘s functions.php file or a custom plugin, add the following code to handle SAML authentication requests:

function saml_sso_login() {
    if (!isset($_GET[‘saml_sso‘])) {
        return;
    }

    // Process SAML request and authenticate user
    // ...

    // Log the user into WordPress
    $user = get_user_by(‘email‘, $saml_user_email);
    if ($user) {
        wp_set_current_user($user->ID);
        wp_set_auth_cookie($user->ID);
    } else {
        // Create a new WordPress user if one doesn‘t exist
        // ...
    }

    wp_redirect(home_url());
    exit;
}
add_action(‘init‘, ‘saml_sso_login‘);

This code checks for a saml_sso parameter in the URL and processes the SAML authentication request. You‘ll need to add your own logic to parse the SAML response and extract the user‘s information (e.g., email address) based on your IdP‘s configuration.

Step 3: Configure the Identity Provider

Follow the steps in Method 1, Step 3 to configure your identity provider to recognize WordPress as a service provider. Use the SAML_SP_ENTITY_ID and SAML_SP_ACS_URL values you defined in wp-config.php.

Step 4: Add a SAML Login Link

Edit your WordPress theme‘s login template or use a custom shortcode to add a SAML login link. For example:

<a href="<?php echo esc_url(add_query_arg(‘saml_sso‘, ‘‘, wp_login_url())); ?>">
    Login with SSO
</a>

This link appends the saml_sso parameter to the WordPress login URL, triggering the SAML authentication flow.

That covers the basic steps for manually implementing SAML in WordPress. Keep in mind that this method requires more technical expertise and code customization compared to using a plugin. Make sure to thoroughly test your SAML integration before deploying it on a live site.

Tips and Best Practices

Regardless of which method you use to set up SAML SSO in WordPress, here are some tips and best practices to keep in mind:

• Keep WordPress and plugins up to date: Regularly update WordPress core, themes, and plugins to ensure you have the latest security patches and features. This is especially important when dealing with user authentication.
• Enforce strong password policies: Even though users will be logging in via SSO, it‘s still a good idea to enforce strong password requirements for any local WordPress user accounts. Consider setting a minimum password length, requiring a mix of characters, and prompting users to change their passwords periodically.
• Use multi-factor authentication: For an extra layer of security, enable multi-factor authentication (MFA) for WordPress administrator accounts. This can be done through the identity provider or by using a separate WordPress MFA plugin.
• Test the SAML login flow: Before rolling out SSO to your entire user base, thoroughly test the SAML login process with a small group of users. Verify that the authentication flow works smoothly, user attributes are mapped correctly, and users are assigned the appropriate WordPress roles and permissions.
• Have a fallback login method: In case of issues with the SAML integration or identity provider, make sure users have an alternative way to log into WordPress. This could be a separate login form that authenticates against local WordPress user accounts.
• Monitor SAML logs: Keep an eye on your WordPress and IdP logs for any errors or unusual activity related to SAML authentication. Promptly investigate and address any issues that arise.
• Provide user guidance: Educate your users on how to log into WordPress using their SSO credentials. Provide clear instructions and support resources to help them get started and troubleshoot common issues.

By following these tips and best practices, you can ensure a smooth and secure SAML SSO experience for your WordPress users.

Conclusion

Implementing SAML single sign-on in WordPress offers significant benefits in terms of user experience, security, and access management. By allowing users to log in with their existing SSO credentials, you can simplify the authentication process and centrally control user access to your WordPress site.

In this guide, we covered two methods for setting up SAML in WordPress:

1. Using the miniOrange SAML Single Sign On plugin, which provides a user-friendly interface for configuring SAML settings and integrating with various identity providers.
2. Manually configuring SAML by editing WordPress files and functions, which requires more technical expertise but allows for greater customization.

We also shared tips and best practices for ensuring a secure and smooth SSO experience, such as keeping WordPress updated, enforcing strong password policies, testing the SAML login flow, and monitoring logs.

Whether you choose the plugin route or the manual method, properly implementing SAML SSO can help streamline access to your WordPress site and enhance overall security. By following the steps outlined in this guide, you‘ll be well on your way to giving your users a seamless login experience through SAML single sign-on.