Single-Sign-On into Wordpress using Admidio as a SAML 2.0 Identity Provider [Admidio-Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Single-Sign-On into Wordpress using Admidio as a SAML 2.0 Identity Provider ======

Starting with version 5.0, Admidio can be used by other applications to authenticate users against Admidios user base. These instructions will guide you through the process of connecting Wordpress to Admidio to use Admidio's login. For general instructions, and other apps, please visit the [[en:2.0:single_sign_on|general Single-Sign-On overview page]].

While the Wordpress plugin directory lists several choices for SAML login, only the [[https://wordpress.org/plugins/onelogin-saml-sso/|OneLogin SAML SOO]] plugin is free and supports permissions depending on the Admidio groups/roles.

===== Prerequisites =====

Throughout the document we will assume you have both Admidio and Wordpress already set up properly at https://admidio.local/ and https://wordpress.local/. Please modify these URLs to your actual installation.
 
As a first step, one needs to **configure Admidio to act as an SAML 2.0 Identity Provider** (IdP). This has to be done once and is not specific to any client. Please follow this guide: [[en:2.0:single_sign_on|#a_basic_setup_for_admidio_as_a_saml_id_provider]]
{{ :en:2.0:sso:sso_saml_01-05_setup_admidio_preferences.png?direct&600 |}}

Basically, one (1) needs to **create a cryptographic key** to sign message and **choose a unique EntityID**.
The page preferences https://admidio.local/modules/preferences.php?panel=sso also provides the link to the metadata xml, and the individual settings in case a client does not support auto-configuration via metadata.

===== TL;DR; - Quick Overview =====

Setting up a client (SAML "Service Provider" - short SP) to use Admidio's user accounts for logging in consists of two steps. If both the IdP (Admidio in our case) and the SP (Wordpress in this document) support metadata loading, the setup is very straightforward and easy. Otherwise, one has to copy URLs manually to the client, but Admidio already provides these in a single place, so this situation is not as bad, either.

  * At the **Service Provider (SP)** - Wordpress in our case - **install the extension** to support SAML login.
  * Configure it either with Admidio's link to the **metadata file**, or enter the EntityID, the Single-Sign-On Endpoint, the SLO Endpoint and the public certificate manually (Admidio provides a simple table to copy these values from).
  * Choose whether sent messages **should be signed and/or encrypted** (these features require an additional private key and certificate for the SP!), and whether received messages are checked for signatures or encryption is expected. 
  * In **Admidio**, **create a new SAML client**. If the SP provides a **metadata URL**, paste it and let Admidio automatically load the configuration from the SP. One can also manually paste these settings.
    * Choose an easily understood **label for the client** (only used in Admidio's list of clients, but has no technical use)
    * Enter the **ClientID from the SP**, as well as the ACS URL and the SLO response URL. These values must be provided by the client.
  * In Admidio, also choose whether sent messages should be **signed or encrypted**. The crypto key generated in the general SAML setup will be used.
  * Optionally select which **profile fields should be mapped** to SAML attributes and sent to the client, and configure which **group memberships** should be transmitted.

===== Wordpress-specific instructions =====

==== Configuring the Service Provider (Wordpress) ====

There are several SAML plugins for Wordpress, mostly non-free and quite expensive. A free SAML plugin that provides login, but also profile field and group sync is the plugin "OneLogin SAML SSO", which can be installed directly in the plugin manager.

<div style="text-align: center;">
{{:en:2.0:sso:sso_saml_wp_01_install_saml_plugin.png?direct&450|}}  {{:en:2.0:sso:sso_saml_wp_01b_install_saml_plugin.png?direct&800|}} </div>


After installation it can be configured in WordPress in the menu "Settings" -> "SSO/SAML Settings". The plugin does not allow auto-configuration from Admidio's metadata file, so one needs to manually enter all IdP information from Admidio's preferences section. It is a good idea to keep two browser windows open so one can easily select and copy the settings. Admidio even provides little "copy" buttons/icons to copy the various settings to the clipboard for easy pasting into Wordpress' configuration.
{{:en:2.0:sso:sso_saml_wp_02_plugin_config.png?direct&900|}}

One central setting is the SAML Client EntityID, which uniquely identifies the Wordpress client to Admidio. You need to scroll down to the  "Advanced Settings" Section and enter the EntityId of your Wordpress SAML client. It is usually recommended to use the URL of the installation, but any unique string is fine. That EntityID will be copied over to the Admidio configuration. If the SP EntityID entered in Wordpress and in Admidio does not match, login via SAML will NOT be posible!
{{ :en:2.0:sso:sso_saml_wp_03b_cliententityid.png?direct&600 |}}

Once these basic SAML settings are done, I would recommend to set up the SP in Admidio, and do the remaining settings (transmitted fields and roles, as well as signing/encryption requirements) in parallel in Wordpress and Admidio. 


If the basic settings are valid, the Wordpress plugin provides a link at the top of the page to check the validity of the configuration. At the very top of the config page is also the link to the client (SP) metadata XML file, which can be pasted into Admidio for auto-configuration  of the SAML access (right-click on the link and copy the link location to the clipboard).

{{ :en:2.0:sso:sso_saml_wp_06_spmetadata_link.png?direct |}}


=== Setting up encryption ===

If encryption is desired for all SAML messages sent by Admidio to Wordpress, or if Wordpress should sign all its SAML requests, then Wordpress needs a private/public key pair to decrypt or sign messages. These need to be entered into the Wordpress SAML config in PEM format and can be generated by openssl's command line tools, by sites like https://www.samltool.com/self_signed_certs.php or in Admidio's key administration. Simply create a new Key for Wordpress (RSA 2048 bits). The certificate can be copied directly from the key's edit page, but the private key is not available in Admidio's GUI for security reason. Instead, it can be downloaded (secured with a password!) from the list of keys in Admidio:

{{ :en:2.0:sso:sso_saml_02-03a_nc_saml_keysetup1.png?direct&400 |}}

After downloading the .p12 file, Applications like [[https://keystore-explorer.org/|KeyStore Explorer]] can be used to read the private key and copy the private key and the certificate in PEM format to the clipboard and paste it into Nextcloud's SAML configuration.

{{:en:2.0:sso:sso_saml_02-03b_nc_saml_keystoreexplorer1.png?direct&400|}}{{:en:2.0:sso:sso_saml_02-03c_nc_saml_keystoreexplorer2.png?direct&400|}}

{{ :en:2.0:sso:sso_saml_wp_03c_cryptokey_wordpress.png?direct |}}



==== Setting up the Client (SP) in Admidio ====


Now, return to Admidio's SSO preferences page, go to the "Single-Sign-On Client Administration" (the button right above the "Save" button), and create a new client.
{{ :en:2.0:sso:sso_saml_03-00_admidio_saml_preferences.png?direct&400 |}}


Paste the metadata URL copied from Wordpress into the corresponding input field at the top and click "Load Client Metadata". This should load all settings from Nextcloud and pre-fill the following fields correctly. Only the Client Name needs to be entered. Choose any name to clearly identify the client in the list of SAML clients. There is no functionality depending on the name.
{{ :en:2.0:sso:sso_saml_wp_07_saml_client.png?direct&600 |}}


==== Further configuration in Wordpress: Groups and Permissions, Fields, Security / Signing ====

The plugin's configuration page provides a long **section of options**, which can be used to fine-tune the SAML functionality. E.g. one can have new users automatically created when a user logs in the first time via SAML. 


The Wordpress SAML configuration also provides **attribute and role mapping** sections. The attribute mapping defines how Admidio's user profile fields are translated to Wordpress profile fields (currently only first and last name and the login name). If you also want to use Admidio's group memberships / roles to determine access permissions in Wordpress, make sure sure include the roles in the mapping!
{{ :en:2.0:sso:sso_saml_wp_03_plugin_fieldmapping.png?direct |}}


=== Role mapping between Admidio and Wordpress, Security Settings ===

To use Admidio's group memberships or roles to define **access permissions to Wordpress**, make sure to include the roles / groups profile field in the field mapping as described in the previous paragraph. In Admidio, you can select which groups should be communicated to Wordpress, and even map them to other names. In the Wordpress SAML configuration, you can choose which group defines rights for Wordpress permissions (Administrator/Editor/Author/Contributor/Subscriber).
{{ :en:2.0:sso:sso_saml_wp_04_plugin_rolemapping.png?direct |}}

If your users have multiple roles, which are mapped to different permissions, one can even choose which permission level should take precendence, but in most cases this is not needed.

The final section with advanced settings in Wordpress contains settings to fine-tune also cryptographic capabilities. It is important that the settings in Wordpress and Admidio are consistent and do not collide (e.g. if Wordpress is configured not to sign requests, while Admidio is configure to require signatures). The choices shown in the following Screenshot can be changed, but they need to be consistent in Wordpress and Admidio.
{{ :en:2.0:sso:sso_saml_wp_05_plugin_cryptosettings.png?direct |}}


==== Setup completed, test Single-Sign-On ====
Admidio and Wordpress should now be set up to use Admidio for logging in to Wordpress. If you log out of Wordpress (or open Wordpress in an incognito browser window) and go to the wordpress admin location, you should see the login screen with the choice of logging in with password or via SAML.
{{ :en:2.0:sso:sso_saml_wp_08_saml_wordpress_login.png?direct&400 |}}


After choosing SAML login and loggin in with a user from Admidio, you should be logged in to Nextcloud.
{{ :en:2.0:sso:sso_saml_wp_08b_saml_admidio_login.png?direct&400 |}}{{ :en:2.0:sso:sso_saml_wp_09_loggedin.png?direct |}}



==== Caveats and Things to Consider ====

  * The permission levels of Wordpress are very limited, so figuring out the proper mapping of groups to permissions is important to prevent accidental admin permissions to users.
  * Even though Wordpress has fields for Website, Bio and Profile Picture, the SAML plugin does not provide a way to populate them from Admidio.