Übersicht

Übersicht

SAML (Security Assertion Markup Language) ist ein weit verbreitetes Authentifizierungsprotokoll, das Single Sign-On (SSO) ermöglicht. Es erlaubt Benutzern, sich einmal bei einem Identity Provider (IdP) zu authentifizieren und Zugriff auf mehrere Dienste zu erhalten, ohne sich erneut anmelden zu müssen.

Aktivierung der Authentifizierungsmethode basierend auf Umgebungsvariablen

Die folgende Tabelle zeigt, welche Authentifizierungsmethode je nach Einstellung der Umgebungsvariablen aktiviert ist:

SAML-Zertifikatsformat und -Konfiguration

Die Umgebungsvariable SAML_CERT wird verwendet, um das Signaturzertifikat des Identity Providers (IdP) zur Validierung von SAML-Antworten anzugeben. Dieses Zertifikat muss im PEM-Format bereitgestellt werden und kann auf eine der folgenden Arten angegeben werden:

Als Dateipfad (relativ oder absolut)

Wenn SAML_CERT auf einen Dateipfad gesetzt ist, lädt die Anwendung das Zertifikat aus der angegebenen Datei. Sowohl relative Pfade als auch absolute Pfade werden unterstützt.

# Relative path (resolved based on the application root)
SAML_CERT=idp-cert.pem

# Absolute path
SAML_CERT=/path/to/idp-cert.pem

Beispiel-Dateiinhalt (idp-cert.pem):

-----BEGIN CERTIFICATE-----
MIIDazCCAlOgAwIBAgIUKhXaFJGJJPx466rl...
-----END CERTIFICATE-----

Als einzeiliger PEM-String

Das Zertifikat kann auch als einzeiliger PEM-String (Base64-kodiert, ohne Zeilenumbrüche) bereitgestellt werden.

SAML_CERT="MIICizCCAfQCCQCY8tKaMc0BMjANBgkqh...W=="

Dieses Format ist nützlich, wenn das Zertifikat direkt in Umgebungsvariablen gespeichert wird.

Als mehrzeiliger PEM-String (mit \n Escape-Sequenzen)

Das Zertifikat kann auch als mehrzeiliger PEM-String bereitgestellt werden, wobei Zeilenumbrüche als \n dargestellt werden.

SAML_CERT="-----BEGIN CERTIFICATE-----\nMIIDazCCAlOgAwIBAgIUKhXaFJGJJPx466rl...\n-----END CERTIFICATE-----\n"

Dieses Format ist nützlich, wenn Zertifikate in .env Dateien konfiguriert werden, während die vollständige PEM-Struktur beibehalten wird.

Anforderungen an das Zertifikatsformat

• Das Zertifikat muss immer im PEM-Format vorliegen (Base64-kodiertes X.509-Zertifikat).
• Falls es als Datei bereitgestellt wird, muss es ein gültiges RFC7468 strict textual message PEM format sein.
• Wenn Sie ein einzeiliges Zertifikat verwenden, stellen Sie sicher, dass der Wert keine Zeilenumbrüche enthält.
• Wenn Sie einen mehrzeiligen String verwenden, stellen Sie sicher, dass Zeilenumbrüche als \n-Escape-Sequenzen dargestellt werden.

Weitere Details finden Sie in der node-saml documentation.

Ablauf zur Bestimmung des angezeigten Benutzernamens basierend auf SAML-Attributen

Bei der SAML-Authentifizierung wird der angezeigte Benutzername gemäß dem folgenden Ablauf bestimmt.

flowchart TD
    A[Start] --> B{{Is SAML_NAME_CLAIM available?}}
    B -- Yes --> C[Value of SAML_NAME_CLAIM]
    B -- No --> D{{Are both SAML_GIVEN_NAME_CLAIM & SAML_FAMILY_NAME_CLAIM available?}}
    D -- Yes --> E[Value of SAML_GIVEN_NAME_CLAIM / SAML_FAMILY_NAME_CLAIM]
    D -- No --> F{{Is only SAML_GIVEN_NAME_CLAIM available?}}
    F -- Yes --> G[Value of SAML_GIVEN_NAME_CLAIM]
    F -- No --> H{{Is only SAML_FAMILY_NAME_CLAIM available?}}
    H -- Yes --> I[Value of SAML_FAMILY_NAME_CLAIM]
    H -- No --> J{{Is SAML_USERNAME_CLAIM available?}}
    J -- Yes --> K[Value of SAML_USERNAME_CLAIM]
    J -- No --> L[Value of SAML_EMAIL_CLAIM]
    style C fill:#FFDEA5,stroke:#FFA500
    style E fill:#FFDEA5,stroke:#FFA500
    style G fill:#FFDEA5,stroke:#FFA500
    style I fill:#FFDEA5,stroke:#FFA500
    style K fill:#FFDEA5,stroke:#FFA500
    style L fill:#FFDEA5,stroke:#FFA500

Bestimmungsregeln

1. Wenn SAML_NAME_CLAIM bereitgestellt wird, wird dessen Wert als Anzeigename des Benutzers verwendet.
2. Wenn sowohl SAML_GIVEN_NAME_CLAIM als auch SAML_FAMILY_NAME_CLAIM bereitgestellt werden, werden ihre entsprechenden Werte verkettet, um den Benutzernamen zu bilden.
3. Wenn nur SAML_GIVEN_NAME_CLAIM bereitgestellt wird, wird dessen Wert verwendet.
4. Wenn nur SAML_FAMILY_NAME_CLAIM bereitgestellt wird, wird dessen Wert verwendet.
5. Wenn SAML_USERNAME_CLAIM bereitgestellt wird, wird dessen Wert verwendet.
6. Wenn keines der oben genannten Attribute angegeben ist, wird SAML_EMAIL_CLAIM als Anzeigename für den Benutzer verwendet.

Durch Befolgen dieses Ablaufs wird während der SAML-Authentifizierung ein geeigneter Benutzername ermittelt.

Konfigurationsbeispiele

• Auth0