Differences

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

--- en:2.0:single_sign_on [2025/05/04 17:19] – kainhofer
+++ en:2.0:single_sign_on [2026/09/11 09:29] (current) – [C. Configuring Admidio with the Relying Party] kainhofer
@@ Line 1: / Line 1: @@
-====== Single-Sign-On using Admidio's User Accounts: SAML 2.0 and OpenId Connect ======
+====== Single Sign-On using Admidio's User Accounts: SAML 2.0 and OpenID Connect ======
-Starting with version 5.0, Admidio can be used by other applications to authenticate users against Admidios user base via Single-Sign-On (SSO). When initiating a login to the application, the user is redirected to Admidio to log in, and after successful authentication, is redirected back to the client app and logged in there. The user has to log in only to Admidio and is automatically given access to other (configured) applications. The other applications do not have to store or process any passwords.
+Starting with version 5.0, Admidio can be used as a central login system for other applications using Single Sign-On (SSO).
-The two dominant protocols are the XML-based SAML 2.0((https://wiki.oasis-open.org/security/FrontPage)) and the JSON-based OpenId Connect (OIDC)((https://openid.net/developers/specs/)). Admidio can act as an Identity Provider (IdP) for both protocols. We will describe the configuration in general for both protocols for the following systems:
+When a user signs in to a connected application, they are redirected to Admidio for authentication, and after successful login are redirected back to the appplication, where they are automatically signed in.
+Users only need to log in to Admidio and can access other configured applications without entering their username and password again. The connected applications do not need to store or process the users' passwords themselves.
+Admidio supports the two most widely used SSO protocols:
+  * **SAML 2.0**(([[https://wiki.oasis-open.org/security/FrontPage|OASIS SAML documentation]])), an XML-based protocol
+  * **OpenID Connect (OIDC)**(([[https://openid.net/developers/specs/|OpenID Connect specifications]])), an authentication protocol based on OAuth 2.0
+With both protocols, Admidio authenticates the user and provides the connected application with the information required to sign the user in. In SAML terminology, Admidio acts as an **Identity Provider (IdP)**. In OpenID Connect, the corresponding term is **OpenID Provider (OP)**.
+The following sections describe the general configuration for both protocols using the following systems as examples:
 ^ Client               ^ SAML 2.0         ^ OpenID Connect ^ Notes                |
 ^ {{:en:2.0:sso:logos:nextcloud.svg?40&nolink|Nextcloud}} Nextcloud   | [[en:2.0:single_sign_on:saml_nextcloud|SAML 2.0 with Nextcloud]]  | [[en:2.0:single_sign_on:oidc_nextcloud|OpenID with Nextcloud]]  |
-^ {{:en:2.0:sso:logos:dokuwiki.png?45&nolink|DokuWiki}} DokuWiki  | [[en:2.0:single_sign_on:saml_dokuwiki|SAML 2.0 with DokuWiki]] | [[en:2.0:single_sign_on:oidc_dokuwiki|OpenID with DokuWiki]]  |  |
+^ {{:en:2.0:sso:logos:dokuwiki.png?40&nolink|DokuWiki}} DokuWiki  | [[en:2.0:single_sign_on:saml_dokuwiki|SAML 2.0 with DokuWiki]] | [[en:2.0:single_sign_on:oidc_dokuwiki|OpenID with DokuWiki]]  |  |
-^ {{:en:2.0:sso:logos:wordpress-logotype-standard.png?150&nolink|Wordpress}}  | [[en:2.0:single_sign_on:saml_wordpress|SAML 2.0 with Wordpress]]  | [[en:2.0:single_sign_on:oidc_wordpress|OpenID  with Wordpress]]   |  |
+^ {{:en:2.0:sso:logos:wordpress-logotype-standard.png?120&nolink|Wordpress}}  | [[en:2.0:single_sign_on:saml_wordpress|SAML 2.0 with Wordpress]]  | [[en:2.0:single_sign_on:oidc_wordpress|OpenID  with Wordpress]]   |  |
 ^ {{:en:2.0:sso:logos:joomla.png?120&nolink|Joomla}}        | [[en:2.0:single_sign_on:saml_joomla|SAML 2.0 with Joomla]]  | [[en:2.0:single_sign_on:oidc_joomla|OpenID with Joomla]]  |  |
 ^ {{:en:2.0:sso:logos:mediawiki.svg?120&nolink|MediaWiki}}  | [[en:2.0:single_sign_on:saml_mediawiki|SAML 2.0 with MediaWiki]]  | [[en:2.0:single_sign_on:oidc_mediawiki|OpenID with MediaWiki]]  |  |
-^ {{:en:2.0:sso:logos:moodle.png?150&nolink|Moodle}}        | [[en:2.0:single_sign_on:saml_moodle|SAML 2.0 with Moodle]]  | [[en:2.0:single_sign_on:oidc_moodle|OpenID with Moodle]]  |  |
+^ {{:en:2.0:sso:logos:moodle.png?90&nolink|Moodle}}        | [[en:2.0:single_sign_on:saml_moodle|SAML 2.0 with Moodle]]  | [[en:2.0:single_sign_on:oidc_moodle|OpenID with Moodle]]  |  |
-^ {{:en:2.0:sso:logos:gitlab.svg?110&nolink|Gitlab}}        | [[en:2.0:single_sign_on:saml_gitlab|SAML 2.0 with Gitlab]]  | [[en:2.0:single_sign_on:oidc_gitlab|OpenID with Gitlab]]  |  |
+^ {{:en:2.0:sso:logos:gitlab.svg?100&nolink|Gitlab}}        | [[en:2.0:single_sign_on:saml_gitlab|SAML 2.0 with Gitlab]]  | [[en:2.0:single_sign_on:oidc_gitlab|OpenID with Gitlab]]  |  |
-^ {{:en:2.0:sso:logos:odoo_logo.svg?80&nolink|Odoo}}       | [[en:2.0:single_sign_on:saml_odoo|SAML 2.0 with Odoo]]  | [[en:2.0:single_sign_on:oidc_odoo|OpenID with Odoo]]  |  |
+^ {{:en:2.0:sso:logos:odoo_logo.svg?60&nolink|Odoo}}       | [[en:2.0:single_sign_on:saml_odoo|SAML 2.0 with Odoo]]  | [[en:2.0:single_sign_on:oidc_odoo|OpenID with Odoo]]  |  |
 ^ {{:en:2.0:sso:logos:keycloak.svg?120&nolink|Keycloak}}    | [[en:2.0:single_sign_on:saml_keycloak|SAML 2.0 with Keycloak]]  | [[en:2.0:single_sign_on:oidc_keycloak|OpenID with Keycloak]]  |  |
 ^ {{:en:2.0:sso:logos:simplesamlphp.png?140&nolink|SimpleSAMLphp}}  | [[en:2.0:single_sign_on:simplesamlphp|SAML 2.0 with SimpleSAMLphp]]  |  |  |
-|
+^ {{:en:2.0:sso:logos:matomo_logo.svg?120&nolink|Matomo}}  | | [[en:2.0:single_sign_on:oidc_matomo|OpenID with Matomo]]  |  |
+^ {{:en:2.0:sso:logos:gnu_mailman_logo2010.png?120&nolink|Mailman3}}  | | [[en:2.0:single_sign_on:oidc_mailman3|OpenID with Mailman3]]  |  |
+^ {{:en:2.0:sso:logos:plesk_logo_primary_positive_.jpg?60&nolink|Plesk}}  | | [[en:2.0:single_sign_on:oidc_plesk|OpenID with Plesk]]  |  |
-Other systems like Prestashop do not provide any freely available SAML plugin, only some very expensive commercial extensions.
+Other systems like Prestashop do not provide any freely available SAML or OpenID plugin, only some very expensive commercial extensions.
@@ Line 28: / Line 41: @@
 To set up a third-party web application to use single-sign-on through Admidio as a SAML 2.0 Identity Provider (so that other applications will use Admidio's user accounts for their logins), one has to take three steps:
   - [[#a_basic_setup_for_admidio_as_a_saml_id_provider|General Setup of the IdP in Admidio]]:
-    - Create a cryptographic key for signing/encryption
+    - Enable SAML 2.0
-    - Choose a unique entityID (typically the URL of the Admidio installation)
+    - Choose a unique entityID for the whole Admidio installation (not client-specific, typically the URL of the Admidio installation)
+    - Save (a cryptographic key for signatures and encryption will be generated automatically )
   - [[#b_configuring_an_app_service_provider_to_use_sso_with_admidio|Configuration of the client app (Service Provider)]]: Admidio will provide a link with all required metadata for clients to use (https://[ADMIDIO_URL]/modules/sso/index.php/saml/metadata).
-    - In the simplest case, paste the metadata URL into the client configuration
+    - If the client supports it, paste the metadata URL into the client configuration
-    - If the client does not support auto-setup using metadata, manually copy/enter the settings:
+    - Otherwise copy/enter the settings manually:
       - Admidio URLs for Single-sign-on (SSO) and Single-Log-Out (SLO)
       - Public key / certificate of the Admidio IdP.
@@ Line 46: / Line 60: @@
 ===== Setup overview for OpenID Connect =====
-To set up a third-party web application (the "Relying Party", short RP) to use single-sign-on through Admidio as an OpenID Connect Identity Provider (so that other applications will use Admidio's user accounts for their logins), one has to take three steps:
+To set up a web application (the "Relying Party"="RP") for single-sign-on through Admidio as an OIDC Identity Provider (so that other applications will use Admidio's user accounts for their logins), one has to take three steps:
   - [[#a_basic_setup_for_admidio_as_an_openid_connect_id_provider|General Setup of the OIDC IdP in Admidio]]:
-    - Create a cryptographic key for signing/encryption
+    - Enable OIDC support in Admidio
-    - Choose a unique entityID (typically the URL of the Admidio installation)
+    - The issuer URL should be left empty in most cases, i.e. the URL of the Admidio installation will be used.
-  - [[#b_configuring_an_app_relying_party_to_use_sso_with_admidio|Configuration of the client app (Relying Party)]]: Admidio will provide a link with all required metadata for clients to use (https://[ADMIDIO_URL]/modules/sso/index.php/oidc/.well-known/openid-configuration).
+    - A cryptographic key for signatures and encryption will be generated automatically if needed, there is no need to generate or select one manually (in the advanced settings)
-    - In the simplest case, paste the metadata URL into the client configuration
+    - Save
-    - If the client does not support auto-setup using metadata, manually copy/enter the settings:
+  - [[#b_configuring_an_app_relying_party_to_use_sso_with_admidio|Configuration of the client app (Relying Party)]]: Admidio
-      - Admidio URLs (endpoints) for authorization, token, userinfo an optionally logout
+provides a link to the discovery URL for automatic client setup (https://[ADMIDIO_URL]/modules/sso/index.php/oidc/.well-known/openid-configuration).
-      - Public key / certificate of the Admidio IdP.
+    - If the client supports it, paste the discovery URL into the client configuration for automatic configuration
+    - Otherwise copy/enter the endpoint URLs from Admidio manually: authorization, token, userinfo an optionally logout URL
     - Choose a unique "Client ID" to identify the client to Admidio.
-    - Select the scopes (classes of information) that Admidio should send to the client (e.g. "openid,profile,email,address,phone,groups,custom", at least "openid" is required)
+    - The client should provide you with a Redirect URI needed for Admidio's client configuration. Note it.
-    - Optionally a mapping of the OpenID claims (individual data fields) to the client's profile fields
   - [[#c_configuring_admidio_with_the_relying_party|Set up Admidio to respond to that particular client (RP)]]:
     - Create a new OIDC client in Admidio's SSO client administration ("Preferences" -> "Single-Sign-On" -> "Single-Sign On Client Administration")
       - Paste the "Client ID" as given in the client app, and paste the Redirect URI given by the client.
       - Admidio will show a "Client Secret", which must be copied to the client's config.
-      - Select which scopes (classes of information) should be allowed to be sent to the client, and optionally select / map Admidio's profile fields and groups to OpenID claims (individual pieces/fields of information)
+      - Many simple OIDC clients do not support PKCE. If you get an error message that the client requires PKCE, disable PKCE in Admidio's client configuration-
-    - OpenID does NOT provide any automatic configuration of the client using metadata((There is an OpenID extension for dynamic/automatic client registration, but that has other complexities!)).
+      - Select which scopes (classes of information) should be allowed to be sent to the client, and optionally select and map Admidio's profile fields and groups to OpenID claims (individual pieces/fields of information)
+    - In contrast to SAML, OpenID does NOT provide any automatic configuration of the client using metadata((There is an OpenID extension specification for dynamic/automatic client registration, but that has other complexities!)).
@@ Line 89: / Line 104: @@
 SAML 2.0 is based on XML messages, and basically just outsources the login form and the resulting login success decision to the IdP. If login is successful, the IdP sends this information (together with the user name and optionally some further profile fields) as a cryptographically signed XML to the SAML client.
+{{ :en:2.0:sso:admidio_saml_loginflows_saml.svg?right&600&direct|}}
 In the SAML case, the login flow above changes to the following. But but from a user perspective, the same steps of entering a password are done, just at a different system. The browser redirects involved in the flow, are hardly noticed by the user and don't require user interaction.
-{{ :en:2.0:sso:admidio_saml_loginflows_saml.svg?right&600&direct |}}
   - User clicks on "Log In"
   - The app does not determine user login itself. Instead it relies on a third party (the "Identity Provider", short IdP) to determine whether a user has access:
@@ Line 109: / Line 124: @@
 ==== Single-Sign-On with OpenID Connect using an external Identity Provider (IdP) ====
-OpenID Connect is based on exchanging data with JSON objects. Rather than working only with browser redirects like SAML, OpenID is based on OAuth and extensively uses direct communication ("backchannel") between the Relying Party and the IdP. Rather than documenting only a successful login, OpenID separates authentication (successfull login) and authorization (roles that grant user rights). It also does not rely on an active session at the IdP. Rather it generates a dedicated password (the "token") for the client and thus replaces the user's individual password with app-specific passwords, which are handled internally by the client and the IdP without the user noticing. When such a token expires, another (refresh) token can be used to create a new token, so that no new login is required. All this is done in the background and the user experience is basically the same as with a direct login or with SAML.
+OpenID Connect is based on exchanging data with JSON objects. It is an extension of the OAuth 2.0 protocol, which only handles authentication. The OpenID layer adds additional profile information and permissions, but uses OAuth for the basic authorization.
+Rather than working only with browser redirects like SAML, OpenID is based on OAuth and extensively uses direct communication ("backchannel") between the Relying Party and the IdP. Rather than documenting only a successful login, OpenID separates authentication (successfull login) and authorization (roles that grant user rights). It also does not rely on an active session at the IdP. Rather it generates a dedicated password (the "token") for the client and thus replaces the user's individual password with app-specific passwords, which are handled internally by the client and the IdP without the user noticing. When such a token expires, another (refresh) token can be used to create a new token, so that no new login is required. All this is done in the background and the user experience is basically the same as with a direct login or with SAML.
@@ Line 120: / Line 137: @@
 ===== A. Basic Setup for Admidio as a SAML ID Provider =====
-Admidio's SSO configuration is done in the preferences (Tab "Modules", section "Single-Sign-On (SAML 2.0, OpenId Connect)").
+Admidio's 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 ====
-  * The first thing to do is to create a cryptographic key (typically an RSA key with 2048 bit). For this, use the "SSO cryptographic Keys Administration" button to switch to the key administration page.
+{{:en:2.0:sso:sso_saml_01-01_setup_admidio_preferences.png?direct&400|}}{{:en:2.0:sso:sso_saml_01-05_setup_admidio_preferences.png?direct&400|}}
-  * {{ :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).
-    * 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 IdP ====
-  * In the SSO section of the preferences, you now need to enable SAML 2.0 Single-Sign-on and configure the following settings:
+  * First enable SAML 2.0 Single-Sign-on to show the SAML-specific settings
-    * **SAML Entity ID**: The URL of your installation (needs to be a **unique ID**, the URL is usually used, but not required)
+  * **SAML Entity ID**: The URL of your installation (needs to be a **unique ID**, the URL is usually used, but some clients do not support colons or slashes in the ID)
-    * **Key for signatures**: Select the key that you just generated; will be used to cryptographically sign the messages to the Service Provider to prevent man-in-the-middle attacks
+  * Save
-    * Key for **Encryption**: If the SP requires (or recommends) encrypting the messages, you can select a key for encryption, too. This can be (but does not have to be) the same key as for signatures.
-    * Select whether Admidio adivses all SPs to sign their messages in turn. This requires each client to have a cryptographic key generated for itself, which some clients (e.g. DokuWiki) do not support. Clients that do not support signatures, will still work, this is just a declaration of preference by Admidio!
-    * Save
-{{ :en:2.0:sso:sso_saml_01-05_setup_admidio_preferences.png?direct&600 |}}
-The Preferences page also lists all the relevant data to set up the client as a Service Provider. Particularly useful will be the Metadata URL, which provides all data to set up a client (SP) in XML format. You don't need to do anything, the SSO plugin for Admidio provides this out of the box. Here is an example of such a metadata xml:
+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.
-{{ :en:2.0:sso:sso_saml_01-06_setup_saml_metadata.png?direct&400 |}}
-Notice that it contains both the public key / certificate of the signing and encryption keys, as well as the URLs to the SingleSignOnService (SSO) and the SingleLogOutService (SLO) at the admidio installation. Furthermore, the first half of the XML contains the cryptographic signature of the XML, signed with the private key to prove that the metadata file actually comes from the admidio installation and not from some adversary.
+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**.
-Each SP first needs to be set up with the URLs (and keys) to connect to Admidio. This can ideally be done by providing the SP with the link to the metadata. After that, Admidio needs to be configured to accept login requests from the SP. Again, each SP typically provides the required data as a metadata XML, which can be loaded in Admidio to set up the client for Single-sign-on functionality. The details depend on the actual client app.
+**Next Steps:** [[single_sign_on#b_configuring_an_app_service_provider_to_use_sso_with_admidio|Configure the client application for use with Admidio]]
+==== Metadata file for automatic setup ====
+That metadata URL provides all data to set up a client (SP) in XML format and can be automatically processed by the SAML client, if supported. Here is an example of such a metadata xml:
+<code xml>
+<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://admidio.local" ID="_1df88e3a68af770dd23bf870b343990d38ce5c4cf0">
+  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
+    <ds:SignedInfo>
+      <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
+      <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
+      <ds:Reference URI="#_1df88e3a68af770dd23bf870b343990d38ce5c4cf0">
+        <ds:Transforms>
+          <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
+          <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
+        </ds:Transforms>
+        <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
+        <ds:DigestValue>5ErkuUnL6eMZ0LnGvWGmZDrF/peW7b81WHQgFGCIB5A=</ds:DigestValue>
+      </ds:Reference>
+    </ds:SignedInfo>
+    <ds:SignatureValue>BT1Rih/IZXn...8mSd0jg==</ds:SignatureValue>
+    <ds:KeyInfo>
+      <ds:X509Data>
+        <ds:X509Certificate>MIID4DCCAsigAwIBA...MyLpVB5</ds:X509Certificate>
+      </ds:X509Data>
+    </ds:KeyInfo>
+  </ds:Signature>
+  <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" WantAuthnRequestsSigned="true">
+    <KeyDescriptor use="signing">
+      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
+        <ds:X509Data>
+          <ds:X509Certificate>MIID4DCCAsigAwIBA...MyLpVB5</ds:X509Certificate>
+        </ds:X509Data>
+      </ds:KeyInfo>
+    </KeyDescriptor>
+    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://admidio.local/modules/sso/index.php/saml/slo"/>
+    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://admidio.local/modules/sso/index.php/saml/slo"/>
+    <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>
+    <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://admidio.local/modules/sso/index.php/saml/sso"/>
+    <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://admidio.local/modules/sso/index.php/saml/sso"/>
+  </IDPSSODescriptor>
+</EntityDescriptor>
+</code>
+Notice that it contains both the public key / certificate of the signing and encryption keys, as well as the URLs to the SingleSignOnService (SSO) and the SingleLogOutService (SLO) at the admidio installation. Furthermore, the first half of the XML contains the cryptographic signature of the XML, signed with the private key to prove that the metadata file actually comes from the admidio installation and not from some adversary.
+==== Advanced settings ====
+{{ :en:2.0:sso:sso_saml_advanced_settings.png?400|}}The SSO setup in Admidio aims to be as straightforward and painless as possible. For this reason, some advanced settings are not shown by default, but can still be configured in the "Advanced settings" are of the SAML preferences. Click on the small triangle to show or hide the advanced section.
+    * **Key for signatures**: Select the cryptographic key that will be used to cryptographically sign the messages to the Service Provider to prevent man-in-the-middle attacks
+    * Key for **encryption**: If the SP requires (or recommends) encrypting the messages, you can select a key for encryption, too. This can be (but does not have to be) the same key as for signatures.
+    * Select whether Admidio requires all SPs to sign their messages in turn. This requires each client to have a cryptographic key generated for itself, which some clients (e.g. DokuWiki) do not support. If a client does not provide a key, this setting has no effect and SSO will still work, but if the client supplies its own key, all requests must be signed by that key.
 ===== 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
@@ Line 163: / 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.
-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]]
@@ Line 188: / Line 250: @@
 To ensure only legitimate login requests from the real client are processed, Admidio needs the entity ID, the URL for redirect as well as the x509 certificate (if messages are cryptographically signed). The following settings are needed for setup. They MUST be consistent with the settings configured in the SAML client (SP). Many SPs provide a Metadata XML link or file with all required settings included for automatic client setup. In Admidio's SAML client section, one can input the metadata URL and Admidio will pre-configure the client, but manual adjustments are possible (and in many areas even needed).
-  * **Metadata URL** (for automatic setup of clients): https://[YOUR_ADMIDIO_URL]/modules/sso/index.php/saml/metadata
+=== If your SAML client provides Metadata (URL or XML) ===
-    * If your SP supports entering and loading the metadata XML, make sure to use it. It will load the correct settings from the SAML IdP and set up most settings correctly!{{ :en:2.0:sso:sso_saml_01-08a_clientsetup1_metadata.png?direct&400 |}}
+  * **Metadata URL** (for automatic setup of clients):
-  * **IdP SAML Entity ID** (unique identifier of the Admidio instance): https://[YOUR_ADMIDIO_URL]
+    * If your SP provides a metadata URL or the metadata xml, Admidio will load the correct settings from the SAML SP and set up most settings correctly!
-  * **SSO Endpoint** (where the SP sends the login request): https://[YOUR_ADMIDIO_URL]/modules/sso/index.php/saml/sso
+    * 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 |}}
-  * **SLO Endpoint** (where logout requests are sent to): https://[YOUR_ADMIDIO_URL]/modules/sso/index.php/saml/slo
+    * 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 |}}
-  * **x509 Certificate** (to allow clients to verify the cryptographic signatures): PEM-format needs to be copied out of the Admidio preferences
-  * **User ID**: Whether the client gets the numeric Admidio user id, the globally unique UUID, or the user's login name as user ID
+=== If your SAML client does not provide metadata ===
+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)
+  * **ACS URL** (where responses to login requests are sent to)
+  * **Single-Log-Out URL** (optional): Backchannel endpoint to log out from all clients
+  * **x509 Certificate** (to allow verification of the messages sent by the SP): PEM-format needs to be copied out from the client
+=== Further configuration for all clients ===
+  * **User ID field**: Whether the client gets the numeric Admidio user id or the globally unique UUID as a persistent identifier. This field is used internally and will never be visible to the user.
   * Further **profile data/fields** transmitted to the client on successful login
   * Which **roles / group memberships** are sent to the client on successful login. The data fields and groups can be mapped to different names, if the client cannot handle Admidio's fields and role names. On particular case is the admin role, where many clients use a role named "admin" to grant admin access to a user logged in via SAML.
@@ Line 210: / Line 281: @@
-Admidio's general SSO configuration is done in the preferences (Tab "Modules", section "Single-Sign-On (SAML 2.0, OpenId Connect)").
+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:
-{{ :en:2.0:sso:sso_oidc_01-06_setup_openid_metadata.png?direct&400 |}}
+<code json>
+{
+  "issuer": "https://admidio.local/modules/sso/index.php/oidc",
+  "authorization_endpoint": "https://admidio.local/modules/sso/index.php/oidc/authorize",
+  "token_endpoint": "https://admidio.local/modules/sso/index.php/oidc/token",
+  "userinfo_endpoint": "https://admidio.local/modules/sso/index.php/oidc/userinfo",
+  "jwks_uri": "https://admidio.local/modules/sso/index.php/oidc/jwks",
+  "introspection_endpoint": "https://admidio.local/modules/sso/index.php/oidc/introspect",
+  "revocation_endpoint": "https://admidio.local/modules/sso/index.php/oidc/revoke",
+  "end_session_endpoint": "https://admidio.local/modules/sso/index.php/oidc/logout",
+  "frontchannel_logout_supported": true,
+  "frontchannel_logout_session_supported": true,
+  "backchannel_logout_supported": true,
+  "backchannel_logout_session_supported": true,
+  "scopes_supported": ["openid", "profile", "email", "address", "phone", "groups", "custom"],
+  "response_types_supported": ["code"],
+  "response_modes_supported": ["query"],
+  "grant_types_supported": ["authorization_code", "refresh_token"],
+  "code_challenge_methods_supported": ["S256"],
+  "subject_types_supported": ["public"],
+  "id_token_signing_alg_values_supported": ["RS256"],
+  "token_endpoint_auth_methods_supported": ["client_secret_post", "client_secret_basic"],
+  "introspection_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
+  "revocation_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
+  "claims_supported": [
+    "sub", "iss", "aud", "exp", "iat", "auth_time", "nonce", "acr", "amr", "sid",
+    "uuid", "preferred_username", "name", "family_name", "given_name", "email", "phone_number", "address",
+    "groups", "locale", "website", "gender", "birthdate"
+  ],
+  "claims_parameter_supported": false,
+  "request_parameter_supported": false,
+  "request_uri_parameter_supported": false
+}
+</code>
 In contrast to SAML, the metadata does not contain the public certificate. In OpenID, there is a separate endpoint (the "jwks_uri" in the discovery document) that provides the current key in "JSON Web Key Sets" (JWKS) format.
@@ Line 245: / Line 340: @@
 ===== B. Configuring an App (Relying Party) to use SSO with Admidio =====
-<WRAP center round todo 60%>
-todo box
+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).
-</WRAP>
+  * **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!
+  * **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
+  * **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):
+  * 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
+  * **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.
+In addition each client typically has settings to for further customization.
+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. We have extensively tested the following clients, but other OIDC clients should work as well. The configuration will be similar to the documented clients.
+[[en:2.0:single_sign_on:oidc_nextcloud|{{:en:2.0:sso:logos:nextcloud.svg?40&nolink|Nextcloud}}]][[en:2.0:single_sign_on:oidc_nextcloud| Nextcloud]]
+[[en:2.0:single_sign_on:oidc_dokuwiki|{{:en:2.0:sso:logos:dokuwiki.png?45&nolink|DokuWiki}}]][[en:2.0:single_sign_on:oidc_dokuwiki| DokuWiki]]
+[[en:2.0:single_sign_on:oidc_wordpress|{{:en:2.0:sso:logos:wordpress-logotype-standard.png?150&nolink|Wordpress}}]]
+[[en:2.0:single_sign_on:oidc_joomla|{{:en:2.0:sso:logos:joomla.png?120&nolink|Joomla}}]]
+[[en:2.0:single_sign_on:oidc_mediawiki|{{:en:2.0:sso:logos:mediawiki.svg?120&nolink|MediaWiki}}]]
+[[en:2.0:single_sign_on:oidc_moodle|{{:en:2.0:sso:logos:moodle.png?150&nolink|Moodle}}]]
+[[en:2.0:single_sign_on:oidc_gitlab|{{:en:2.0:sso:logos:gitlab.svg?110&nolink|Gitlab}}]]
+[[en:2.0:single_sign_on:oidc_odoo|{{:en:2.0:sso:logos:odoo_logo.svg?80&nolink|Odoo}}]]
+[[en:2.0:single_sign_on:oidc_keycloak|{{:en:2.0:sso:logos:keycloak.svg?120&nolink|Keycloak}}]]
 ===== C. Configuring Admidio with the Relying Party =====
-<WRAP center round todo 60%>
-todo box
-</WRAP>
+Once the client is set up to send authentication requests to Admidio, Admidio needs to be configured to respond to them. All OpenID clients (Relying Parties) are configured in the SSO Client Administration page, which can be reached from the SSO Preferences page (https://admidio.local/modules/preferences.php?panel=sso) from the SSO OIDC preferences page.
+{{ :en:2.0:sso:sso_saml_01-07_clientlist.png?direct&600 |}}
+To ensure only legitimate login requests from the real client are processed, Admidio needs the entity ID and the Redirect URI. In addition, Admidio will generate a Client Secret (a random string) that needs to be copied to the client's configuration and acts as a client password.
+The following settings are needed for setup. They MUST be consistent with the settings configured in the OpenID Connect client (RP).
+  * **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.
+  * **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 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!
+  * Further **profile data/fields** transmitted to the client on successful login
+  * Which **roles / group memberships** are sent to the client on successful login. The data fields and groups can be mapped to different names, if the client cannot handle Admidio's fields and role names. On particular case is the admin role, where many clients use a role named "admin" to grant admin access to a user logged in via OpenID.
+In addition each client typically has some more settings regarding fields <=> claims mapping, groups, auto-generating accounts for new logins, etc. The details depend on the capabilities of the client.
+{{:en:2.0:sso:sso_oidc_01-08_clientsetup1.png?direct&300|}}{{:en:2.0:sso:sso_oidc_01-09_clientsetup2.png?direct&300|}}{{:en:2.0:sso:sso_oidc_01-10_clientsetup3.png?direct&300|}}
+====== Advanced Settings ======
+==== Generating a Cryptographic Key for Signing and Encryption ====
+  * Both SAML 2.0 and OIDC use cryptographic keys to secure data transmission between Admidio and the client application. When first enabling SAML 2.0 or OIDC, Admidio automatically generated an RSA key with 2048 with default settings. Sometimes, manual key generation might be needed or desired:
+    * Replacing a cryptographic key periodically ("key rollover") is a standard security technique, in case someone had undetected access to the private key.
+    * Some client might have special requirements on the key. Admidio's implementation follows the SAML 2.0 and OIDC standard, but some applications might require even higher security.
+  * {{ :en:2.0:sso:sso_key_dropdown.png?direct&400|}}The advanced settings for OIDC and SAML 2.0 in the preferences page allow selecting a different key or generating a new key. The advanced settings are a closed section within the SAML / OIDC settings and offer a dropdown list to select an existing key for signatures. Additionally, the button to the right links to Admidio's cryptographic key administration.
+{{ :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).
+    * 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 |}}