Single-Sign-On into Nextcloud using Admidio as a SAML 2.0 Identity Provider [Admidio-Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Single-Sign-On into Nextcloud using Admidio as a SAML 2.0 Identity Provider ======

Starting with version 5.0, Admidio can be used by other applications to authenticate users against Admidios user base. These instructions will guide you through the process of connecting Nextcloud to Admidio to use Admidio's login. For general instructions, and other apps, please visit the [[en:2.0:single_sign_on|general Single-Sign-On overview page]].

The SAML Login functionality of Nextcloud is provided by the [[https://apps.nextcloud.com/apps/user_saml|SSO & SAML authentication]] extension.

===== Prerequisites =====

Throughout the document we will assume you have both Admidio and Nextcloud already set up properly at https://admidio.local/ and https://nextcloud.local/. Please modify these URLs to your actual installation.
 
As a first step, one needs to **configure Admidio to act as an SAML 2.0 Identity Provider** (IdP). This has to be done once and is not specific to Nextcloud. Please follow this guide: [[en:2.0:single_sign_on|#a_basic_setup_for_admidio_as_a_saml_id_provider]]
{{ :en:2.0:sso:sso_saml_01-05_setup_admidio_preferences.png?direct&600 |}}

Basically, one (1) needs to **create a cryptographic key** to sign message and **choose a unique EntityID**.
The page https://admidio.local/adm_program/modules/preferences.php?panel=sso also provides the link to the metadata xml, and the individual settings in case a client does not support auto-configuration via metadata.

===== TL;DR; - Quick Overview =====

Setting up a client (SAML "Service Provider" - short SP) to use Admidio's user accounts for logging in consists of two steps. If both the IdP (Admidio in our case) and the SP (Nextcloud in this document) support metadata loading, the setup is very straightforward and easy. Otherwise, one has to copy URLs manually to the client, but Admidio already provides these in a single place, so this situation is not as bad, either.

  * At the **Service Provider (SP)** - Nextcloud in our case - **install the extension** to support SAML login.
  * Configure it either with Admidio's link to the **metadata file**, or enter the EntityID, the Single-Sign-On Endpoint, the SLO Endpoint and the public certificate manually (Admidio provides a simple table to copy these values from).
  * Choose whether sent messages **should be signed and/or encrypted** (these features require an additional private key and certificate for the SP!), and whether received messages are checked for signatures or encryption is expected. 
  * In **Admidio**, **create a new SAML client**. If the SP provides a **metadata URL**, paste it and let Admidio automatically load the configuration from the SP. One can also manually paste these settings.
    * Choose an easily understood **label for the client** (only used in Admidio's list of clients, but has no technical use)
    * Enter the **ClientID from the SP**, as well as the ACS URL and the SLO response URL. These values must be provided by the client.
  * In Admidio, also choose whether sent messages should be **signed or encrypted**. The crypto key generated in the general SAML setup will be used.
  * Optionally select which **profile fields should be mapped** to SAML attributes and sent to the client, and configure which **group memberships** should be transmitted.

===== Nextcloud-specific instructions =====

==== 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, by tools like https://www.samltool.com/self_signed_certs.php, 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&900 |}}


The Nextclout SAML configuration also provides settings to choose whether its requests sent to admidio should be signed (a crypto key needs to be set as described above!), and whether all received responses and asserts are expected to be signed or encrypted. You can choose the security level that you desire, but you need to make sure that the settings in Admidio and Nextcloud are consistent, otherwise login will not be possible (e.g. if Wordpress is configured to require signatures on all asserts and responses received, while Admidio is configured not to sign them).

{{ :en:2.0:sso:sso_saml_02-07_nc_admidio_clientsetup3.png?direct&900 |}}


==== 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|}}



==== Caveats and Things to Consider ====

  * For security reasons, Nextcloud will prepend **SAML_ prefix to the group names** obtained from the SAML IdP. This makes hybrid environments quite hard in practice, where some users authenticate via SAML, others via local accounts or other network accounts. In these hybrid cases, the SAML-generated groups will be different than the local groups and all group permissions need to be set twice! As a **workaround**, one can **enter a single space into the prefix input box**. This will cause Nextcloud's SAML extension to clear the prefix, but the input field will appear empty in the future, so it is not clarly visible whether the prefix was "cleared" or the default prefix will be applied!