Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
en:2.0:single_sign_on [2026/09/11 08:38] – [Single-Sign-On with SAML 2.0 using an external Identity Provider (IdP)] kainhoferen:2.0:single_sign_on [2026/09/11 09:29] (current) – [C. Configuring Admidio with the Relying Party] kainhofer
Line 145: Line 145:
   * Save   * Save
  
-The Preferences page also lists all the relevant data to set up the client as a Service Provider. The the client supports automatic setup from metadata, you can copy the metadata URL directly from this page and paste it in the client configuration. Use the "Copy" icon right of the URL.+The Preferences page also lists all the relevant data to set up the client as a Service Provider. If the client supports automatic setup from metadata, you can copy the metadata URL directly from this page and paste it in the client configuration. Use the "Copy" icon right of the URL. 
 + 
 +The SSO settings also provide an advanced section, where you can select or generate crypto keys for the signatures and encryption of the SAML messages. A default key will be generated automatically.
  
 Admidio is now **ready to provide single-sign-on functionality to Service Providers**.  Admidio is now **ready to provide single-sign-on functionality to Service Providers**. 
Line 210: Line 212:
 ===== B. Configuring an App (Service Provider) to use SSO with Admidio ===== ===== B. Configuring an App (Service Provider) to use SSO with Admidio =====
  
-Once Admidio is set up to act as a SAML 2.0 IdP, the clients (Service Providers, "SP") can be configured to use Admidio as their login provider. Many systems either support SAML 2.0 out of the box or with some plugin. The following settings are needed for setup. They are also available for copying at Admidio's SSO preferences page, as well as in the metadata xml.+Once Admidio is set up to act as SAML 2.0 IdP, clients (Service Providers, "SP") can Admidio as their login provider. Many systems support SAML 2.0 out of the box or with a plugin. The following settings are needed for setup. They are also available for copying at Admidio's SSO preferences page, as well as in the metadata xml.
  
   * **Metadata URL** (optional; for automatic setup of clients): https://[YOUR_ADMIDIO_URL]/modules/sso/index.php/saml/metadata   * **Metadata URL** (optional; for automatic setup of clients): https://[YOUR_ADMIDIO_URL]/modules/sso/index.php/saml/metadata
Line 221: Line 223:
   * **User attribute mapping**: Which SAML attributes returned with the login confirmation ("Assertion") correspond to the login name, the full name, the email and possibly the user's group memberships in the SP system.   * **User attribute mapping**: Which SAML attributes returned with the login confirmation ("Assertion") correspond to the login name, the full name, the email and possibly the user's group memberships in the SP system.
  
-In addition each client typically has settings to require sent or received SAML messages to be signed and/or encrypted to ensure a secure login process. The details depend on the capabilities of the client. Some clients do not support encryption, other require all SAML messages to be signed (for good reason!). +In addition each client typically has settings to require sent or received SAML messages to be signed and/or encrypted to ensure a secure login process. The details depend on the capabilities of the client. Some clients do not support encryption at all, other require all SAML messages to be signed (for good reason!). None of these settings are required, but the settings in the client and in Admidio must be consistent, i.e. if a client does not support encryption, Admidio must not require encryption.
-Also, some clients offer a setting that SAML login is only possible for users that are already manually created in the SP, while others offer a setting to automatically create user accounts on successful SAML login. +
  
-The details always depend on the particular client. See the client-specific instructions for details for a particular client. Other clients should work, too, if they properly implement SAML. The configuration will be similar to the documented clients.+Some clients also support Just-in-time user-provisioning (meaning users will be created on-the-fly the first time they are logged in), while others require all users to be presents before they can log in through SAML. 
 + 
 +The details always depend on the particular client.  
 +We have extensively tested Admidio's SAML implementation with the following clients and provide detailed setup instructions for them. Other clients should work, too, if they properly implement SAML, and their configuration will be similar to the documented clients.
  
 [[en:2.0:single_sign_on:saml_nextcloud|{{:en:2.0:sso:logos:nextcloud.svg?40&nolink|Nextcloud}}]][[en:2.0:single_sign_on:saml_nextcloud| Nextcloud]] [[en:2.0:single_sign_on:saml_nextcloud|{{:en:2.0:sso:logos:nextcloud.svg?40&nolink|Nextcloud}}]][[en:2.0:single_sign_on:saml_nextcloud| Nextcloud]]
Line 251: Line 255:
     * If the SP provides a metadata URL, paste it and load it. The URL will be stored and can be reloaded any time, in case the client changes its key or some other settings. {{ :en:2.0:sso:sso_saml_01-08a_clientsetup1_metadata.png?direct&400 |}}     * If the SP provides a metadata URL, paste it and load it. The URL will be stored and can be reloaded any time, in case the client changes its key or some other settings. {{ :en:2.0:sso:sso_saml_01-08a_clientsetup1_metadata.png?direct&400 |}}
     * If the SP provides the metadata in XML format without an URL reachable from admidio, paste the XML code into the input field to parse it. The XML will not be stored by Admidio and must be pasted again if the client changes settings.  {{ :en:2.0:sso:sso_saml_01-08a_clientsetup1_metadataxml.png?direct&400 |}}     * If the SP provides the metadata in XML format without an URL reachable from admidio, paste the XML code into the input field to parse it. The XML will not be stored by Admidio and must be pasted again if the client changes settings.  {{ :en:2.0:sso:sso_saml_01-08a_clientsetup1_metadataxml.png?direct&400 |}}
 +
 +
 === If your SAML client does not provide metadata === === If your SAML client does not provide metadata ===
  
-If your client application does not provide SAML configuration as metadat for automatic setup, you need to copy the following settings from the client into Admidio's client configuration:+If your client application does not provide SAML configuration as metadata for automatic setup, you need to copy the following settings from the client into Admidio's client configuration:
   * **Client ID** (unique identifier of the Client)   * **Client ID** (unique identifier of the Client)
   * **ACS URL** (where responses to login requests are sent to)   * **ACS URL** (where responses to login requests are sent to)
Line 276: Line 282:
  
 Admidio's general SSO configuration is done in the preferences (Tab "Sign in & Security", section "Single-Sign-On").  Admidio's general SSO configuration is done in the preferences (Tab "Sign in & Security", section "Single-Sign-On"). 
-{{ :en:2.0:sso:sso_saml_01-01_setup_admidio_preferences.png?direct&400 |}} 
  
-==== 1. Generating a Cryptographic Key for Signing and Encryption ====+{{:en:2.0:sso:sso_saml_01-01_setup_admidio_preferences.png?direct&600|}} 
 +{{:en:2.0:sso:sso_oidc_01-01a_setup_admidio_preferences.png?500|}}
  
-  * The first thing to do is to create a cryptographic key (typically an RSA key with 2048 bit). If SAML 2.0 and OpenID are used, they can share the same RSA key.  +  - First enable OIDC Single-Sign-On to show the OIDC-specific settings. 
-  * To manage keys, use the "SSO cryptographic Keys Administration" button to switch to the key administration page.  +  - The **Issuer URL** should typically be left empty, so the default URL of Admidio is used. 
-  * {{ :en:2.0:sso:sso_saml_01-02_setup_admidio_keyadmin.png?direct&400|}}At the "SSO Cryptographic Keys Administration" page, create a new key (typically RSA with 2048 bits).  +  - Save
-    * Also enter the URL of the Admidio installation as "Common Name". The other required fields (Organisation, OU, city, etc.) must be filled, but their value is not relevant. Make sure that the expiration date is long enough! By default, an expiration of two years is suggested. +
-{{ :en:2.0:sso:sso_saml_01-03_setup_admidio_newkey.png?direct&400 |}} +
-  * The key should now be listed and activated. Return  to the "Preferences" for further setup. {{ :en:2.0:sso:sso_saml_01-04_setup_admidio_keys.png?direct&400 |}} +
-   +
-==== 2. Configuring Admidio as OpenID Connect IdP ====+
  
-  * In the SSO section of the preferences, you now need to enable OpenID Connect Single-Sign-on and configure the following settings: +The SSO settings also provide an advanced section, where you can select or generate crypto keys for the signatures and encryption of the OIDC messages. A default key will be generated automatically.
-    * **Issuer**: The URL of your installation (needs to be a **unique ID**, the URL is usually used; Some clients require this to the the base URL, others accept any random string) +
-    * **Key for signatures**: Select the key that you just generated; will be used to cryptographically sign the messages to the Relying Party to prevent man-in-the-middle attacks +
-    * Save +
-{{ :en:2.0:sso:sso_oidc_01-05_setup_admidio_preferences.png?direct&600 |}}+
  
-The Preferences page also lists all the relevant URLs (endpoints) to set up the client as a Relying Party. Particularly useful will be the Discovery URL, which provides all data to set up a client (RP) in JSON format. If an app supports automatic discovery, this will automatically do the basic setup. Otherwise you will have to copy the provided endpoint URLs to the client's config. Here is an example of such a discovery JSON:+The Preferences page also lists all the relevant URLs (endpoints) to set up the client as a Relying Party. If client supports automatic discovery, you can copy the discovery URL from this page and paste it in the client configuration. Use the “Copy” icon right of the URL. Otherwise you will have to copy the provided endpoint URLs to the client's config. Here is an example of such a discovery JSON:
 <code json> <code json>
 { {
Line 344: Line 341:
  
  
-Once Admidio is set up to act as an OpenID IdP, the clients (Relying Parties, "RP") can be configured to use Admidio as their login provider. Many systems either support OpenID Connect out of the box or with some plugin. The following settings are needed for setup. They are also available for copying at Admidio's SSO preferences page, as well as in the metadata json (from the discovery URL).+Once Admidio is set up to act as OpenID Identity Provider, clients can be configured to use Admidio as their login provider. Many systems support OpenID Connect out of the box or with some plugin. The following settings are needed for setup. They are also available for copying at Admidio's SSO preferences page, as well as in the metadata json (from the discovery URL).
  
   * **Discovery URL** (optional; for automatic setup of clients): https://[YOUR_ADMIDIO_URL]//modules/sso/index.php/oidc   * **Discovery URL** (optional; for automatic setup of clients): https://[YOUR_ADMIDIO_URL]//modules/sso/index.php/oidc
     * If your RP supports auto-configuration, make sure to use it. It will load the correct settings from the SAML IdP and set up most settings correctly!     * If your RP supports auto-configuration, make sure to use it. It will load the correct settings from the SAML IdP and set up most settings correctly!
-  * **IdP Isuer** (unique identifier of the Admidio instance): https://modules/sso/index.php/oidc+  * **IdP Issuer** (unique identifier of the Admidio instance): https://modules/sso/index.php/oidc
   * **Authorization Endpoint** (where the RP sends the login request): https://[YOUR_ADMIDIO_URL]/modules/sso/index.php/saml/sso   * **Authorization Endpoint** (where the RP sends the login request): https://[YOUR_ADMIDIO_URL]/modules/sso/index.php/saml/sso
   * **Token Endpoint** (where the RP sends requests to convert an auth code to a token, i.e. an app-specific password replacement): https://[YOUR_ADMIDIO_URL]/modules/sso/index.php/saml/slo   * **Token Endpoint** (where the RP sends requests to convert an auth code to a token, i.e. an app-specific password replacement): https://[YOUR_ADMIDIO_URL]/modules/sso/index.php/saml/slo
   * **Userinfo Indpoint** (where the RP can request details about the user):    * **Userinfo Indpoint** (where the RP can request details about the user): 
 +  * The (unique) **Client ID** and **Client Secret** must be entered identically in Admidio's client configuration and in the client. They serve as "password" to grant access to the client.
   * **Scopes** (which groups of profile data are requested by the client): Any of openid (required), profile, address, phone, email, custom, groups, roles   * **Scopes** (which groups of profile data are requested by the client): Any of openid (required), profile, address, phone, email, custom, groups, roles
   * **User attribute mapping**: Which data fields (OpenID claims) returned by Admidio correspond to the login name, the full name, the email and possibly the user's group memberships in the RP system.   * **User attribute mapping**: Which data fields (OpenID claims) returned by Admidio correspond to the login name, the full name, the email and possibly the user's group memberships in the RP system.
Line 358: Line 356:
 Also, some clients offer a setting that SAML login is only possible for users that are already manually created in the RP, while others offer a setting to automatically create user accounts on successful SAML login.  Also, some clients offer a setting that SAML login is only possible for users that are already manually created in the RP, while others offer a setting to automatically create user accounts on successful SAML login. 
  
-The details always depend on the particular client. See the client-specific instructions for details for a particular client. Other clients should work, too, if they properly implement SAML. The configuration will be similar to the documented clients.+The details always depend on the particular client. We have extensively tested the following clients, but other OIDC clients should work as well. The configuration will be similar to the documented clients.
  
  
Line 384: Line 382:
   * **Client ID** (unique identifier of the client): typically the URL of the OpenID client (RP)((Some RPs use basic auth by default, which does not allow special characters in the username. In this case, the URL MUST NOT be used, as this will prevent successful login! Other OpenID clients hardcode the client ID as their URL.))   * **Client ID** (unique identifier of the client): typically the URL of the OpenID client (RP)((Some RPs use basic auth by default, which does not allow special characters in the username. In this case, the URL MUST NOT be used, as this will prevent successful login! Other OpenID clients hardcode the client ID as their URL.))
   * **Client Secret** (basically the client's password to access Admidio): Admidio will create this secret when the RP is created and will store it only as a hash in the database. Make sure to copy the secret before saving, as it is not possible to retrieve it later! One can, however, simply recreate a new secret and paste that into the RP's configuration.   * **Client Secret** (basically the client's password to access Admidio): Admidio will create this secret when the RP is created and will store it only as a hash in the database. Make sure to copy the secret before saving, as it is not possible to retrieve it later! One can, however, simply recreate a new secret and paste that into the RP's configuration.
-  * **Redirect URI** (where the user is redirected after successful login)+  * **Redirect URI** (where the user is redirected after successful login). Many clients send an explicit URL where users are returned after a successful OIDC logout. To prevent security issues, only explicitly listed URLs are allowed. Multiple URLs can be given, one per line, and a **%%*%%** can be used as a placeholder (not allowed in the protocol or the domain name, only in the path after the domain). Some clients (like Wordpress) append variable options like the user's language. In that case, the placeholder should be used.
  
-  * **User ID field**: Whether the client gets the numeric Admidio user id, the globally unique UUID, or the user's login name as user ID+  * **User ID field**: Whether the client gets the numeric Admidio user id, the globally unique UUID, or the user's login name as user ID to uniquely identify users. This is not the suggested login name in the client, but an internal identifier.
   * **Permitted scopes**: OpenID defines certain groups of profile data, for which permission can be granted. The RP will include the scopes it is interested in in its login request, and the OpenID Provider (OP, Admidio in our case) will return the profile fields ("claims") corresponding to those scopes, if permission is given. The "openid" scope MUST always be present in OpenID!   * **Permitted scopes**: OpenID defines certain groups of profile data, for which permission can be granted. The RP will include the scopes it is interested in in its login request, and the OpenID Provider (OP, Admidio in our case) will return the profile fields ("claims") corresponding to those scopes, if permission is given. The "openid" scope MUST always be present in OpenID!
   * Further **profile data/fields** transmitted to the client on successful login   * Further **profile data/fields** transmitted to the client on successful login
  • en/2.0/single_sign_on.1789108699.txt.gz
  • Last modified: 2026/09/11 08:38
  • by kainhofer