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/04/24 08:53] – kainhoferen:2.0:single_sign_on [2025/04/29 01:56] (current) – kainhofer
Line 2: Line 2:
  
 Starting with version 5.0, Admidio can be used by other applications to authenticate users against Admidios user base. Other applications can use Admidio's user database to log in users into the app. 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. Other applications can use Admidio's user database to log in users into the app. 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.
 +
 +Many widely used applications support SAML. We will describe the configuration in general 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|}}]] 
 +
 +[[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:simplesamlphp.png?200|}}]]
 +</WRAP>
 +
 +Other systems like Prestashop do not provide any freely available SAML plugin. 
 +
  
 All examples here use the domain https://admidio.demo.open-tools.net/ as Admidio domain and https://[appname].demo.open-tools.net/ for the client applications. All examples here use the domain https://admidio.demo.open-tools.net/ as Admidio domain and https://[appname].demo.open-tools.net/ for the client applications.
Line 22: Line 36:
  
 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.
-|----------------------|------------------|----------------------| +^ Client               ^ SAML 2.0         ^ Notes                | 
-| Client               | SAML 2.0         | Notes                | +^ Nextcloud   |  |  | 
-|----------------------|------------------|----------------------| +^ DokuWiki    |  |  | 
-| Nextcloud   |  |  | +^ Wordpress   |  |  |
-| DokuWiki    |  |  | +
-| Wordpress   |  |  |+
 | Joomla      |  |  | | Joomla      |  |  |
 | Drupal      |  |  | | Drupal      |  |  |
Line 150: Line 162:
  
  
-===== D. Setting up Nextcloud for Single-Sign-On ===== +===== Specific Instructions for Individual Client Apps =====
-Here we describe, how Nextcloud can be configured to use Admidio's login to authenticate users. It is assumed that Admidio is already configured to act as an IdP, as described in section [[#a_basic_setup_for_admidio_as_a_saml_id_provider|"A. Basic setup for Admidio as a SAML id Provider]] (create a cryptographic key, an ID, etc.). +
- +
-==== Configuring the Service Provider (Nextcloud) ==== +
- +
-SAML 2.0 login in Nextcloud is provided by the app "SSO & SAML authentication". +
-{{ :en:2.0:sso:sso_saml_02-01_nc_install_saml_app.png?direct&600 |}} +
- +
-After installation it can be configured in Nextcloud's "Administration settings" in the section "SSO & SAML authentication". First, one needs to choose the built-in SAML authentication (one-time setting after first installation). +
-{{ :en:2.0:sso:sso_saml_02-02_nc_saml_setup1.png?direct&600 |}} +
- +
-Nextcloud does not support automatic configuration from IdP metadata, so one has to copy the correct settings over from the Admidio preferences. It is a good idea to keep two browser windows open so one can easily select and copy the settings. Admidio even provides little "copy" buttons/icons to copy the various settings to the clipboard for easy pasting into Nextcloud's configuration. +
- +
-This is a typical configuration of the Nextcloud SAML plugin for Admidio as an idP: +
-{{ :en:2.0:sso:sso_saml_02-03_nc_saml_setup2.png?direct&600 |}} +
- +
-Once these basic SAML settings are done, I would recommend to set up the SP in Admidio, and do the remaining settings (transmitted fields and roles, as well as signing/encryption requirements) in parallel in Nextcloud and Admidio.  +
- +
-If the basic settings are valid, Nextcloud should indicate "Metadata valid" at the bottom of the page next to a button to download the metadata XML. Copy the URL of the metadata XML button (right-click on the "Download metadata XML" button and choose "copy link address"). +
-{{ :en:2.0:sso:sso_saml_02-04_nc_saml_metadata_link.png?direct&400 |}} +
- +
-=== Setting up encryption === +
- +
-If encryption is desired for all SAML messages sent by Admidio to Nextcloud, or if Nextcloud should sign all its requests, then Nextcloud needs a private/public key pair to decrypt or sign messages. These need to be entered into the Nextcloud SAML config in PEM format and can be generated by openssl's command line tools, or in Admidio's key administration. Simply create a new Key for Nextcloud (RSA 2048 bits). The certificate can be copied directly from the key's edit page, but the private key is not available in Admidio's GUI for security reason. Instead, it can be downloaded (secured with a password!) from the list of keys in Admidio: +
- +
-{{ :en:2.0:sso:sso_saml_02-03a_nc_saml_keysetup1.png?direct&400 |}} +
- +
-After downloading the .p12 file, Applications like [[https://keystore-explorer.org/|KeyStore Explorer]] can be used to read the private key and copy the private key and the certificate in PEM format to the clipboard and paste it into Nextcloud's SAML configuration. +
- +
-{{:en:2.0:sso:sso_saml_02-03b_nc_saml_keystoreexplorer1.png?direct&400|}}{{:en:2.0:sso:sso_saml_02-03c_nc_saml_keystoreexplorer2.png?direct&400|}} +
- +
-{{ :en:2.0:sso:sso_saml_02-03d_nc_saml_keyconfig.png?direct&400 |}} +
-==== Setting up the Client (SP) in Admidio ==== +
- +
-Now, return to Admidio's SSO preferences page, go to the "Single-Sign-On Client Administration" (the button right above the "Save" button), and create a new client. +
-{{ :en:2.0:sso:sso_saml_03-00_admidio_saml_preferences.png?direct&400 |}} +
- +
- +
-Paste the metadata URL copied from Nextcloud into the corresponding input field at the top and click "Load Client Metadata". This should load all settings from Nextcloud and pre-fill the following fields correctly. Only the Client Name needs to be entered. Choose any name to clearly identify the client in the list of SAML clients. There is no functionality depending on the name. +
-{{ :en:2.0:sso:sso_saml_02-05_nc_admidio_clientsetup1.png?direct&600 |}} +
- +
- +
-In addition to the Entity ID and URLs to connect SP and IdP and the certificate, which are configured automatically, one also needs to define the attribute and role mapping. The username is the most relevant. To use Admidio's group memberships as Nextcloud groups, make sure to include the "Roles" field and provide the correct field name in Nextcloud. Internally, Nextcloud will add a prefix to the role names, which makes it impossible to assign admin rights to SAML groups (Nextcloud uses the group with internal name "admin" for administrators). If you want to assign admin rights through SAML, too, then you must enter a single space into the prefix field. This causes Nextcloud to take the role names verbatim as Nextcloud group names, including "admin". +
- +
-{{ :en:2.0:sso:sso_saml_02-06_nc_admidio_clientsetup1.png?direct&600 |}} +
- +
-<WRAP center round todo 60%> +
-TODO: Describe signing and encryption settings (synced) +
-</WRAP> +
-{{ :en:2.0:sso:sso_saml_02-07_nc_admidio_clientsetup3.png?direct&600 |}} +
- +
- +
-==== Setup completed, test Single-Sign-On ==== +
-Admidio and Nextcloud should now be set up to use Admidio for logging in to Nextcloud. If you log out of Nextcloud, you should see the login screen with the choice of logging in with password or via SAML. +
-{{ :en:2.0:sso:sso_saml_02-08_nc_saml_login.png?direct&400 |}} +
- +
-After choosing SAML login and loggin in with a user from Admidio, you should be logged in to Nextcloud. +
-{{:en:2.0:sso:sso_saml_02-09_nc_saml_loggedin.png?direct&200|}} +
-{{:en:2.0:sso:sso_saml_02-10_nc_saml_users.png?direct&600|}} +
- +
- +
- +
-===== E. Setting up DokuWiki for Single-Sign-On ===== +
- +
-Here we describe, how DokuWiki can be configured to use Admidio's login to authenticate users. It is assumed that Admidio is already configured to act as an IdP, as described in section [[#a_basic_setup_for_admidio_as_a_saml_id_provider|"A. Basic setup for Admidio as a SAML id Provider]] (create a cryptographic key, an ID, etc.). +
- +
-==== Configuring the Service Provider (DokuWiki) ==== +
- +
-SAML 2.0 login in Nextcloud is provided by the "SAML Plugin" extension. +
-{{ :en:2.0:sso:sso_saml_04-01_dw_saml_plugin_install.png?direct&600 |}} +
- +
-After installation it can be configured in DokuWiki's Configuration Settings, near the bottom in the "Saml" section. The extension also provides a configuration helper, that reads the metadata from Admidio, but that is not neccessary, as we will directly copy over the settings from Admidio. +
-{{ :en:2.0:sso:sso_saml_04-02_dw_saml_admin.png?direct&400 |}} +
- +
-It is a good idea to keep two browser windows open so one can easily select and copy the settings. Admidio even provides little "copy" buttons/icons to copy the various settings to the clipboard for easy pasting into DokuWiki's configuration. +
- +
-This is a typical configuration of the DokuWiki SAML extension for Admidio as an idP: +
-{{ :en:2.0:sso:sso_saml_04-04_dw_saml_settings.png?direct&600 |}} +
- +
-Once these basic SAML settings are done, I would recommend to set up the SP in Admidio, and do the remaining settings (transmitted fields and roles, as well as signing/encryption requirements) in parallel in Dokuwiki and Admidio.  +
- +
- +
-==== Setting up the Client (SP) in Admidio ==== +
- +
-Now, return to Admidio's SSO preferences page, go to the "Single-Sign-On Client Administration" (the button right above the "Save" button), and create a new client. +
-{{ :en:2.0:sso:sso_saml_03-00_admidio_saml_preferences.png?direct&400 |}} +
- +
-DokuWiki provides its SAML SP client settings as a metadata XML. Unfortunately, there is no direct link to copy the URL from, but the URL is easy to construct: +
-     +
-    https://[URL_TO_YOUR_DOKUWIKI]/doku.php?do=saml +
-     +
-Paste that metadata URL into the corresponding input field at the top and click "Load Client Metadata". This should load all settings from Dokuwiki and pre-fill the following fields correctly. Only the Client Name needs to be entered. Choose any name to clearly identify the client in the list of SAML clients. There is no functionality depending on the name. +
- +
-{{ :en:2.0:sso:sso_saml_04-05_dw_admidio_clientsetup1.png?direct&400 |}} +
- +
-In addition to the Entity ID and URLs to connect SP and IdP and the certificate, which are configured automatically, one also needs to define the attribute and role mapping. The username is the most relevant. To use Admidio's group memberships as Dokuwiki groups, make sure to include the "Roles" field and provide the correct field name in Dokuwiki.  +
- +
-Make sure to use the same SAML field names as the ones mapped in Dokuwiki's Saml configuration (circled red in the configuration screenshot above). +
- +
-{{ :en:2.0:sso:sso_saml_04-06_dw_admidio_clientsetup2.png?direct&400 |}} +
- +
- +
-TODO: Describe signing and encryption settings (synced) +
-{{ :en:2.0:sso:sso_saml_02-07_nc_admidio_clientsetup3.png?direct&600 |}} +
- +
-Once all settings are done, it is time to enable the saml plugin for login to DokuWiki in the "Configuration Settings":  +
-{{ :en:2.0:sso:sso_saml_04-07_dw_saml_enable.png?direct&400 |}} +
- +
- +
-==== Setup completed, test Single-Sign-On ==== +
- +
-Admidio and DokuWiki should now be set up to use Admidio for logging in to Dokuwiki. If you log out of DokuWiki and try to log in again, you will be shown the Admidio login screen and then redirected back to Dokuwiki. +
-{{ :en:2.0:sso:sso_saml_04-08_dw_saml_login.png?direct&400 |}} +
-{{ :en:2.0:sso:sso_saml_04-09_dw_admidio_login.png?direct&400 |}} +
-{{ :en:2.0:sso:sso_saml_04-10_dw_login_success.png?direct&400 |}} +
-{{ :en:2.0:sso:sso_saml_04-11_dw_login_success_groups.png?direct&400 |}} +
- +
- +
- +
-==== Caveats and Things to Consider ==== +
- +
-  * Dokuwiki is picky about signatures. If a SAML response is not signed, login will not be possible, but no corresponding error message will be shown. After an apparent login, the user will arrive at dokuwiki with no user logged in (actually, DokuWiki even silently triggers a logout!). Make sure that in Admidio's client setting for the Dokuwiki SAML client the checkbox "Sign assertions sent to the client (SP)" is checked! +
-===== F. Setting up Wordpress for Single-Sign-On ===== +
- +
-<WRAP center round todo 60%> +
-TODO +
-</WRAP> +
- +
-==== Configuring the Service Provider (Wordpress) ==== +
- +
-==== Setting up the Client (SP) in Admidio ==== +
- +
- +
- +
-===== G. Setting up a local Gitlab for Single-Sign-On ===== +
- +
-==== Configuring the Service Provider (Gitlab) ==== +
- +
-Gitlab does not provide a graphic config interface to set up SAML. However, it is easy to set up SAML in the config file (gitlab.rb) as described in https://docs.gitlab.com/17.10/integration/saml/.  +
- +
-An example would be as follows. The URLs and the certificate can again be copied from Admidios SSO preferences page. +
-<code> +
-gitlab_rails['omniauth_enabled'] = true +
-gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'gitlab'] +
-gitlab_rails['omniauth_block_auto_created_users'] = false  +
-gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml' # don't show gitlabs login screen at all +
-gitlab_rails['omniauth_auto_link_saml_user'] = true +
-gitlab_rails['omniauth_providers'] = [ +
-  { "name" => "gitlab", ...}, +
-  { +
-    "name" => "saml", +
-    "label" => "Admidio SAML SSO", +
-    "groups_attribute" => "groups", +
-    "admin_groups" => ["admin"], +
-    "args" => { +
-      "assertion_consumer_service_url" => "https://gitlab.open-tools.net/users/auth/saml/callback", +
-      "sp_entity_id" => "https://gitlab.open-tools.net", +
-      "idp_cert" => "-----BEGIN CERTIFICATE----- +
-... +
------END CERTIFICATE-----", +
-      "idp_sso_service_url" => "https://admidio.demo.open-tools.net/adm_program/modules/sso/index.php/saml/sso", +
-      "idp_slo_service_url" => "https://admidio.demo.open-tools.net/adm_program/modules/sso/index.php/saml/slo", +
-      "issuer" => "https://gitlab.open-tools.net", +
-      "attribute_statements" => { "email" => ['email'], "nickname" => ['username'] }, +
-      "name_identifier_format" => "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", +
-      "uid_attribute" => 'username' +
-    } +
-  } +
-] +
-</code> +
- +
-Gitlab also supports encryption, which needs its own public + private key pair configured in gitlab. To generate keys, one can use Admidio's key administration (RSA 2048 key), export the Key (saved as PKCS#12 with file extension .p12 and a password) and then open the key file in any application that handles PKCS#12 Key and copy the private key and the public certificate in PEM format into the gitlab.rb file. The corresponding config keys are documented in the gitlab documentation mentioned above. +
- +
-After editing gitlab.rb, one needs to reconfigure gitlab by running: +
- +
-  sudo gitlab-ctl reconfigure +
- +
-Gitlab will provide the SP metadata as an XML at the URL +
- +
-  https://[GITLAB_SERVER_URL]/users/auth/saml/metadata +
-  +
- +
-==== Setting up the Client (SP) in Admidio ==== +
- +
-Now, return to Admidio's SSO preferences page, go to the "Single-Sign-On Client Administration" (the button right above the "Save" button), and create a new client. +
-{{ :en:2.0:sso:sso_saml_03-00_admidio_saml_preferences.png?direct&400 |}} +
- +
-Gitlab provides its SAML SP client settings as a metadata XML at the URL +
- +
-  https://[GITLAB_SERVER_URL]/users/auth/saml/metadata +
-      +
-Paste that metadata URL into the corresponding input field at the top and click "Load Client Metadata". This should load all settings from Gitlab and pre-fill the following fields correctly. Only the Client Name needs to be entered. Choose any name to clearly identify the client in the list of SAML clients. There is no functionality depending on the name. +
- +
-{{ :en:2.0:sso:sso_saml_05-01_gitlab_saml_idp1.png?direct&400 |}} +
- +
-In addition to the Entity ID and URLs to connect SP and IdP and the certificate, which are configured automatically, one also needs to define the attribute and role mapping. The username is the most relevant and must match the uid_attribute configured in gitlab.rb. To use Admidio's group memberships as Gitlab groups, make sure to include the "Roles" field and provide the correct field name in Dokuwiki. Unfortunately, it seems that this features is only available in Gitlab EE (Enterprise Edition). +
- +
-{{ :en:2.0:sso:sso_saml_05-02_gitlab_saml_idp2.png?direct&400 |}}+
  
 +|  [[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: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]]  | 
  
-==== Setup completed, test Single-Sign-On ==== 
  
-Admidio and Gitlab should now be set up to use Admidio for logging in to Gitlab. If you log out of Gitlab and try to log in again, you will be shown the Admidio login screen and then redirected back to Gitlab after successful login. 
  
-{{:en:2.0:sso:sso_saml_05-03_gitlab_login_selection.png?direct&200|}} 
-{{:en:2.0:sso:sso_saml_05-03a_gitlab_login_admidio.png?direct&300|}} 
-{{:en:2.0:sso:sso_saml_05-04_gitlab_saml_loggedin.png?direct&200|}} 
  
  
  • en/2.0/single_sign_on.1745477618.txt.gz
  • Last modified: 2025/04/24 08:53
  • by kainhofer