SAML

Verbinden Sie Ihren SAML-Identitätsanbieter als Single-Sign-On-Methode (SSO).

Bemerkung

🤷 Was ist SAML?

SAML ist (u.a.) ein offener Standard für die SSO-Authentifizierung. Anmeldungen werden von mehreren Dienstanbietern gemeinsam genutzt und von einem zentralen Identitätsanbieter (Identity Provider, kurz IdP) verwaltet.

In diesem Fall ist der Dienstanbieter Zammad, und der IdP ist ein Softwaredienst, den Sie entweder selbst hosten oder abonnieren (z.B. Keycloak, Redhat SSO Server, ADFS, oder Okta).

Die Anleitung geht davon aus, dass Sie SAML bereits in Ihrer Organisation verwenden (d.h. dass Ihr IdP vollständig eingerichtet ist).

Schritt 1: Konfigurieren Sie Ihren IdP

Zammad als Client/Anwendung hinzufügen

Importieren Sie Zammad in Ihren IdP unter Verwendung der XML-Konfiguration, die Sie unter https://your.zammad.domain/auth/saml/metadata finden.

Bemerkung

🙋 Was ist, wenn mein IdP den XML-Import nicht unterstützt?

Sie müssen Zammad als neuen Client/App manuell konfigurieren, indem Sie die obige XML-Metadaten-Datei als Referenz verwenden. Ein Beispiel mit folgendem Tag:

<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="http://your.zammad.domain/auth/saml/callback" index="0" isDefault="true"/>

Setzen Sie die Assertion Consumer Service Binding URL (manchmal auch als Valid Redirect URIs bezeichnet) auf http://your.zammad.domain/auth/saml/callback.

Benutzerattribut-Zuordnung einrichten

Zammad fordert die folgenden Benutzerattribute (oder „Eigenschaften“) vom IdP an:

  • E-Mail Adresse (email)

  • Vollständiger Name (name)

  • Vorname (first_name)

  • Nachname (last_name)

Möglicherweise müssen Sie „Mapper“ (oder „Mappings“) einrichten, um Ihrem IdP mitzuteilen, welche Benutzerattribute in SAML mit welchen in Zammad übereinstimmen. Eine detailliertere Aufschlüsselung finden Sie in der XML-Metadaten-Datei, auf die im vorherigen Abschnitt verwiesen wurde.

Informationen für verschiedene IdP

Keycloak

  • Um Zammad als Client hinzuzufügen, speichern Sie die XML-Konfiguration auf Ihrem Rechner (https://your.zammad.domain/auth/saml/metadata) und verwenden Sie Clients > Clients list > Import client im Keycloak Admin Panel.

  • Um Zammad bei der Zuordnung der Benutzerkonten zu Keycloak-Benutzern zu helfen, erstellen Sie einen Benutzerattribut- (oder „Eigenschafts-„)-Mapper. Klicken Sie in der Clientl list auf Ihre neu erstellte Client-ID, wählen Sie den Reiter Client scopes und klicken Sie auf den Link, der auf Ihre Zammad-Instanz verweist. Wählen Sie Add mapper > By configuration > User Property und erstellen Sie einen Mapper mit den folgenden Einträgen:

    Name

    email

    Mapper-Typ

    User Property

    Property

    emailAddress

    SAML Attribute Name

    email

    SAML Attribute NameFormat

    basic

    Im obigen Beispiel weisen wir Zammad an, dass es bei jeder SAML-Anmeldeanfrage die Eigenschaft email von Keycloak nehmen, nach einem Zammad-Benutzer mit demselben email-Attribut suchen und eine neue Sitzung für diesen Benutzer erstellen soll.

    Wenn die E-Mail-Adressen Ihrer Keycloak-Benutzer in einer anderen Eigenschaft gespeichert sind (z.B. username), passen Sie sie entsprechend an.

  • Geben Sie in den Einstellungen die Client-ID (https://your.zammad.domain/auth/saml/metadata) in das Feld Master SAML Processing URL ein.

  • Sie müssen auch Sign Assertions aktivieren.

Schritt 2: Zammad konfigurieren

Aktivieren Sie SAML und geben Sie die Details Ihres IdP im Admin Bereich unter Einstellungen > Sicherheit > Anwendungen von Drittanbietern > Anmeldung über SAML ein:

SAML Beispielkonfiguration
Anzeigename

Ermöglicht es Ihnen, einen eigenen Namen für den SAML-Button zu definieren. Das kann hilfreich sein, damit Ihre Benutzer verstehen, was die Schaltfläche auf der Anmeldeseite genau bewirkt.

Die Voreinstellung ist SAML.

IDP SSO Ziel-URL

Dies ist die Ziel-URL, zu der Zammad umleiten soll, wenn der Benutzer die SAML-Schaltfläche anklickt. Für Keycloak muss dies wie folgt aussehen: https://your.domain/realms/your-realm/protocol/saml.

IDP-Zertifikat

Das öffentliche Zertifikat Ihres IDP, das Zammad während des „Callbacks“ überprüfen soll.

Fingerabdruck IDP-Zertifikat

Der Fingerabdruck Ihres öffentlichen IDP-Zertifikats, der während des „Callbacks“ geprüft wird.

Bemerkung

🔏 Für das IdP-Zertifikat / den Zertifikatsfingerabdruck:

Verwenden Sie nur eine der Varianten. Wir empfehlen die Verwendung des Zertifikats selbst: Fingerabdrücke verwenden SHA-1, das seit einiger Zeit als unsicher gilt).

Keycloak-Anwender: Sie finden Ihr Zertifikat im Keycloak-Administrationsbereich unter Realm Settings > Keys > Algorithm: RS256 > Certificate.

Name Identifier Format

Dies ist der Feldtyp für unique identifiers (eindeutige Kennung). Normalerweise ist es urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

Warnung

Zammad erwartet eine E-Mail-Adresse als eindeutige Identifizierung!

Ihre Callback-URL

Diese URL wird für die IDP-Konfiguration benötigt, damit dieser weiß, wohin er nach erfolgreicher Authentifizierung weiterleiten muss.

Siehe automatische Kontoverknüpfung für Details zur Verknüpfung bestehender Zammad-Konten mit IdP-Konten.

Fehlerbehebung

Automatische Kontoverknüpfung funktioniert nicht

Haben Sie die Konfiguration der Benutzerattribut-Zuordnung Ihres IdP überprüft?