SAML

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

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

Warnung

Bitte beachten Sie: Unsere Anleitung basiert auf der Anbindung von Keycloak.

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.

Wenn Ihr IdP den XML-Import nicht unterstützt, müssen Sie Zammad manuell als neuen Client/App konfigurieren und dabei die oben genannte XML-Metadaten-Datei als Referenz verwenden.

Wenn Sie zum Beispiel diesen Tag sehen:

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

Beispielkonfiguration von SAML Teil 1
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 Ziel-URL für Einzel-Abmeldung

Dies ist die URL, an die die einzelne Abmeldeanforderung gesendet werden soll.

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.

Zammad erwartet eine E-Mail-Adresse als eindeutigen Identifikator!

Name des UID-Attributs

Hier können Sie ein Attribut zur eindeutigen Identifizierung des Benutzers festlegen. Wenn es nicht gesetzt ist, wird der von der IDP zurückgegebene Namensbezeichner verwendet.

Beispielkonfiguration von SAML Teil 2
SSL-Verifizierung

Entscheiden Sie, ob das Zertifikat für die Verbindung zum IdP-Dienst verifiziert werden muss oder nicht (Standard: Ja).

Gefahr

Bitte beachten Sie, dass das Deaktivieren der SSL-Verifizierung ein Sicherheitsrisiko darstellt. Es sollte nur vorübergehend oder zu Testzwecken verwendet werden. Wenn diese Option deaktiviert ist, findet keine Überprüfung des Zertifikats statt, was bedeutet, dass jedes vorgelegte Zertifikat akzeptiert wird.

Signieren & Verschlüsseln

Legen Sie fest, ob Sie die Anfragen signieren, verschlüsseln, beides oder nichts tun wollen.

Zertifikat (PEM)

Fügen Sie das öffentliche Zertifikat Ihres Zammad SAML-Clients ein, wenn Sie die Anfragen verschlüsseln möchten.

Privater Schlüssel (PEM)

Fügen Sie hier den privaten Schlüssel Ihres Zammad SAML-Clients ein, wenn Sie die Anfragen signieren möchten.

Geheimnis des privaten Schlüssels

Wenn Ihr privater Schlüssel mit einem Passwort gesichert ist, können Sie es hier angeben.

Ihre Callback-URL

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

Hinweis

Nachdem Sie Ihre Eingaben durch Klicken auf die Schaltfläche „Absenden“ gespeichert haben, überprüft Zammad die bereitgestellten Schlüssel/Zertifikate (z.B. ob sie zum Signieren/Verschlüsseln gültig und nicht abgelaufen sind).

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?