Single-Sign-On using OpenId Connect (OIDC) [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 using OpenId Connect (OIDC) ======

<WRAP center round todo 60%>
This page needs to be written. It is currently copied from the SAML documentation to have a basic starting structure. DO NOT FOLLOW THESE INSTRUCTTIONS YET!
</WRAP>

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.

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:
  - [[#a_basic_setup_for_admidio_as_a_saml_id_provider|General Setup of the IdP in Admidio]]: 
    - Create a cryptographic key for signing/encryption
    - Choose a unique entityID
  - [[#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).
    - 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:
      - Admidio URLs for Single-sign-on (SSO) and Single-Log-Out (SLO)
      - Public key / certificate of the Admidio IdP.
    - 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]]: 
    - 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.
    - 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.
  - 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.
^ Client               ^ SAML 2.0         ^ Notes                |
^ Nextcloud   |  |  |
^ DokuWiki    |  |  |
^ Wordpress   |  |  |
| Joomla      |  |  |
| Drupal      |  |  |
| Moodle      |  |  |
| MediaWiki   |  |  |
| Odoo        |  |  |
| Gitlab      |  |  |
| Keycloak    |  |  |



===== How does Single-Sign-On work? =====
==== Traditional Log-In ====

{{ :en:2.0:sso:admidio_saml_loginflows_password.svg?right&400|}}
The default login process to an app (the "Service Provider", i.e. SP) works with the following steps:
  - User clicks on "Log In" 
  - 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.
  - 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.). 

==== Single-Sign-On 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.).

In the SAML case, the login flow above changes to the following. But but from a user perspective, the same steps of entering a password are done, just at a different system. The browser redirects involved in the flow, are hardly noticed by the user and don't require user interaction.

{{ :en:2.0:sso:admidio_saml_loginflows_saml.svg?right&600&direct |}}
  - User clicks on "Log In"
  - The app does not determine user login itself. Instead it relies on a third party (the "Identity Provider", short IdP) to determine whether a user has access:
    - It creates an XML containing an XML "AuthnRequest" and redirects the browser to the IdP (Admidio in our case)
    - If the user is not logged in to Admidio, it shows the login screen
    - Admidio checks the login of the user (and whether the user is member of the permitted groups)
    - 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.
    - 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.
  - 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:
  - All **password handling** and requesting is done **by Admidio alone**. The Service Provider (client app) never receives, asks or has to handle passwords.
  - 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.


===== A. Basic Setup for Admidio as a SAML ID Provider =====

Admidio's SSO configuration is done in the preferences (Tab "Modules", section "Single-Sign-On (SAML 2.0, OpenId Connect)"). 
{{ :en:2.0:sso:sso_saml_01-01_setup_admidio_preferences.png?direct&400 |}}
==== 1. Generating a Cryptographic Key for Signing and Encryption ====

  * The first thing to do is to create a cryptographic key (typically an RSA key with 2048 bit). For this, use the "SSO cryptographic Keys Administration" button to switch to the key administration page. 
  * {{ :en:2.0:sso:sso_saml_01-02_setup_admidio_keyadmin.png?direct&400|}}At the "SSO Cryptographic Keys Administration" page, create a new key (typically RSA with 2048 bits). 
    * Also enter the URL of the Admidio installation as "Common Name". The other required fields (Organisation, OU, city, etc.) must be filled, but their value is not relevant. Make sure that the expiration date is long enough! By default, an expiration of two years is suggested.
{{ :en:2.0:sso:sso_saml_01-03_setup_admidio_newkey.png?direct&400 |}}
  * The key should now be listed and activated. Return  to the "Preferences" for further setup. {{ :en:2.0:sso:sso_saml_01-04_setup_admidio_keys.png?direct&400 |}}
  
==== 2. Configuring Admidio as IdP ====

  * In the SSO section of the preferences, you now need to enable SAML 2.0 Single-Sign-on and configure the following settings:
    * **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
{{ :en:2.0:sso:sso_saml_01-05_setup_admidio_preferences.png?direct&600 |}}

The Preferences page also lists all the relevant data to set up the client as a Service Provider. Particularly useful will be the Metadata URL, which provides all data to set up a client (SP) in XML format. You don't need to do anything, the SSO plugin for Admidio provides this out of the box. Here is an example of such a metadata xml:
{{ :en:2.0:sso:sso_saml_01-06_setup_saml_metadata.png?direct&400 |}}
Notice that it contains both the public key / certificate of the signing and encryption keys, as well as the URLs to the SingleSignOnService (SSO) and the SingleLogOutService (SLO) at the admidio installation. Furthermore, the first half of the XML contains the cryptographic signature of the XML, signed with the private key to prove that the metadata file actually comes from the admidio installation and not from some adversary.


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:
  * [[#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]].


===== B. Configuring an App (Service Provider) to use SSO with Admidio =====

Once Admidio is set up to act as a SAML 2.0 IdP, the clients (Service Providers, "SP") can be configured to use Admidio as their login provider. Many systems either support SAML 2.0 out of the box or with some plugin. The following settings are needed for setup. They are also available for copying at Admidio's SSO preferences page, as well as in the metadata xml.

  * **Metadata URL** (optional; for automatic setup of clients): https://[YOUR_ADMIDIO_URL]/adm_program/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!
  * **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
  * **SLO Endpoint** (where logout requests are sent to): https://[YOUR_ADMIDIO_URL]/adm_program/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

  * **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.
===== 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.

{{ :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, 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
    * 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 |}}
  * **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
  * **SLO Endpoint** (where logout requests are sent to): https://[YOUR_ADMIDIO_URL]/adm_program/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

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

{{:en:2.0:sso:sso_saml_01-08_clientsetup1.png?direct&300|}}{{:en:2.0:sso:sso_saml_01-09_clientsetup2.png?direct&300|}}{{:en:2.0:sso:sso_saml_01-10_clientsetup3.png?direct&300|}}


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