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

In diesem Abschnitt wird die Einrichtung eines IdP allgemein beschrieben. Spezifische Einrichtungsanleitungen finden Sie für Keycloak sowie für Microsoft SAML. Falls Sie einen anderen IdP verwenden, passen Sie die Anleitung bitte an Ihr jeweiliges Szenario an. Eine Beschreibung der Felder in Zammad finden Sie weiter unten.

Konfigurieren Sie Ihren IdP

Zammad als Client/Anwendung hinzufügen

Importieren Sie Zammad in Ihren IdP mithilfe der XML-Konfiguration, die Sie unter https://zammad.example.com/auth/saml/metadata finden. Falls Ihr IdP den XML-Import nicht unterstützt, müssen Sie Zammad manuell als neuen Client/neue App konfigurieren und dabei die oben genannte XML-Metadatendatei als Vorlage verwenden.

Wenn Sie zum Beispiel diesen Tag sehen:

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

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

Benutzerattribut-Zuordnung einrichten

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

  • E-Mail Adresse (email)

  • Vollständiger Name (name)

  • Vorname (first_name)

  • Nachname (last_name)

Möglicherweise müssen Sie „Mappers“ (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.

Allgemeine Zammad-Konfiguration

Aktivieren Sie SAML und geben Sie die Details Ihres IdP in den Einstellungen 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, 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

IdP-Zertifikat oder Zertifikats-Fingerabdruck

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

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.

Nachdem Sie Ihre Eingabe durch Klicken auf Übermitteln gespeichert haben, verifiziert Zammad die bereitgestellten Schüssel/Zertifikate (z.B. ob sie für das Signieren/Verschlüsseln gültig sind und nicht abgelaufen sind). Weitere Informationen zum Verknüpfen bestehender Zammad-Konten mit IdP-Konten finden Sie unter Konto-Verknüppung.

Fehlerbehebung

Automatische Kontoverknüpfung funktioniert nicht

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

Logout funktioniert nicht

Falls Ihr Logout-Prozess nicht funktioniert, können Sie https://zammad.example.com/auth/saml/slo als Alternative versuchen. Allerdings wird dann keine Abmeldung an Ihren IdP gesendet.