Single-Sign-On mit Admidio-Benutzerkonten: SAML 2.0 und OpenID Connect [Admidio-Wiki]

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
FIXME **Diese Seite wurde noch nicht vollständig übersetzt. Bitte helfen Sie bei der Übersetzung.**\\ //(diesen Absatz entfernen, wenn die Übersetzung abgeschlossen wurde)//

====== Single-Sign-On mit Admidio-Benutzerkonten: SAML 2.0 und OpenID Connect ======


Ab Version 5.0 kann Admidio von anderen Anwendungen genutzt werden, um Benutzer per Single-Sign-On (SSO) anhand der Admidio-Benutzerdatenbank zu authentifizieren. Wenn ein Login in der Anwendung initiiert wird, wird der Benutzer zum Login zu Admidio weitergeleitet und nach erfolgreicher Authentifizierung zurück zur Client-Anwendung geleitet und dort angemeldet. Der Benutzer muss sich nur bei Admidio anmelden und erhält automatisch Zugang zu anderen (konfigurierten) Anwendungen. Die anderen Anwendungen müssen keine Passwörter speichern oder verarbeiten.

Die beiden dominierenden Protokolle sind das XML-basierte SAML 2.0(([https://wiki.oasis-open.org/security/FrontPage](https://wiki.oasis-open.org/security/FrontPage))) und das JSON-basierte OpenID Connect (OIDC)(([https://openid.net/developers/specs/](https://openid.net/developers/specs/))). Admidio kann für beide Protokolle als Identity Provider (IdP) fungieren. Wir werden die Konfiguration im Allgemeinen für beide Protokolle für die folgenden Systeme beschreiben:

^ Client ^ SAML 2.0 ^ OpenID Connect ^ Anmerkungen |
^ {{:en:2.0:sso:logos:nextcloud.svg?40&nolink|Nextcloud}} Nextcloud | [[en:2.0:single_sign_on:saml_nextcloud|SAML 2.0 mit Nextcloud]] | [[en:2.0:single_sign_on:oidc_nextcloud|OpenID mit Nextcloud]] | |
^ {{:en:2.0:sso:logos:dokuwiki.png?40&nolink|DokuWiki}} DokuWiki | [[en:2.0:single_sign_on:saml_dokuwiki|SAML 2.0 mit DokuWiki]] | [[en:2.0:single_sign_on:oidc_dokuwiki|OpenID mit DokuWiki]] | |
^ {{:en:2.0:sso:logos:wordpress-logotype-standard.png?120&nolink|Wordpress}} | [[en:2.0:single_sign_on:saml_wordpress|SAML 2.0 mit Wordpress]] | [[en:2.0:single_sign_on:oidc_wordpress|OpenID mit Wordpress]] | |
^ {{:en:2.0:sso:logos:joomla.png?120&nolink|Joomla}} | [[en:2.0:single_sign_on:saml_joomla|SAML 2.0 mit Joomla]] | [[en:2.0:single_sign_on:oidc_joomla|OpenID mit Joomla]] | |
^ {{:en:2.0:sso:logos:mediawiki.svg?120&nolink|MediaWiki}} | [[en:2.0:single_sign_on:saml_mediawiki|SAML 2.0 mit MediaWiki]] | [[en:2.0:single_sign_on:oidc_mediawiki|OpenID mit MediaWiki]] | |
^ {{:en:2.0:sso:logos:moodle.png?90&nolink|Moodle}} | [[en:2.0:single_sign_on:saml_moodle|SAML 2.0 mit Moodle]] | [[en:2.0:single_sign_on:oidc_moodle|OpenID mit Moodle]] | |
^ {{:en:2.0:sso:logos:gitlab.svg?100&nolink|Gitlab}} | [[en:2.0:single_sign_on:saml_gitlab|SAML 2.0 mit Gitlab]] | [[en:2.0:single_sign_on:oidc_gitlab|OpenID mit Gitlab]] | |
^ {{:en:2.0:sso:logos:odoo_logo.svg?60&nolink|Odoo}} | [[en:2.0:single_sign_on:saml_odoo|SAML 2.0 mit Odoo]] | [[en:2.0:single_sign_on:oidc_odoo|OpenID mit Odoo]] | |
^ {{:en:2.0:sso:logos:keycloak.svg?120&nolink|Keycloak}} | [[en:2.0:single_sign_on:saml_keycloak|SAML 2.0 mit Keycloak]] | [[en:2.0:single_sign_on:oidc_keycloak|OpenID mit Keycloak]] | |
^ {{:en:2.0:sso:logos:simplesamlphp.png?140&nolink|SimpleSAMLphp}} | [[en:2.0:single_sign_on:simplesamlphp|SAML 2.0 mit SimpleSAMLphp]] | | |
^ {{:en:2.0:sso:logos:matomo_logo.svg?120&nolink|Matomo}} | | [[en:2.0:single_sign_on:oidc_matomo|OpenID mit Matomo]] | |
^ {{:en:2.0:sso:logos:gnu_mailman_logo2010.png?120&nolink|Mailman3}} | | [[en:2.0:single_sign_on:oidc_mailman3|OpenID mit Mailman3]] | |
^ {{:en:2.0:sso:logos:plesk_logo_primary_positive_.jpg?60&nolink|Plesk}} | | [[en:2.0:single_sign_on:oidc_plesk|OpenID mit Plesk]] | |

Andere Systeme wie Prestashop bieten keine frei verfügbaren SAML- oder OpenID-Plugins an, nur einige sehr teure kommerzielle Erweiterungen.

Alle Beispiele hier verwenden die Domain https://admidio.demo.open-tools.net/ oder https://admidio.local als Admidio-Domain und https://[appname].demo.open-tools.net/ oder https://[appname].local für die Client-Anwendungen.


===== Einrichtungsübersicht für SAML 2.0 =====


Um eine Webanwendung eines Drittanbieters so einzurichten, dass sie Single-Sign-On über Admidio als SAML 2.0 Identity Provider verwendet (damit andere Anwendungen die Benutzerkonten von Admidio für ihre Logins nutzen), sind drei Schritte erforderlich:

  - [[#Eine grundlegende Einrichtung für Admidio als SAML-IdP|Allgemeine Einrichtung des IdP in Admidio]]:
      - Erstellen eines kryptografischen Schlüssels zum Signieren/Verschlüsseln
      - Auswahl einer eindeutigen entityID (typischerweise die URL der Admidio-Installation)
  - [[#Konfiguration einer Anwendung (Service Provider) zur Nutzung von SSO mit Admidio|Konfiguration der Client-App (Service Provider)]]: Admidio stellt einen Link mit allen erforderlichen Metadaten zur Verfügung, die Clients verwenden können (https://[ADMIDIO-URL]/modules/sso/index.php/saml/metadata).
      - Im einfachsten Fall die Metadaten-URL in die Client-Konfiguration einfügen
      - Wenn der Client die automatische Einrichtung mittels Metadaten nicht unterstützt, die Einstellungen manuell kopieren/eingeben:
          - Admidio URLs für Single-Sign-On (SSO) und Single-Log-Out (SLO)
          - Öffentlicher Schlüssel / Zertifikat des Admidio IdP.
      - Wählen Sie eine eindeutige "Client ID", um den Client gegenüber Admidio zu identifizieren.
  - [[#Konfiguration von Admidio mit dem Service Provider|Admidio so einrichten, dass es auf Anfragen dieses speziellen Clients reagiert]]:
      - Erstellen eines neuen SAML-Clients in der SSO-Client-Administration von Admidio ("Einstellungen" -> "Single-Sign-On" -> "Single-Sign-On Client Administration")
      - Idealerweise stellt der Client ("Service Provider") einen Link zu XML-Metadaten bereit. Diese URL einfügen und Admidio die Konfiguration automatisch laden lassen.
      - Andernfalls die Client-ID, die URL, zu der der Benutzer nach dem Login umgeleitet werden soll (ACS-URL), sowie ein optionales kryptografisches Zertifikat, das vom Client zum Signieren von Nachrichten verwendet wird, manuell kopieren/eingeben.
  - In vielen Fällen funktioniert die automatische Einrichtung über Metadaten, aber es ist möglich, weitere Konfigurationen hinzuzufügen, wie z.B. übermittelte Profildaten oder Gruppen-/Rollen-Mapping, oder ob Nachrichten signiert/verschlüsselt werden.

Diese Seite beschreibt die generische Einrichtung eines Admidio- und eines SAML 2.0-Clients. Sie wurde mit mehreren SAML-fähigen Anwendungen getestet, und clientspezifische Anweisungen sind auf separaten Seiten verfügbar.


==== Einrichtungsübersicht für OpenID Connect ====


Um eine Webanwendung eines Drittanbieters (die "Relying Party", kurz RP) so einzurichten, dass sie Single-Sign-On über Admidio als OpenID Connect Identity Provider verwendet (damit andere Anwendungen die Benutzerkonten von Admidio für ihre Logins nutzen), sind drei Schritte erforderlich:

  - [[#Eine grundlegende Einrichtung für Admidio als OpenID Connect IdP|Allgemeine Einrichtung des OIDC IdP in Admidio]]:
      - Erstellen eines kryptografischen Schlüssels zum Signieren/Verschlüsseln
      - Auswahl einer eindeutigen entityID (typischerweise die URL der Admidio-Installation)
  - [[#Konfiguration einer Anwendung (Relying Party) zur Nutzung von SSO mit Admidio|Konfiguration der Client-App (Relying Party)]]: Admidio stellt einen Link mit allen erforderlichen Metadaten zur Verfügung, die Clients verwenden können (https://[ADMIDIO-URL]/modules/sso/index.php/oidc/.well-known/openid-configuration).
      - Im einfachsten Fall die Metadaten-URL in die Client-Konfiguration einfügen
      - Wenn der Client die automatische Einrichtung mittels Metadaten nicht unterstützt, die Einstellungen manuell kopieren/eingeben:
          - Admidio URLs (Endpunkte) für Autorisierung, Token, Benutzerinfo und optional Logout
          - Öffentlicher Schlüssel / Zertifikat des Admidio IdP.
      - Wählen Sie eine eindeutige "Client ID", um den Client gegenüber Admidio zu identifizieren.
      - Wählen Sie die Scopes (Informationsklassen) aus, die Admidio an den Client senden soll (z.B. "openid,profile,email,address,phone,groups,custom", mindestens "openid" ist erforderlich)
      - Optional ein Mapping der OpenID Claims (einzelne Datenfelder) auf die Profilfelder des Clients
  - [[#Konfiguration von Admidio mit der Relying Party|Admidio so einrichten, dass es auf diesen speziellen Client (RP) reagiert]]:
      - Erstellen eines neuen OIDC-Clients in der SSO-Client-Administration von Admidio ("Einstellungen" -> "Single-Sign-On" -> "Single-Sign-On Client Administration")
          - Die "Client ID" aus der Client-App einfügen und die vom Client angegebene Redirect URI einfügen.
          - Admidio zeigt ein "Client Secret" an, das in die Konfiguration des Clients kopiert werden muss.
          - Wählen Sie aus, welche Scopes (Informationsklassen) an den Client gesendet werden dürfen, und wählen/mappen Sie optional die Admidio-Profilfelder und -Gruppen zu OpenID Claims (einzelne Informationen/Felder).
      - OpenID bietet KEINE automatische Konfiguration des Clients mittels Metadaten((Es gibt eine OpenID-Erweiterungsspezifikation für die dynamische/automatische Client-Registrierung, aber die hat andere Komplexitäten!)).

Diese Seite beschreibt die generische Einrichtung eines Admidio- und eines OpenID-Clients. Sie wurde mit mehreren OpenID-fähigen Anwendungen getestet, und clientspezifische Anweisungen sind auf separaten Seiten verfügbar.



====== Wie funktioniert Single-Sign-On? ======

===== Traditionelles Login =====

{{ :en:2.0:sso:admidio-saml-loginflows-password.svg?right&400|}}
Der Standard-Login-Prozess für eine Anwendung (den "Service Provider", d.h. SP) funktioniert mit den folgenden Schritten:

  - Der Benutzer klickt auf "Anmelden".
  - Die Anwendung bestimmt, ob der Benutzer Zugriff hat: Sie zeigt ein Anmeldeformular an, prüft den eingegebenen Benutzernamen und das Passwort (Hash), und wenn diese existieren und übereinstimmen, trifft sie die Entscheidung, den Zugriff zu gewähren.
  - Die Anwendung weiß nun, dass der Benutzer erfolgreich angemeldet ist und erstellt eine entsprechende Sitzung, um den Benutzer angemeldet zu halten.

Schritt 2 wird in diesem Fall von der Anwendung durchgeführt, aber es gibt dafür keine technische Voraussetzung. Im Prinzip kann die Entscheidung, dass ein Benutzer erfolgreich angemeldet ist, von jedem **vertrauenswürdigen** System getroffen werden. Hier setzt Single-Sign-On an: Anstatt dass jede Anwendung Passwörter anfordert und verarbeitet, wird Schritt 2 an einen sogenannten Identitätsanbieter ("IdP") delegiert. Dieser Identitätsanbieter muss vertrauenswürdig sein und übernimmt den Teil der Überprüfung, ob ein Benutzer Zugriffsrechte hat (z.B. durch Eingabe eines Passworts oder Verwendung eines Fingerabdrucks usw.).


===== Single-Sign-On mit SAML 2.0 unter Verwendung eines externen Identity Providers (IdP) =====

Es gibt zwei etablierte technische Protokolle für Single-Sign-On: **SAML 2.0** (XML-basiert, weit verbreitet in großen Geschäftsanwendungen und z.B. Microsoft ADFS) und **OpenID Connect (OIDC)** (JSON-basiert mit "Tokens"; verwendet von vielen Web-/Social-Apps wie Google, Facebook usw.).

SAML 2.0 basiert auf XML-Nachrichten und lagert im Grunde nur das Anmeldeformular und die daraus resultierende Anmeldeentscheidung an den IdP aus. Wenn der Login erfolgreich ist, sendet der IdP diese Informationen (zusammen mit dem Benutzernamen und optional weiteren Profilfeldern) als kryptografisch signiertes XML an den SAML-Client.

Im SAML-Fall ändert sich der oben beschriebene Login-Flow wie folgt. Aus Benutzersicht werden jedoch die gleichen Schritte der Passworteingabe durchgeführt, nur auf einem anderen System. Die im Flow involvierten Browser-Weiterleitungen werden vom Benutzer kaum bemerkt und erfordern keine Benutzerinteraktion.

{{ :en:2.0:sso:admidio-saml-loginflows-saml.svg?right&600&direct |}}

  - Der Benutzer klickt auf "Anmelden".
  - Die Anwendung bestimmt den Benutzer-Login nicht selbst. Stattdessen verlässt sie sich auf einen Drittanbieter (den "Identity Provider", kurz IdP), um festzustellen, ob ein Benutzer Zugriff hat:
      - Sie erstellt ein XML mit einer XML "AuthnRequest" und leitet den Browser zum IdP (in unserem Fall Admidio) weiter.
      - Wenn der Benutzer nicht bei Admidio angemeldet ist, wird der Anmeldebildschirm angezeigt.
      - Admidio prüft die Anmeldung des Benutzers (und ob der Benutzer Mitglied der erlaubten Gruppen ist).
      - Wenn der Login erfolgreich ist (oder der Benutzer bereits angemeldet war), sollte der Zugriff gewährt werden. Dies wird in XML-Daten (der "Assertion"; kryptografisch signiert, um Man-in-the-Middle-Angriffe zu verhindern) dokumentiert und per Browser-Weiterleitung an den Service Provider zurückgesendet.
      - Neben dem Benutzernamen kann die an den SP zurückgegebene Assertion auch weitere Benutzerinformationen (E-Mail, Vor-/Nachname usw.) und Gruppen/Rollen enthalten.
  - Die Client-Anwendung (Service Provider) weiß nun, dass der Benutzer erfolgreich bei Admidio angemeldet ist, und erstellt eine entsprechende Sitzung, um den Benutzer angemeldet zu halten.

Es gibt einige Dinge zu beachten, wie die SAML-Authentifizierung funktioniert:

  - Die gesamte **Passwortverwaltung** und -anforderung erfolgt **ausschließlich durch Admidio**. Der Service Provider (Client-Anwendung) empfängt, fragt oder muss niemals Passwörter verarbeiten.
  - Es ist äußerst wichtig sicherzustellen, dass die Anfragen wirklich an das richtige System gesendet werden und die zurückgegebenen Antworten tatsächlich vom autorisierten IdP stammen. Dies kann durch die Verwendung von **Public-Key-Kryptographie** gewährleistet werden, insbesondere durch das **Signieren jeder Anfrage und Antwort** mit privaten Schlüsseln, die nur dem SP bzw. IdP bekannt sind. Während der Ersteinrichtung müssen die entsprechenden Zertifikate (signierte Public Keys) ausgetauscht werden, was den Hauptteil der SSO-Einrichtung ausmacht (zusätzlich zur Bereitstellung der URLs des SP und IdP aneinander).
  - Der **IdP und der SP kommunizieren niemals direkt**, sondern nur über den Browser des Benutzers! Folglich können sich der IdP und der SP in getrennten Netzwerken befinden, z.B. kann der IdP sogar in einem privaten Netzwerk ohne Zugriff aus dem Internet sein, solange der Browser des Benutzers eine Verbindung zu ihm herstellen kann.



===== Single-Sign-On mit OpenID Connect unter Verwendung eines externen Identity Providers (IdP) =====

OpenID Connect basiert auf dem Austausch von Daten mit JSON-Objekten. Es ist eine Erweiterung des OAuth 2.0-Protokolls, das nur die Authentifizierung handhabt. Die OpenID-Schicht fügt zusätzliche Profilinformationen und Berechtigungen hinzu, verwendet aber OAuth für die grundlegende Autorisierung.

Anstatt nur mit Browser-Weiterleitungen wie SAML zu arbeiten, basiert OpenID auf OAuth und nutzt ausgiebig die direkte Kommunikation ("Backchannel") zwischen der Relying Party und dem IdP. Anstatt nur eine erfolgreiche Anmeldung zu dokumentieren, trennt OpenID Authentifizierung (erfolgreiche Anmeldung) und Autorisierung (Rollen, die Benutzerrechte gewähren). Es ist auch nicht auf eine aktive Sitzung beim IdP angewiesen. Stattdessen generiert es ein dediziertes Passwort (das "Token") für den Client und ersetzt somit das individuelle Passwort des Benutzers durch app-spezifische Passwörter, die intern vom Client und dem IdP gehandhabt werden, ohne dass der Benutzer es bemerkt. Wenn ein solches Token abläuft, kann ein anderes (Refresh-)Token verwendet werden, um ein neues Token zu erstellen, sodass kein neuer Login erforderlich ist. All dies geschieht im Hintergrund und die Benutzererfahrung ist im Grunde die gleiche wie bei einem direkten Login oder mit SAML.

<WRAP center round todo 60%>
todo box
</WRAP>


====== Setting up SSO via SAML 2.0 ======
===== 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. 


===== 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]/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]/modules/sso/index.php/saml/sso
  * **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

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

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

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): 
    * 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 |}}
  * **Client ID** (unique identifier of the Client)
  * **ACS URL** (where responses to login requests are sent to)
  * **Single-Log-Out URL** (optional): Backchannel endpoint to log out from all clients
  * **x509 Certificate** (to allow verification of the messages sent by the SP): PEM-format needs to be copied out from the client

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



====== Setting up SSO via OpenID Connect (OIDC) ======

===== A. Basic Setup for Admidio as an OpenID Connect ID Provider =====


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

==== 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). 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 some more settings regarding fields <=> claims mapping, groups, auto-generating accounts for new logins, etc. The details depend on the capabilities of the client.

{{: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|}}