SAML

Einführung

Verbinden Sie Ihren SAML (Security Assertion Markup Language)-Identitätsanbieter als SSO-Methode (Single Sign-On). SAML ist ein offener Standard für die SSO-Authentifizierung (u.a.). Anmeldungen werden von mehreren Dienstanbietern gemeinsam genutzt und von einem zentralen Identitätsanbieter (Identity provider, 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).

Basis-Konfiguration

Dieser Abschnitt beschreibt die Einrichtung eines IdP in allgemeiner Form. Außerdem gibt es Einrichtungsanleitungen für Keycloak und Microsoft SAML.

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.

Konfigurationsanleitung

Sie finden Konfigurationsanleitungen für:

• Keycloak

• Microsoft SAML

Wenn Sie einen anderen IdP verwenden, passen Sie die Schritte entsprechend an. Für eine Beschreibung der Felder in Zammad lesen Sie weiter unten.

Allgemeine Zammad-Konfiguration

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

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, an die Zammad weiterleiten soll, wenn der Benutzer die SAML-Schaltfläche drückt.

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.

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.

Vergewissern Sie sich, dass das Zertifikat:

• bereits gültig und noch nicht abgelaufen ist

• kein CA-Zertifikat ist

• gültig zum Signieren und Verschlüsseln ist

Privater Schlüssel (PEM)

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

Stellen Sie sicher, dass der Schlüssel ein RSA-Schlüssel mit einer Länge von mindestens 2048 Bit ist.

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?