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 demselbenemail
-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:
- 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.
- 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?