WordPress SAML

0 27 May 2024

This comprehensive guide is designed to assist you in integrating ALMEFY as your Identity Provider (IdP) on WordPress, utilising SAML 2.0, enabling Single Sign-On (SSO). We'll walk you through the necessary steps to ensure a seamless and secure setup. Please also refer to the Plugin documentation for further details.

Prerequisites

  • Admin access to your ALMEFY Hub at <subdomain>.hub.almefy.com
  • A WordPress server
  • WP SAML Auth Plugin plugin to enable SAML support for WordPress
  • WP Add MIME Types plugin to allow uploading a .crt file to WordPress

These are 3rd party plugins which we have confirmed to work well. You may choose any other SAML 2.0 compatible auth plugin.

Setup Overview

We try our best to keep these guides updated but can not anticipate when platforms might update interfaces, or change available options for configuring SSO.

Though setting up ALMEFY as your IdP generally follows the same steps for all platforms.

  1. Configure Endpoint – Set up the specific details of your endpoint in the ALMEFY Hub.
  2. Configure Platform – Adjust your platform’s settings for compatibility with the ALMEFY endpoint.
  3. Copy Metadata – Transfer the necessary metadata from your platform to the ALMEFY Hub for secure integration.

Each step corresponds to the options in the left column of the ALMEFY Hub interface.
If you find any inconsistencies in this guide, please let us know via our contact form.

Setup

Please note: the steps in the left column of the Endpoint Creation screen in the ALMEFY Hub correspond to the same as in this guide.

Step 1. ALMEFY SSO Endpoint Configuration

  1. Create a new Endpoint in the ALMEFY Hub by clicking the Add Endpoint button in the top right of the Endpoints page.
  2. Select the WordPress SAML Preset
  3. (Optional) Rename the endpoint and the endpoint id if you do not want to use the default.
  4. Press the Generate Certificate & Private Key button or paste your own into the text boxes. We will need those later again.
  5. Go to Step 2. in the left column of the Endpoint creation configuration and click Download X.509 Certificate. We will use it later.
  6. Keep the endpoint configuration options open and continue with Step 2.

Note that we offer both a WordPress SAML and a WordPress OIDC preset, so make sure to choose the correct one.

Step 2. WordPress Configuration

More details can be found in the Plugin documentation.

  1. Log into WordPress with an admin account and navigate to https://<website>.com/wp-admin.
  2. Go to Plugins > Add New Plugin
  3. Search for WP Add MIME Types, install and activate.
  4. Search for WP SAML Auth Plugin, install and activate.
  5. Before we can configure the SAML settings, we must tell WordPress to accept .crt files. Go to Settings > Mime Type Settings and at the bottom add crt = application/x-x509-ca-cert to Add Values and save.
  6. In Media > Add New Media File upload your wordpress_saml_certificate.crt file we downloaded earlier and hit Copy URL to clipboard. We will need it later.
  7. Navigate to Settings > WP SAML Auth.
  8. Auto Provision: Set this to true, if you want users created in the ALMEFY Hub to be automatically created in WordPress as well. (Recommended)
  9. Permit WordPress login: Set this to true for testing. It allows you to login with your password until you verified SAML authentication works properly.
  10. Get User By: email
  11. Base URL: Set to https://<yourdomain>.com

Do not add trailing slashes to any of the URLs!

Service Provider Settings

  1. Entity Id: Set to urn:https://<yourdomain>.com
  2. Assertion Consumer Service URL: Do not change this. We will use it later. Should point to your WordPress login page like https://<yourdomain>.com/wp-login.php

Identity Provider Settings

  1. Entity Id: Copy the Issuer from Step 2. section of the Endpoint settings and paste it here.

  2. Single SignOn Service URL: Copy the SSO URL from Step 2. section of the Endpoint settings and paste it here.

  3. x509 Certificate Path: Paste the URL we copied earlier. The URL will look something like https://<yourdomain>.com/wp-content/uploads/<month>/<year>/wordpress_saml_certificate.crt.

  4. Change the the certificate path to this format: ABSPATH/wp-content/uploads/<year>/<month>/wordpress_saml_certificate.crt

  5. Leave all other settings as they are.

  6. Click the Save changes button.

    Step 3. Configure WordPress Metadata in ALMEFY

  7. Copy the Assertion Consumer Service URL we skipped earlier.

  8. Navigate back to the ALMEFY Hub Endpoint creation page.

  9. In the Step 3. section, paste the copied URL as ACS URL.

  10. Click "Add Endpoint".

  11. You are done!

Test & Troubleshoot

To ensure that ALMEFY has been correctly set up as your Identity Provider (IdP), you can test the login in two ways:

  1. Platform Login Page: Visit the WordPress login page and check if the ALMEFY Login option is visible and functional by clicking on it and scanning the ALMEFY QR Code with the ALMEFY App.
  2. ALMEFY SSO Page: Go to <subdomain>.sso.almefy.com, sign in with the ALMEFY App, and choose your newly enabled endpoint to test the authentication process.

If you encounter any issues:

  • Review this guide to make sure all steps were followed correctly.
  • Consult the Plugin documentation for specific setup and troubleshooting instructions.
  • Try to the contact Plugin developers support and see if your issue can be resolved.
  • Try another WordPress SAML Plugin.
  • If you still need help, please fill out our contact form for support.

    Conclusion

Congratulations on successfully setting up SAML 2.0 authentication with ALMEFY as your Identity Provider! You are now equipped to offer users a secure and convenient single sign-on experience.