Single-Sign-On using SAML 2.0

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.

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.

To set up Admidio as a SAML 2.0 Identity Provider (so that other applications can use the Admidio user base for their logins), one has to take three steps:

1. General Setup of the IdP in Admidio (create a cryptographic key, an ID, etc.)
2. Configuration of the client app (Service Provider): enter the Admidio URLs for Single-sign-on (SSO) and Single-Log-Out (SLO), as well as the public key / certificate of the Admidio IdP. Some clients even support downloading the metadata xml directly from Admidio for almost automatic setup.
3. Set up Admidio respond to reqruest from that particular client, too. This involves configuring the ID (typically the URL) of the client, the script URL where the user should be redirected after login, as well as the cryptographic certificate to sign/encrypt messages. For most clients, these data can be downloaded automatically through xml metadata.

The default login process to an app (the “Service Provider”, i.e. SP) works with the following steps:

1. User clicks on “Log In”
2. The app determines whether the user has access: It displays a login form, checks the entered Username and Password (hash), and if they exist and match, makes the decision to grant access.
3. the app now knows that the user has successfully logged in and creates an appropriate session to keep the user logged in.

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.).

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.).

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.

1. User clicks on “Log In”
2. 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:
   1. It creates an XML containing an XML “AuthnRequest” and redirects the browser to the IdP (Admidio in our case)
   2. If the user is not logged in to Admidio, it shows the login screen
   3. Admidio checks the login of the user (and whether the user is member of the permitted groups)
   4. If login is successful (or the user was already logged in), access should be granted. This is documented in XML data (the “Assertion”; cryptographically signed to prevent man-in-the-middle attacks) and sent back to the Service provider by a browser redirect.
   5. In addition to the username, the Assertion returned to the SP can also contain further user information (email, first/last name, etc.) and groups/roles.
3. The client app (Service Provider) now knows that the user has successfully logged in to Admidio and creates an appropriate session to keep the user logged in.

There are some things to notice about the way SAML authentication works:

1. All password handling and requesting is done by Admidio alone. The Service Provider (client app) never receives, asks or has to handle passwords.
2. 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).
3. 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.

Admidio's SSO configuration is done in the preferences (Tab “Modules”, section “Single-Sign-On (SAML 2.0, OpenId Connect)”).

• 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.
• 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.

• The key should now be listed and activated. Return to the “Preferences” for further setup.

• In the SSO section of the preferences, you now need to enable SAML 2.0 Single-Sign-on and configure the following settings:
  • SAML Entity ID: The URL of your installation (needs to be a unique ID, the URL is usually used, but not required)
  • 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
  • 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

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: 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.

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.

Here we show the setup at the examples of:

• Nextcloud,
• DokuWiki and
• WordPress.

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_plugins/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!
• 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_plugins/sso/index.php/saml/sso
• SLO Endpoint (where logout requests are sent to): https://[YOUR_ADMIDIO_URL]/adm_plugins/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

• 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!). 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.

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.

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_plugins/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!
• 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_plugins/sso/index.php/saml/sso
• SLO Endpoint (where logout requests are sent to): https://[YOUR_ADMIDIO_URL]/adm_plugins/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

• User ID: 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
• 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.

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!).

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 (create a cryptographic key, an ID, etc.).

SAML 2.0 login in Nextcloud is provided by the app “SSO & SAML authentication”.

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).

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:

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”).

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:

After downloading the .p12 file, Applications like 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.

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.

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.

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”.

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.

After choosing SAML login and loggin in with a user from Admidio, you should be logged in to Nextcloud.

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 (create a cryptographic key, an ID, etc.).

SAML 2.0 login in Nextcloud is provided by the “SAML Plugin” extension.

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.

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:

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.

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.

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.

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).

TODO: Describe signing and encryption settings (synced)

Once all settings are done, it is time to enable the saml plugin for login to DokuWiki in the “Configuration Settings”:

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.

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.

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_plugins/sso/index.php/saml/sso",
      "idp_slo_service_url" => "https://admidio.demo.open-tools.net/adm_plugins/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'
    }
  }
]

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

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.

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.

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).

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.