| Both sides previous revision Previous revision Next revision | Previous revision |
| en:2.0:single_sign_on:oidc_wordpress [2025/05/13 19:16] – kainhofer | en:2.0:single_sign_on:oidc_wordpress [2026/09/06 18:51] (current) – [Setting up the Client (SP) in Admidio] kainhofer |
|---|
| |
| 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. | 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 OpenID Provider** (OP). This has to be done once and is not specific to WordPress. Please follow this guide: [[en:2.0:single_sign_on|#a_basic_setup_for_admidio_as_an_oidc_id_provider]] | As a first step, one needs to **configure Admidio to act as an OpenID Provider** (OP). This has to be done once and is not specific to any particular client. Please [[en:2.0:single_sign_on#a_basic_setup_for_admidio_as_an_oidc_id_provider|folow this guide]]: |
| {{ :en:2.0:sso:sso_oidc_01-05_setup_admidio_preferences.png?direct&600 |}} | {{ :en:2.0:sso:sso_oidc_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 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. | Basically, one needs to enable OpenID Connect (OIDC). The Issuer URL should in most cases be left blank, which means Admidio's public URL will be used as issuer URL. |
| | |
| | The page https://admidio.local/adm_program/modules/preferences.php?panel=sso also provides the link to the automatic discovery URL, and the individual settings in case a client does not support auto-configuration via metadata. |
| |
| ===== 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). 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. | Setting up a client (OpenID "Relying Party" = "RP") to use Admidio's user accounts for log-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. 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. |
| |
| 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 **endpoint URLs** for authentication, token and userinfo, and enter the EntityID. | * Configure it 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; Since the OpenID Wordpress plugin does not support groups mapping, the "groups" scope is not relevant and has no use. | * Also, choose which scopes (groups of profile fields) should be requested from Admidio ("openid" is required); Although the OpenID Wordpress plugin at first glance does not seem to support groups mapping, this can be achieved with a small self-written plugin, so in this case the "groups" scope should also be included. |
| * 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 and displayed to the user on the login screen, 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. The latter can be found on the RP's configuration page. | * 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. |
| * 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. | * 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. |
| |
| ==== Configuring the Service Provider (WordPress) ==== | ==== Configuring the Service Provider (WordPress) ==== |
| |
| 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 | There are several OpenID plugins for WordPress, but none of the free versions supports permission mapping based on groups easily. 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 |
| | That plugin also allows mapping Admidio's groups to WordPress roles, but that involves writing a tiny Wordpress plugin for the mapping. See below for the instructions. |
| |
| If you have shell access to the WP installation, the easiest way is to use the git shell command: | If you have shell access to the WP installation, the easiest way is to use the git shell command: |
| - 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). Sonce the WordPress plugin does not support OpenID groups, the presence of the "groups" scope has no effect. |
| - 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. | - 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. |
| | - 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_wp_08_oidc_wpsettings.png?direct&800 |}} |
| | - 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 |}} |
| | - WordPress's OIDC implementation does not support PKCE for increased security, which is enabled by Admidio by default. For this reason, make sure to disable the PKCE requirement in the OIDC client's advanced settings: {{ :en:2.0:sso:sso_oidc_04-04a_dw_settings_pkce.png?400 |}} |
| |
| 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_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 |}} | |
| |
| |
| * 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. | * 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. |
| |
| ^ Error Message ^ Error Message ^ Reason and solution ^ | ^ Error Message ^ Reason and solution ^ |
| | {{:en:2.0:sso:sso_oidc_wp_15a_login_troubleshooting_username.png?nolink|}} | 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_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?nolink|}} | 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_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?nolink|}} | 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). | | | {{: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). | |
| |
| |
