| Next revision | Previous revision |
| en:2.0:single_sign_on:oidc_wordpress [2025/05/07 17:09] – created kainhofer | en:2.0:single_sign_on:oidc_wordpress [2025/05/13 19:26] (current) – [Caveats and Things to Consider] kainhofer |
|---|
| ====== Single-Sign-On into WordPress using Admidio as an OpenID Provider ====== | ====== Single-Sign-On into WordPress using Admidio as an OpenID Provider ====== |
| <WRAP center round todo 60%> | |
| todo box | |
| </WRAP> | |
| |
| 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]]. | 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]]. |
| The page https://admidio.local/adm_program/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. | The page https://admidio.local/adm_program/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 ===== | ===== Quick Overview ===== |
| |
| Setting up a client (OpenID "Relying Party" - short RP) to use Admidio's user accounts for logging in consists of two steps: (1) The client (RP, WordPress in our case) needs to be set up with the data about the OpenID Provider (OP). Typically this is done via the metadata provided in the discovery URL of the provider. Otherwise one has to manually paste the endpoint URLs of the OpenID provider. Since Admidio provides those URLs with copy buttons in the preferences screen, even the manual configuration is rather straigtforward. (2) Admidio needs to be told about the client. In particular, the entity ID and the redirect URL must be given, and a custom-generated (random) secret must be copied to the client configuration. | Setting up a client (OpenID "Relying Party" - short RP) to use Admidio's user accounts for logging in consists of two steps: (1) The client (RP, WordPress in our case) needs to be set up with the data about the OpenID Provider (OP). As WordPress does not support auto-configuration useing the OpenID discovery endpoint, one has to manually paste the endpoint URLs of the OpenID provider. Admidio provides copy buttons in the preferences screen, so this is rather straightforward. (2) Admidio needs to be told about the client. In particular, the entity ID and the redirect URL must be given, and a custom-generated (random) secret must be copied to the client configuration. |
| |
| The concrete steps are: | The concrete steps are: |
| * At the **Relying Party (RP)** - WordPress in our case - **install the extension** to support OpenID login. | * At the **Relying Party (RP)** - WordPress in our case - **install the extension** to support OpenID login. |
| * Configure it either with Admidio's **discovery URL** (if supported), or enter the EntityID and the URL endpoints for authentication, token and userinfo. | * Configure it either with Admidio's **endpoint URLs** for authentication, token and userinfo, and enter the EntityID. |
| * Also, choose which scopes (groups of profile fields) should be requested from Admidio ("openid" is required; If Admidio's groups/roles should be mapped to the client's groups, the "groups" scope is also required). | * Also, choose which scopes (groups of profile fields) should be requested from Admidio ("openid" is required; Since the OpenID Wordpress plugin does not support groups mapping, the "groups" scope is not relevant and has no use. |
| * In **Admidio**, **create a new OpenID client**. | * In **Admidio**, **create a new OpenID client**. |
| * Choose an easily understood **label for the client** (only used in Admidio's list of clients, but has no technical use) | * 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 RP**, Copy the created Client Secret (you will later need to paste it into the WordPress configuration), and enter the **Redirect URI** for the RP. Typically the latter can be found either on the RP's configuration page or in the documentation. | * Enter the **ClientID from the RP**, Copy the created Client Secret (you will later need to paste it into the WordPress configuration), and enter the **Redirect URI** for the RP. The latter can be found on the RP's configuration page. |
| * Optionally select (both in Admidio and the RP) which **profile fields should be mapped** to OpenID claims (attributes) and sent to the client, and configure which **group memberships** should be transmitted. | * In Admidio, map the user ID, username, email and fullname to fields that are included in the OpenID login response (so-called "claims") and enter the corresponding claim names in Wordpress. If the field names are not alligned, login will not be possible, but the error message will be quite generic without helpful hints. |
| |
| |
| ===== DokuWiki-specific instructions ===== | ===== WordPress-specific instructions ===== |
| |
| ==== Configuring the Service Provider (DokuWiki) ==== | ==== Configuring the Service Provider (WordPress) ==== |
| |
| OpenID Connect login in WordPress is provided by the [[https://www.wordpress.org/plugin:oauth|"oauth plugin"]] and the connected [[https://www.wordpress.org/plugin:oauthgeneric|"oauth generic Service"]] extension. | There are several OpenID plugins for WordPress, but none of the free versions supports permission mapping based on groups. The best free plugin we found is the [[https://github.com/forumone/openid-connect-wp-dist|OpenID Connect for WP]] plugin, which is a hard fork of Jonathan Daggerhart's OpenID Connect Generic plugin (which he is no longer able to maintain due to WordPress's stance on WP Engine and the fallout of the actions of Matt Mullenweg). The "OpenID Connect for WP" plugin is not available in the Wordpress plugin directory, only the previous "OpenID Connect Generic" by Daggerhart. We still recommend to use the newer "OpenID Connect for WP" and install it manually (either using git or by downloading the plugin code to the WP installation). See the plugin's source code repository on GitHub: https://github.com/forumone/openid-connect-wp-dist |
| {{ :en:2.0:sso:sso_oidc_04-01_dw_plugin_install.png?direct&600 |}} | |
| |
| After installation it can be configured in the WordPress Configuration Settings, near the bottom in the "Oauth" and "Oauthgeneric" sections. | If you have shell access to the WP installation, the easiest way is to use the git shell command: |
| | |
| | <code bash> |
| | # Switch to the base directory of your WordPress installation. Then: |
| | cd wp-content/plugins/ |
| | git clone https://github.com/forumone/openid-connect-wp-dist.git |
| | </code> |
| | |
| | After installation it can be configured in the menu item "Settings" -> "OpenID Connect Client". |
| | {{ :en:2.0:sso:sso_oidc_wp_02_plugin_configuration.png?direct&200 |}} |
| |
| First, one has to copy over the OpenID endpoint URLs from Admidio's OpenID preferences (each URL has a copy button). You can find them here: | First, one has to copy over the OpenID endpoint URLs from Admidio's OpenID preferences (each URL has a copy button). You can find them here: |
| {{ :en:2.0:sso:sso_oidc_01-01_setup_admidio_endpoints.png?direct&600 |}} | {{ :en:2.0:sso:sso_oidc_wp_06_oidc_setupendpoints.png?direct&800 |}} |
| | |
| | The remaining settings in Wordpress are client-specific, so one first needs to setup the OpenID client in Admidio and configure WordPress and Admidio in parallel. |
| |
| ==== Setting up the Client (SP) in Admidio ==== | ==== Setting up the Client (SP) in Admidio ==== |
| It is now 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 the WordPress configuration. | It is now 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 the WordPress configuration. |
| |
| Now, return to Admidio's SSO preferences page, go to the "Single-Sign-On Client Administration" (the button right below the endpoint URLs and above the "Save" button), and create a new client. | Return to Admidio's SSO preferences page, go to the "Single-Sign-On Client Administration" (the button right below the endpoint URLs and above the "Save" button), and create a new client. |
| {{ :en:2.0:sso:sso_oidc_01-07_clientadmin.png?direct&400 |}} | {{ :en:2.0:sso:sso_oidc_wp_07_oidc_setupclient.png?direct&800 |}} |
| |
| - The **Client Name** is the label of the client in Admidio's client list, it can be anything you like. | - The **Client Name** is the label of the client in Admidio's client list, it can be anything you like. |
| - The **"Client ID"** and **"Client Secret"** in Admidio have to match exactly the **"Application UID"** and **"Application Secret"** in the WordPress configuration. The ID is typically the client's URL, although some clients allow any unique identifier, while others (most notably MediaWiki) require it to be the base of the OpenID endpoint (up until the 'index.php/oidc/'). The Client Secret should a random string and will serve like a password. Admidio will create one and allow it to be copied to the client. Afterwards it is only stored as a hash in the database and not be recovered any more. However, one can create a new Client Secret in Admidio and copy that to the client's configuration. | - The **"Client ID"** and **"Client Secret"** in Admidio and WordPress have to match exactly. The ID is typically the client's URL, although some clients allow any unique identifier. The Client Secret should a random string and will serve like a password. Admidio will create one and allow it to be copied to the client. Afterwards it is only stored as a hash in the database and not be recovered any more. However, one can create a new Client Secret in Admidio and copy that to the client's configuration. |
| - WordPress will display its **Redirect URL**, which needs to be copied to Admidio. | - Enter the **scopes** you desire in the WordPress config and make sure that Admidio's config matches it. At least **openid must be included** (Admidio will implicitly add it). Sonce the WordPress plugin does not support OpenID groups, the presence of the "groups" scope has no effect. |
| - Enter the **scopes** you desire in the WordPress config and make sure that Admidio's config matches it. At least **openid must be included** (Admidio will implicitly add it). If groups/roles are supposed to be used for access permissions, the **"groups" scope** also must be included in both the WordPress and Admidio's scope setting and the roles included as an OpenID claim. (The groups mapping that Admidio offers is optional, one can also send all groups verbatim without mapping. This can be achieved by checking the checkbox below the mapping table in Admidio). | - In Admidio, choose which field should be sent to and used by the Wordpress Plugin to uniquely identify users. This would typically be the login name, although the user ID or UUID area also possible. |
| |
| This is a typical configuration of the WordPress Oauth extensions for Admidio as an OpenID provider: | In addition, WordPress also provides settings to map OpenID claims (defined profile fields with a fixed name, defined in the OpenID standard) to the WordPress user's ID, nickname, email and fullname, as well as flags to enable automatic user creation when a new user logs in to WordPress. |
| {{ :en:2.0:sso:sso_oidc_04-04_dw_settings.png?direct&800 |}} | {{ :en:2.0:sso:sso_oidc_wp_08_oidc_wpsettings.png?direct&800 |}} |
| | {{ :en:2.0:sso:sso_oidc_wp_09_oidc_wpsettings.png?direct&300 |}} |
| |
| | - WordPress will display its **Redirect URL** at the very bottom of the form, which needs to be copied to Admidio's OpenID client configuration. |
| | {{ :en:2.0:sso:sso_oidc_wp_10_redirecturl.png?direct&800 |}} |
| |
| To use Admidio's group memberships as WordPress groups, make sure to include the "Roles" field and provide the correct field name in WordPress. WordPress even provides a setting to overwrite all groups with the groups received from Admidio. | |
| |
| Make sure to use the same OpenID claim names as the ones mapped in the WordPress OpenID configuration (circled red in the configuration screenshot above). | After saving the changes (both in WordPress and Admidio), the apps should should now be set up for single-sign-on in WordPress. |
| |
| Once all settings are done, it is time to enable the saml plugin for login to WordPress in the "Configuration Settings": | |
| {{ :en:2.0:sso:sso_oidc_04-07_dw_enable.png?direct&400 |}} | |
| |
| ==== WordPress configuration as text ==== | |
| |
| The settings done above in the graphical interface could also be done in the ''conf/local.php'' config file of WordPress. The corresponding settings would look like this: | |
| |
| <code php> | |
| $conf['authtype'] = 'oauth'; | |
| $conf['superuser'] = '@admin'; | |
| $conf['plugin']['oauth']['register-on-auth'] = 1; | |
| $conf['plugin']['oauth']['overwrite-groups'] = 1; | |
| $conf['plugin']['oauthgeneric']['key'] = 'https://wordpress.local/'; | |
| $conf['plugin']['oauthgeneric']['secret'] = 'lWDQ......gU'; | |
| $conf['plugin']['oauthgeneric']['authurl'] = 'https://admidio.local/modules/sso/index.php/oidc/authorize'; | |
| $conf['plugin']['oauthgeneric']['tokenurl'] = 'https://admidio.local/modules/sso/index.php/oidc/token'; | |
| $conf['plugin']['oauthgeneric']['userurl'] = 'https://admidio.local/modules/sso/index.php/oidc/userinfo'; | |
| $conf['plugin']['oauthgeneric']['scopes'] = array('openid', 'profile', 'address', 'phone', 'email', 'custom', 'groups', 'roles'); | |
| $conf['plugin']['oauthgeneric']['json-user'] = 'username'; | |
| $conf['plugin']['oauthgeneric']['json-name'] = 'fullname'; | |
| $conf['plugin']['oauthgeneric']['json-mail'] = 'email'; | |
| $conf['plugin']['oauthgeneric']['json-grps'] = 'roles'; | |
| $conf['plugin']['oauthgeneric']['label'] = 'OIDC Login with Admidio'; | |
| </code> | |
| |
| ==== Setup completed, test Single-Sign-On ==== | ==== 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 and try to log in again, you will be shown the Admidio login screen and then redirected back to WordPress. | Admidio and WordPress should now be set up to use Admidio for logging in to WordPress. If you log out of WordPress and try to log in again, you will be shown the Admidio login screen and then redirected back to WordPress. |
| |
| {{ :en:2.0:sso:sso_oidc_04-08_dw_login.png?direct&400 |}} | {{:en:2.0:sso:sso_oidc_wp_11_wordpress_login.png?direct&250|}} |
| {{ :en:2.0:sso:sso_oidc_04-09_dw_admidio_login.png?direct&400 |}} | {{:en:2.0:sso:sso_oidc_wp_12_admidio_login.png?direct&400}} |
| {{ :en:2.0:sso:sso_oidc_04-10_dw_login_success.png?direct&400 |}} | {{:en:2.0:sso:sso_oidc_wp_13_login_success.png?direct&250|}} |
| | {{ :en:2.0:sso:sso_oidc_wp_14_login_success_profile.png?direct&600 |}} |
| |
| |
| ==== Caveats and Things to Consider ==== | ==== Caveats and Things to Consider ==== |
| |
| * WordPress allows **admin login** through OpenID by assigning the **group 'admin'** in the group mapping. | * The [[https://github.com/forumone/openid-connect-wp-dist|OpenID Connect for WP]] plugin does not support groups and assigning WordPress permissions based on OpenID claims. If this is required, consider Single-Sign-On via the SAML protocol. WordPress has a SAML plugin that supports permission mapping and works with Admidio. |
| * WordPress will convert all group names to lowercase. This is a general restriction in WordPress and not specific to OpenID. | * The claim names for the user ID, nickname, email and full name must be entered **exactly** as given in Admidio, otherwise login will fail with some cryptic error messages. |
| * WordPress will match its accounts using the email provided in the OpenID token, even when a different user id field is selected. E.g. if a local user 'dale' with email 'dale@example.com' already exists, and a new OpenID login from user 'dale' with email 'dale.baade@example.com' occurs, WordPress will treat these as two separate users (and modify the username of the newly created user to 'dale1')! | |
| * WordPress controls **login permissions for OpenID** with a **group 'generic' assigned to a user**. If local accounts already exist, one needs to add them to the 'generic' group, otherwise login with OpenID is not possible and the following error message will be shown:{{ :en:2.0:sso:sso_oidc_04-10_dw_error_group.png?direct |}} To fix this, add the user to the 'generic' group: {{ :en:2.0:sso:sso_oidc_04-11_dw_generic_group.png?direct&600 |}} | ^ Error Message ^ Reason and solution ^ |
| | | {{:en:2.0:sso:sso_oidc_wp_15a_login_troubleshooting_username.png?333 |}} ERROR (incomplete-user-claim): User claim incomplete. | The **user ID** is misspellt or wrong (or not included in the OpenID response). Try to **use "sub"** as the user ID in WordPress, and make sure that the **openid scope is included**. | |
| | | {{:en:2.0:sso:sso_oidc_wp_15b_login_troubleshooting_nickname.png?372 |}} ERROR (no-nickname): No nickname found in user claim using key: //claimname// | The **claim used for the nickname** is wrong or missing. Check whether the given **claim name matches** exactly an OpenID claim name configured in Admidio and whether the **"profile" scope is included** (both in WordPress and Admidio). | |
| | | {{:en:2.0:sso:sso_oidc_wp_15c_login_troubleshooting_missing_email_fullname.png?380 |}} ERROR(incomplete-user-claim): User claim incomplete. | The **claim names given for email and fullname** in Wordpress are either wrong or missing from the OpenID response. Check whether the given claim names given for the email and fullname match exactly an OpenID claim names configured in Admidio and whether the **"profile" and "email" scopes are included** (both in WordPress and Admidio). | |
| | |
