Differences

This shows you the differences between two versions of the page.

--- en:2.0:single_sign_on:oidc_nextcloud [2025/05/14 22:25] – created kainhofer
+++ en:2.0:single_sign_on:oidc_nextcloud [2026/09/10 18:30] (current) – [Setting up the Client (SP) in Admidio] kainhofer
@@ Line 14: / Line 14: @@
 Throughout the document we will assume you have both Admidio and Nextcloud already set up properly at https://admidio.local/ and https://nextcloud.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 Nextcloud. 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 |}}
-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 for clients that do not support auto-configuration via metadata.
 ===== 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, Nextcloud in our case) needs to be set up with the data about the OpenID Provider (OP). IF the plugin supports auto-discovery, paste the .well-known/openid-configuration URL from Admidio into the plugin config. Otherweise, 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:
+  - The client (RP, Nextcloud in our case) needs to be set up with the data about the OpenID Provider (OP). If the plugin supports auto-discovery, paste the .well-known/openid-configuration URL from Admidio into the plugin config. 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 straightforward.
+  - 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:
   * At the **Relying Party (RP)** - Nextcloud in our case - **install the extension** to support OpenID login.
-    * Configure it either using OpenID auto-discovery, or manually with Admidio's **endpoint URLs** for authentication, token and userinfo, and enter the EntityID.
+    * Configure it either with Admidio's **discovery URL** (if supported), or enter the EntityID and the URL endpoints for authentication, token and userinfo.
-    * Also, choose which scopes (groups of profile fields) should be requested from Admidio ("openid" is required; Since the OpenID Nextcloud 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; If Admidio's groups/roles should be mapped to the client's groups, the "groups" scope is also required).
   * 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)
-    * Enter the **ClientID from the RP**, Copy the created Client Secret (you will later need to paste it into the Nextcloud configuration), and enter the **Redirect URI** for the RP. The latter can be found on the plugin's configuration page in Nextcloud.
+    * Enter the **ClientID from the RP**, copy the created Client Secret (you will later need to paste it into the Nextcloud configuration), and enter the **Redirect URI** for the RP. The latter can be found on the plugin's configuration page in Nextcloud.
+    * Many open source OIDC clients do not support encryption (PKCE, which is a security mechanism that prevents attackers from obtaining access unless their application started the initial login). By default, PKCE is required by Admidio, so in this case make sure that the requirement checkbox is turned off. Otherwise you will get an error.
     * 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 Nextcloud.
 ===== Nextcloud Login via OpenID using the OpenID Connect user backend (user_oidc) =====
-The most convenient OpenID Connect support for Nextcloud is provided by the "[[https://apps.nextcloud.com/apps/user_oidc|**OpenID Connect user backend** (user_oidc)]]" plugin. It supports multiple OpenID Providers, support for groups, fields mapping, automatic user-creation on login and auto-discovery of settings. Its configuration is done in Nextcloud's preferencess UI.
+The most convenient OpenID Connect support for Nextcloud is provided by the "**[[https://apps.nextcloud.com/apps/user_oidc|OpenID Connect user backend (user_oidc)]]**" plugin. It supports multiple OpenID Providers, support for groups, fields mapping, automatic user-creation on login and auto-discovery of settings. Its configuration is done in Nextcloud's preferences UI.
+For convenient mapping of OIDC claims to Nextcloud profile fields, use the **[[https://apps.nextcloud.com/apps/oidc_claim_mapping|OIDC Claim Mapping]]** plugin. To map admidio groups to Nextcloud groups in a visual style, use the **[[https://apps.nextcloud.com/apps/oidc_groups_mapping|OIDC Groups Mapping]]** plugin.
@@ Line 51: / Line 57: @@
   * Create a new Provider by clicking on the "+".
-  * Go to Admidio's Single-Sign-On Preferences and copy the Discovery URL for OpenID Connect (of the form ''https://[YOUR_ADMIDIO]/modules/sso/index.php/oidc/.well-known/openid-configuration''). It should be pasted into Nextcloud's OpenID Client configuration as "Discovery endpoint". All other endpoints shown in Admidio's preferences screen are provided in the discovery document and don't need to be copied manually.
-{{ :en:2.0:sso:sso_nc_user_oidc_04a_pluginpage_discovery.png?direct&950 |}}
+The configuration of the provider in Nextcloud is now best done in parallel with the client configuration in Admidio.
 ==== Setting up the Client (SP) in Admidio ====
@@ Line 62: / Line 67: @@
 {{ :en:2.0:sso:sso_oidc_01-07_clientadmin.png?direct&400 |}}
+  * Nextcloud's user_oidc plugin uses the Discovery URL (of the form ''https://[YOUR_ADMIDIO]/modules/sso/index.php/oidc/.well-known/openid-configuration'') from Admidio to configure most of the general OpenID Connect settings automatically. Copy the Discovery URL from the top of the OIDC client page in Admitio into NextCloud's "Discovery endoint" field. All other endpoints shown in Admidio's preferences screen are provided in the discovery document and don't need to be copied manually.
+{{ :en:2.0:sso:sso_nc_user_oidc_04a_pluginpage_discovery.png?direct&950 |}}
   * 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 and Nextcloud 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.
+  * The **"Client ID"** and **"Client Secret"** in Admidio and Nextcloud have to match exactly. The ID is typically the client's URL, although some clients allow any unique identifier. The Client Secret should be 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 can not be recovered any more. However, one can always create a new Client Secret in Admidio and copy that to the client's configuration.
-  * Enter the **scopes** you desire in the Nextcloud config and make sure that Admidio's config matches it. At least **openid must be included** (Admidio will implicitly add it). If group support is desired, the "groups" scope must be included (and the corresponding groups claim mapped, and group support selected in the Nextcloud config).
-  * In Admidio, choose which field should be sent to and used by the Nextcloud Plugin to uniquely identify users. This would typically be the login name, although the user ID or UUID area also possible.
   * Nextcloud will display its **Redirect URL** at the very top of the form, which needs to be copied to Admidio's OpenID client configuration.
 {{ :en:2.0:sso:sso_nc_user_oidc_05_configuration.png?direct&900 |}}
+  * Enter the **scopes** you desire in the Nextcloud config and make sure that Admidio's config matches it. At least **openid must be included** (Admidio will implicitly add it). If group support is desired, the "groups" scope must be included (and the corresponding groups claim mapped, and group support selected in the Nextcloud config).
   * In addition, Nextcloud also provides settings to map OpenID claims (defined profile fields with a fixed name, defined in the OpenID standard) to the Nextcloud user's profile data. None of them are required, but they can be mapped, if profile information should be transferred from Admidio to Nextcloud: