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 [2025/05/03 15:32] – kainhoferen:2.0:single_sign_on [2025/05/05 01:25] (current) – [C. Configuring Admidio with the Service Provider] kainhofer
Line 3: Line 3:
 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 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.
  
-The two dominant protocols as SAML 2.0\footnote{https://wiki.oasis-open.org/security/FrontPage} and OpenId Connect (OIDC)\footnote{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:+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:
  
-<WRAP centeralign> 
-[[en:2.0:single_sign_on:saml_dokuwiki|{{:en:2.0:sso:logos:dokuwiki.png?75|}}]][[en:2.0:single_sign_on:saml_dokuwiki| DokuWiki]]    [[en:2.0:single_sign_on:saml_nextcloud|{{:en:2.0:sso:logos:nextcloud.svg?100|Nextcloud}}]]    [[en:2.0:single_sign_on:saml_wordpress|{{:en:2.0:sso:logos:wordpress-logotype-standard.png?150|Wordpress}}]]  [[en:2.0:single_sign_on:saml_joomla|{{:en:2.0:sso:logos:joomla.png?150|}}]] 
  
-[[en:2.0:single_sign_on:saml_mediawiki|{{:en:2.0:sso:logos:mediawiki.svg?200|}}]]   [[en:2.0:single_sign_on:saml_gitlab|{{:en:2.0:sso:logos:gitlab.svg?150|}}]]  [[en:2.0:single_sign_on:saml_odoo|{{:en:2.0:sso:logos:odoo_logo.svg?125|}}]]  +^ 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:single_sign_on:saml_keycloak|{{:en:2.0:sso:logos:keycloak.svg?200|}}]]    [[en:2.0:single_sign_on:simplesamlphp +^ {{: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:simplesamlphp.png?200|}}]] +^ {{: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]]   |  | 
-</WRAP>+^ {{: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: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: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: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]]  |  |  | 
 +|
  
 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 plugin, only some very expensive commercial extensions. 
Line 22: Line 27:
  
 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: 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]]: +  - [[#a_basic_setup_for_admidio_as_a_saml_id_provider|General Setup of the IdP in Admidio]]:
     - Create a cryptographic key for signing/encryption     - Create a cryptographic key for signing/encryption
-    - Choose a unique entityID +    - Choose a unique entityID (typically the URL of the Admidio installation) 
-  - [[#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]/adm_program/modules/sso/index.php/saml/metadata).+  - [[#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     - In the simplest case, paste the metadata URL into the client configuration
     - If the client does not support auto-setup using metadata, manually copy/enter the settings:     - If the client does not support auto-setup using metadata, manually copy/enter the settings:
       - Admidio URLs for Single-sign-on (SSO) and Single-Log-Out (SLO)       - Admidio URLs for Single-sign-on (SSO) and Single-Log-Out (SLO)
       - Public key / certificate of the Admidio IdP.       - Public key / certificate of the Admidio IdP.
-    - Choose a unique client ID to identify the client to Admidio. +    - Choose a unique "Client ID" to identify the client to Admidio. 
-  - [[#c_configuring_admidio_with_the_service_provider|Set up Admidio respond to request from that particular client]]: +  - [[#c_configuring_admidio_with_the_service_provider|Set up Admidio respond to request from that particular client]]:
     - Create a new SAML client in Admidio's SSO client administration ("Preferences" -> "Single-Sign-On" -> "Single-Sign On Client Administration")     - Create a new SAML client in Admidio's SSO client administration ("Preferences" -> "Single-Sign-On" -> "Single-Sign On Client Administration")
     - Ideally, the client ("Service Provider") will provide a link to xml metadata. Paste this URL and let Admidio automatically load the configuration.     - Ideally, the client ("Service Provider") will provide a link to xml metadata. Paste this URL and let Admidio automatically load the configuration.
-    - If not, manually copy/enter the Client ID, theURL where the user should be redirected after login (ACS URL) as well as an optional cryptographic certificate used by the client to sign messages.+    - If not, manually copy/enter the Client ID, the URL where the user should be redirected after login (ACS URL) as well as an optional cryptographic certificate used by the client to sign messages.
   - In many cases, the automatic setup via metadata will work, but it is possible to add further configuration, like profile data submitted or groups/role mapping, or whether messages are signed/encrypted.   - In many cases, the automatic setup via metadata will work, but it is possible to add further configuration, like profile data submitted or groups/role mapping, or whether messages are signed/encrypted.
  
 This page will describe the generic setup of a Admidio and a SAML 2.0 client. It has been tested with several SAML-ready applications, and client-specific instructions are available at separate pages. This page will describe the generic setup of a Admidio and a SAML 2.0 client. It has been tested with several SAML-ready applications, and client-specific instructions are available at separate pages.
- 
  
 ===== Setup overview for OpenID Connect ===== ===== Setup overview for OpenID Connect =====
  
-To set up a third-party web application 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 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: 
-  - [[#a_basic_setup_for_admidio_as_a_oidc_id_provider|General Setup of the OIDC IdP in Admidio]]: +  - [[#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     - Create a cryptographic key for signing/encryption
-    - Choose a unique entityID +    - Choose a unique entityID (typically the URL of the Admidio installation) 
-  - [[#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]/adm_program/modules/sso/index.php/saml/metadata).+  - [[#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).
     - In the simplest case, paste the metadata URL into the client configuration     - In the simplest case, paste the metadata URL into the client configuration
     - If the client does not support auto-setup using metadata, manually copy/enter the settings:     - If the client does not support auto-setup using metadata, manually copy/enter the settings:
-      - Admidio URLs for Single-sign-on (SSO) and Single-Log-Out (SLO)+      - Admidio URLs (endpoints) for authorization, token, userinfo an optionally logout
       - Public key / certificate of the Admidio IdP.       - Public key / certificate of the Admidio IdP.
-    - Choose a unique client ID to identify the client to Admidio. +    - Choose a unique "Client ID" to identify the client to Admidio. 
-  - [[#c_configuring_admidio_with_the_service_provider|Set up Admidio respond to request from that particular client]]:  +    - 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) 
-    - Create a new SAML client in Admidio's SSO client administration ("Preferences" -> "Single-Sign-On" -> "Single-Sign On Client Administration") +    - Optionally a mapping of the OpenID claims (individual data fields) to the client's profile fields 
-    - Ideally, the client ("Service Provider") will provide a link to xml metadata. Paste this URL and let Admidio automatically load the configuration. +  - [[#c_configuring_admidio_with_the_relying_party|Set up Admidio to respond to that particular client (RP)]]:  
-    - If not, manually copy/enter the Client ID, theURL where the user should be redirected after login (ACS URL) as well as an optional cryptographic certificate used by the client to sign messages. +    - Create a new OIDC client in Admidio's SSO client administration ("Preferences" -> "Single-Sign-On" -> "Single-Sign On Client Administration") 
-  - In many cases, the automatic setup via metadata will work, but it is possible to add further configuration, like profile data submitted or groups/role mapping, or whether messages are signed/encrypted.+      - 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) 
 +    - 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!)).
  
-This page will describe the generic setup of a Admidio and a SAML 2.0 client. It has been tested with several SAML-ready applications, and client-specific instructions are available at separate pages.+ 
 +This page will describe the generic setup of a Admidio and an OpenID client. It has been tested with several OpenID-ready applications, and client-specific instructions are available at separate pages
  
  
-^ Client               ^ SAML 2.0         ^ Notes                | 
-^ Nextcloud   |  |  | 
-^ DokuWiki    |  |  | 
-^ Wordpress   |  |  | 
-| Joomla      |  |  | 
-| Drupal      |  |  | 
-| Moodle      |  |  | 
-| MediaWiki   |  |  | 
-| Odoo        |  |  | 
-| Gitlab      |  |  | 
-| Keycloak    |  |  | 
  
  
Line 86: Line 83:
 Step 2 are done by the application in this case, but there is no technical requirement for this. In principle, the decision that a user has successfully logged in can be done by any **trusted** system. This is where single-sign-on hooks in: Rather than each app requesting and processing passwords, step 2 is delegated to a so-called identity provider ("idP"). That identity provider needs to be trusted, and it will take over the part of checking whether a user has access permissions (by e.g. entering a password or using a fingerprint, etc.).  Step 2 are done by the application in this case, but there is no technical requirement for this. In principle, the decision that a user has successfully logged in can be done by any **trusted** system. This is where single-sign-on hooks in: Rather than each app requesting and processing passwords, step 2 is delegated to a so-called identity provider ("idP"). That identity provider needs to be trusted, and it will take over the part of checking whether a user has access permissions (by e.g. entering a password or using a fingerprint, etc.). 
  
-==== Single-Sign-On using an external Identity Provider (IdP) ====+==== Single-Sign-On with SAML 2.0 using an external Identity Provider (IdP) ====
  
 There are two established technical protocols for Single-Sign-On: **SAML 2.0** (XML-based, widely used by large-scale bussiness applications and e.g. Microsoft ADFS) and **OpenID Connect (OIDC)** (JSON-based using "Tokens"; used by many web / social apps like Google, Facebook, etc.). There are two established technical protocols for Single-Sign-On: **SAML 2.0** (XML-based, widely used by large-scale bussiness applications and e.g. Microsoft ADFS) and **OpenID Connect (OIDC)** (JSON-based using "Tokens"; used by many web / social apps like Google, Facebook, etc.).
 +
 +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.
  
 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. 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.
Line 107: Line 106:
   - It is extremely important to ensure that the requests are really sent to the right system and the returned responses really originate from the authorized IdP. This can be assured by using **public key cryptography**, in particular by **signing each request and response** by private keys that ar only known to the SP and IdP, in turn. During initial set up, the corresponding certificates (signed public keys) need to be exchanged, which is the main part of setting up SSO (in addition to providing the URLs of the SP and IdP to each other).   - It is extremely important to ensure that the requests are really sent to the right system and the returned responses really originate from the authorized IdP. This can be assured by using **public key cryptography**, in particular by **signing each request and response** by private keys that ar only known to the SP and IdP, in turn. During initial set up, the corresponding certificates (signed public keys) need to be exchanged, which is the main part of setting up SSO (in addition to providing the URLs of the SP and IdP to each other).
   - The **IdP and the SP never communicate directly**, only through the user's browser! As a consequence, the IdP and the SP can be in separate networks, e.g. the IdP can even be in a private network without access from the internet, as long as the user's browser can connect to it.   - The **IdP and the SP never communicate directly**, only through the user's browser! As a consequence, the IdP and the SP can be in separate networks, e.g. the IdP can even be in a private network without access from the internet, as long as the user's browser can connect to it.
 +
 +==== 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.
 +
 +
 +<WRAP center round todo 60%>
 +todo box
 +</WRAP>
  
  
Line 140: Line 148:
  
 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.  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. 
- 
-Here we show the setup at the examples of: 
-  * [[#d_setting_up_nextcloud_for_single-sign-on|Nextcloud]], 
-  * [[#e_setting_up_dokuwiki_for_single-sign-on|DokuWiki]] and  
-  * [[#f_setting_up_wordpress_for_single-sign-on|WordPress]]. 
  
  
Line 151: Line 154:
 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 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.
  
-  * **Metadata URL** (optional; for automatic setup of clients): https://[YOUR_ADMIDIO_URL]/adm_program/modules/sso/index.php/saml/metadata+  * **Metadata URL** (optional; for automatic setup of clients): https://[YOUR_ADMIDIO_URL]/modules/sso/index.php/saml/metadata
     * 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!     * 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!
   * **IdP SAML Entity ID** (unique identifier of the Admidio instance): https://[YOUR_ADMIDIO_URL]   * **IdP SAML Entity ID** (unique identifier of the Admidio instance): https://[YOUR_ADMIDIO_URL]
-  * **SSO Endpoint** (where the SP sends the login request): https://[YOUR_ADMIDIO_URL]/adm_program/modules/sso/index.php/saml/sso +  * **SSO Endpoint** (where the SP sends the login request): https://[YOUR_ADMIDIO_URL]/modules/sso/index.php/saml/sso 
-  * **SLO Endpoint** (where logout requests are sent to): https://[YOUR_ADMIDIO_URL]/adm_program/modules/sso/index.php/saml/slo+  * **SLO Endpoint** (where logout requests are sent to): https://[YOUR_ADMIDIO_URL]/modules/sso/index.php/saml/slo
   * **x509 Certificate** (to allow clients to verify the cryptographic signatures): PEM-format needs to be copied out of the Admidio preferences   * **x509 Certificate** (to allow clients to verify the cryptographic signatures): PEM-format needs to be copied out of the Admidio preferences
  
Line 163: Line 166:
 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.  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. Below, we will show the configuration at the examples of DokuWiki, Nextcloud and Wordpress.+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. 
 + 
 +[[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_dokuwiki|{{:en:2.0:sso:logos:dokuwiki.png?45&nolink|DokuWiki}}]][[en:2.0:single_sign_on:saml_dokuwiki| DokuWiki]] 
 +[[en:2.0:single_sign_on:saml_wordpress|{{:en:2.0:sso:logos:wordpress-logotype-standard.png?150&nolink|Wordpress}}]] 
 +[[en:2.0:single_sign_on:saml_joomla|{{:en:2.0:sso:logos:joomla.png?120&nolink|Joomla}}]] 
 +[[en:2.0:single_sign_on:saml_mediawiki|{{:en:2.0:sso:logos:mediawiki.svg?120&nolink|MediaWiki}}]] 
 +[[en:2.0:single_sign_on:saml_moodle|{{:en:2.0:sso:logos:moodle.png?150&nolink|Moodle}}]] 
 +[[en:2.0:single_sign_on:saml_gitlab|{{:en:2.0:sso:logos:gitlab.svg?110&nolink|Gitlab}}]] 
 +[[en:2.0:single_sign_on:saml_odoo|{{:en:2.0:sso:logos:odoo_logo.svg?80&nolink|Odoo}}]] 
 +[[en:2.0:single_sign_on:saml_keycloak|{{:en:2.0:sso:logos:keycloak.svg?120&nolink|Keycloak}}]]  
 +[[en:2.0:single_sign_on:simplesamlphp|{{:en:2.0:sso:logos:simplesamlphp.png?140&nolink|SimpleSAMLphp}}]] 
 + 
 ===== C. Configuring Admidio with the Service Provider ===== ===== C. Configuring Admidio with the Service Provider =====
  
-Once the client is set up to send authentication requests to Admidio, Admidio needs to be configured to respond to them. All SAML clients (Service Providers) are configured in the SSO Client Administration page, which can be reached from the SSO Preferences page (https://admidio.demo.open-tools.net/adm_program/modules/preferences.php?panel=sso) from the SSO SAML preferences page.+Once the client is set up to send authentication requests to Admidio, Admidio needs to be configured to respond to them. All SAML clients (Service Providers) are configured in the SSO Client Administration page, which can be reached from the SSO Preferences page (https://admidio.demo.open-tools.net/modules/preferences.php?panel=sso) from the SSO SAML preferences page.
  
 {{ :en:2.0:sso:sso_saml_01-07_clientlist.png?direct&600 |}} {{ :en:2.0:sso:sso_saml_01-07_clientlist.png?direct&600 |}}
Line 172: Line 188:
 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). 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]/adm_program/modules/sso/index.php/saml/metadata +  * **Metadata URL** (for automatic setup of clients):  
-    * 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 |}} +    * If your SP provides a metadata URL, make sure to use it. It will load the correct settings from the SAML SP and set up most settings correctly!{{ :en:2.0:sso:sso_saml_01-08a_clientsetup1_metadata.png?direct&400 |}} 
-  * **IdP SAML Entity ID** (unique identifier of the Admidio instance): https://[YOUR_ADMIDIO_URL] +  * **Client ID** (unique identifier of the Client) 
-  * **SSO Endpoint** (where the SP sends the login request): https://[YOUR_ADMIDIO_URL]/adm_program/modules/sso/index.php/saml/sso +  * **ACS URL** (where responses to login requests are sent to) 
-  * **SLO Endpoint** (where logout requests are sent to): https://[YOUR_ADMIDIO_URL]/adm_program/modules/sso/index.php/saml/slo +  * **Single-Log-Out URL** (optional): Backchannel endpoint to log out from all clients 
-  * **x509 Certificate** (to allow clients to verify the cryptographic signatures): PEM-format needs to be copied out of the Admidio preferences+  * **x509 Certificate** (to allow verification of the messages sent by the SP): PEM-format needs to be copied out from the client
  
-  * **User ID**: 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
   * Further **profile data/fields** transmitted to the client on successful login   * 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.   * 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 188: Line 204:
  
  
-===== Specific Instructions for Individual Client Apps ===== 
  
-|  [[en:2.0:single_sign_on:saml_dokuwiki|{{:en:2.0:sso:logos:dokuwiki.png?75|}}]][[en:2.0:single_sign_on:saml_dokuwiki| DokuWiki]]  |  [[en:2.0:single_sign_on:saml_nextcloud|{{:en:2.0:sso:logos:nextcloud.svg?100|Nextcloud}}]]  |  [[en:2.0:single_sign_on:saml_wordpress|{{:en:2.0:sso:logos:wordpress-logotype-standard.png?150|Wordpress}}]]  | +====== Setting up SSO via OpenID Connect (OIDC) ======
-|  [[en:2.0:single_sign_on:saml_joomla|{{:en:2.0:sso:logos:joomla.png?150|}}]]  |  [[en:2.0:single_sign_on:saml_mediawiki|{{:en:2.0:sso:logos:mediawiki.svg?200|}}]]  |  [[en:2.0:single_sign_on:simplesamlphp +
-|{{:en:2.0:sso:logos:simplesamlphp.png?200|}}]]  |  +
-|  [[en:2.0:single_sign_on:saml_gitlab|{{:en:2.0:sso:logos:gitlab.svg?150|}}]]  |  [[en:2.0:single_sign_on:saml_keycloak|{{:en:2.0:sso:logos:keycloak.svg?200|}}]][[en:2.0:single_sign_on:saml_keycloak|TODO]]  |  [[en:2.0:single_sign_on:saml_odoo|{{:en:2.0:sso:logos:odoo_logo.svg?125|}}]][[en:2.0:single_sign_on:saml_odoo|TODO]]  | +
  
 +===== A. Basic Setup for Admidio as an OpenID Connect ID Provider =====
  
  
-====== Setting up SSO via OpenID Connect (OIDC) ======+Admidio's general SSO configuration is done in the preferences (Tab "Modules", section "Single-Sign-On (SAML 2.0, OpenId Connect)").  
 +{{ :en:2.0:sso:sso_saml_01-01_setup_admidio_preferences.png?direct&400 |}}
  
-<WRAP center round todo 60%> +==== 1. Generating a Cryptographic Key for Signing and Encryption ====
-todo box +
-</WRAP>+
  
 +  * 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. 
 +  * To manage keys, use the "SSO cryptographic Keys Administration" button to switch to the key administration page. 
 +  * {{ :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 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:
 +    * **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:
 +{{ :en:2.0:sso:sso_oidc_01-06_setup_openid_metadata.png?direct&400 |}}
 +
 +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.
 +Also notice that the discovery document lists all allowed scopes and technical details about the internal OpenID settings.
 +
 +Admidio is now **ready to provide single-sign-on functionality to Relying Parties**. 
 +
 +Each RP first needs to be set up with the URLs to connect to Admidio. This can ideally be done by providing the RP with the discovery link. After that, Admidio needs to be configured to accept login requests from the RP. Unfortunately, OpenID Connect does not provide an automatic way to transfer configuration data from the RP to the IdP, so the client ID and the Redirect URL needs to be manually copied from the RP to Admidio's OpenID client settings. The details on where to find these depend on the actual client app. 
 +
 +
 +
 +
 +===== B. Configuring an App (Relying Party) to use SSO with Admidio =====
 +
 +
 +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).
 +
 +  * **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 Isuer** (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): 
 +  * **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. 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.
 +
 +
 +[[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 =====
 +
 +
 +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)
 +
 +  * **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
 +  * **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 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!).
  
 +{{: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|}}
  
  • en/2.0/single_sign_on.1746279129.txt.gz
  • Last modified: 2025/05/03 15:32
  • by kainhofer