Dieses Dokument wurde mithilfe automatisierter maschineller Übersetzungstechnologie übersetzt. Wir bemühen uns um korrekte Übersetzungen, übernehmen jedoch keine Gewähr für die Vollständigkeit, Richtigkeit oder Zuverlässigkeit der übersetzten Inhalte. Im Falle von Abweichungen ist die englische Originalversion maßgebend und stellt den verbindlichen Text dar.

Keycloak (SAML) konfigurieren

Wenn Ihre Organisation Keycloak Identity Provider (IdP) zur Benutzerauthentifizierung verwendet, können Sie Rancher so konfigurieren, dass Ihre Benutzer sich mit ihren IdP-Anmeldeinformationen anmelden können.

Voraussetzungen

  • Sie müssen einen Keycloak IdP Server konfiguriert haben.

  • Erstellen Sie in Keycloak einen neuen SAML-Client mit den folgenden Einstellungen. Siehe die Keycloak-Dokumentation für Hilfe.

    Einstellung Wert

    Sign Documents

    ON 1

    Sign Assertions

    ON 1

    Alle anderen ON/OFF Einstellungen

    OFF

    Client ID

    Entweder https://yourRancherHostURL/v1-saml/keycloak/saml/metadata oder der in der Entry ID Field der Rancher Keycloak-Konfiguration konfigurierte Wert2

    Client Name

    (z.B. rancher)

    Client Protocol

    SAML

    Valid Redirect URI

    https://yourRancherHostURL/v1-saml/keycloak/saml/acs

    1: Optional können Sie eine oder beide dieser Einstellungen aktivieren. 2: Die Rancher SAML-Metadaten werden nicht generiert, bis ein SAML-Anbieter konfiguriert und gespeichert ist.

    keycloak saml client configuration

  • Erstellen Sie im neuen SAML-Client Mapper, um die Benutzerfelder offenzulegen.

    • Fügen Sie alle "Builtin Protocol Mappers" hinzu

      keycloak saml client builtin mappers

    • Erstellen Sie einen neuen "Group list" Mapper, um das Mitgliedsattribut den Gruppen eines Benutzers zuzuordnen.

      keycloak saml client group mapper

Abrufen der IDP-Metadaten

  • Keycloak 5 und früher

  • Keycloak 6-13

  • Keycloak 14+

Um die IDP-Metadaten zu erhalten, exportieren Sie eine metadata.xml Datei von Ihrem Keycloak-Client. Wählen Sie im Tab Installation die Formatoption SAML Metadata IDPSSODescriptor und laden Sie Ihre Datei herunter.

  1. Klicken Sie im Abschnitt Konfigurieren auf die Registerkarte Realm-Einstellungen.

  2. Klicken Sie auf die Registerkarte Allgemein.

  3. Klicken Sie im Feld Endpunkte auf SAML 2.0 Identitätsanbieter-Metadaten.

Überprüfen Sie, ob die IDP-Metadaten die folgenden Attribute enthalten:

xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"

Einige Browser, wie Firefox, können das Dokument so darstellen/verarbeiten, dass der Inhalt geändert zu sein scheint und einige Attribute fehlen. In dieser Situation verwenden Sie die Rohdaten der Antwort, die Sie mit Ihrem Browser finden können.

Das Folgende ist ein Beispiel für einen Prozess in Firefox, kann jedoch für andere Browser leicht variieren:

  1. Drücken Sie F12, um die Entwicklertools zu öffnen.

  2. Klicken Sie auf die Registerkarte Netzwerk.

  3. Klicken Sie in der Tabelle auf die Zeile, die descriptor enthält.

  4. Klicken Sie im Detailbereich auf die Registerkarte Antwort.

  5. Kopieren Sie die Rohdaten der Antwort.

Die erhaltene XML enthält EntitiesDescriptor als Root-Element. Rancher erwartet, dass das Root-Element EntityDescriptor anstelle von EntitiesDescriptor ist. Bevor Sie diese XML an Rancher übergeben, befolgen Sie diese Schritte, um sie anzupassen:

  1. Kopieren Sie alle Attribute von EntitiesDescriptor zu dem EntityDescriptor, die nicht vorhanden sind.

  2. Entfernen Sie das <EntitiesDescriptor>-Tag vom Anfang.

  3. Entfernen Sie das </EntitiesDescriptor> vom Ende der XML.

Es bleibt etwas Ähnliches übrig, wie im folgenden Beispiel:

<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" entityID="https://{KEYCLOAK-URL}/auth/realms/{REALM-NAME}">
....
</EntityDescriptor>

  1. Klicken Sie im Abschnitt Konfigurieren auf die Registerkarte Realm-Einstellungen.

  2. Klicken Sie auf die Registerkarte Allgemein.

  3. Klicken Sie im Feld Endpunkte auf SAML 2.0 Identitätsanbieter-Metadaten.

Überprüfen Sie, ob die IDP-Metadaten die folgenden Attribute enthalten:

xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"

Einige Browser, wie Firefox, können das Dokument so darstellen/verarbeiten, dass der Inhalt geändert zu sein scheint und einige Attribute fehlen. In dieser Situation verwenden Sie die Rohdaten der Antwort, die Sie mit Ihrem Browser finden können.

Das folgende ist ein Beispielprozess für Firefox, kann jedoch leicht für andere Browser variieren:

  1. Drücken Sie F12, um die Entwicklertools zu öffnen.

  2. Klicken Sie auf die Registerkarte Netzwerk.

  3. Klicken Sie in der Tabelle auf die Zeile, die descriptor enthält.

  4. Klicken Sie im Detailbereich auf die Registerkarte Antwort.

  5. Kopieren Sie die Rohdaten der Antwort.

Keycloak in Rancher konfigurieren

  1. Klicken Sie oben links auf ☰ > Benutzer & Authentifizierung.

  2. Klicken Sie im linken Navigationsmenü auf Auth-Anbieter.

  3. Klicken Sie auf Keycloak SAML.

  4. Füllen Sie das Formular Keycloak-Konto konfigurieren aus. Für Hilfe beim Ausfüllen des Formulars siehe die Konfigurationsreferenz.

  5. Nachdem Sie das Formular Keycloak-Konto konfigurieren ausgefüllt haben, klicken Sie auf Aktivieren.

    Rancher leitet Sie zur IdP-Anmeldeseite weiter. Geben Sie Anmeldeinformationen ein, die mit Keycloak IdP authentifiziert werden, um Ihre Rancher Keycloak-Konfiguration zu validieren.

    Möglicherweise müssen Sie Ihren Popup-Blocker deaktivieren, um die IdP-Anmeldeseite zu sehen.

Ergebnis: Rancher ist so konfiguriert, dass es mit Keycloak funktioniert. Ihre Benutzer können sich jetzt mit ihren Keycloak-Anmeldedaten bei Rancher anmelden.

SAML-Anbieter-Hinweise

  • Benutzer und Gruppen werden nicht validiert, wenn Sie ihnen Berechtigungen in Rancher zuweisen.

  • Beim Hinzufügen von Benutzern müssen die genauen Benutzer-IDs (d.h. UID Field) korrekt eingegeben werden. Während Sie die Benutzer-ID eingeben, wird nicht nach anderen Benutzer-IDs gesucht, die möglicherweise übereinstimmen.

  • Beim Hinzufügen von Gruppen müssen Sie die Gruppe aus dem Dropdown-Menü auswählen, das neben dem Textfeld steht. Rancher geht davon aus, dass jede Eingabe im Textfeld ein Benutzer ist.

  • Das Gruppen-Dropdown zeigt nur die Gruppen an, in denen Sie Mitglied sind. Wenn Sie jedoch Administratorrechte oder eingeschränkte Administratorrechte haben, können Sie einer Gruppe beitreten, in der Sie kein Mitglied sind.

Konfigurationsreferenz

Feld Beschreibung

Feld für den Anzeigenamen

Das Attribut, das den Anzeigenamen der Benutzer enthält.

Beispiel: givenName

Feld für den Benutzernamen

Das Attribut, das den Benutzernamen/Vornamen enthält.

Beispiel: email

UID-Feld

Ein Attribut, das für jeden Benutzer einzigartig ist.

Beispiel: email

Gruppenfeld

Erstellen Sie Einträge zur Verwaltung von Gruppenmitgliedschaften.

Beispiel: member

Entity-ID-Feld

Die ID, die als Client-ID im Keycloak-Client konfiguriert werden muss.

Standard: https://yourRancherHostURL/v1-saml/keycloak/saml/metadata

Rancher API-Host

Die URL für Ihren Rancher-Server.

Privater Schlüssel / Zertifikat

Ein Schlüssel/Zertifikat-Paar zur Erstellung einer sicheren Shell zwischen Rancher und Ihrem IdP.

IDP-metadata

Die metadata.xml Datei, die Sie von Ihrem IdP-Server exportiert haben.

Sie können ein Schlüssel/Zertifikat-Paar mit dem Befehl openssl generieren. Beispiel:

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert

Anhang: Fehlerbehebung

Wenn Sie Probleme beim Testen der Verbindung zum Keycloak-Server haben, überprüfen Sie zuerst die Konfigurationsoption Ihres SAML-Clients. Sie können auch die Rancher-Protokolle überprüfen, um die Ursache des Problems zu ermitteln. Debug-Protokolle können detailliertere Informationen über den Fehler enthalten. Bitte beziehen Sie sich auf Wie kann ich das Debug-Logging aktivieren in dieser Dokumentation.

Sie werden nicht zu Keycloak umgeleitet.

Wenn Sie auf Mit Keycloak authentifizieren klicken, werden Sie nicht zu Ihrem IdP umgeleitet.

  • Überprüfen Sie Ihre Keycloak-Clientkonfiguration.

  • Stellen Sie sicher, dass Force Post Binding auf OFF eingestellt ist.

Die Fehlermeldung wird nach der IdP-Anmeldung angezeigt.

Sie werden korrekt auf Ihre IdP-Anmeldeseite umgeleitet und können Ihre Anmeldedaten eingeben, jedoch erhalten Sie danach eine Forbidden-Meldung.

  • Überprüfen Sie das Rancher-Debugprotokoll.

  • Wenn das Protokoll ERROR: either the Response or Assertion must be signed anzeigt, stellen Sie sicher, dass entweder Sign Documents oder Sign assertions in Ihrem Keycloak-Client auf ON eingestellt ist.

HTTP 502 beim Versuch, auf /v1-saml/keycloak/saml/metadata zuzugreifen.

Dies liegt normalerweise daran, dass die Metadaten nicht erstellt werden, bis ein SAML-Anbieter konfiguriert ist. Versuchen Sie, Keycloak als Ihren SAML-Anbieter zu konfigurieren und zu speichern und dann auf die Metadaten zuzugreifen.

Keycloak-Fehler: "Es tut uns leid, die Antwort konnte nicht verarbeitet werden"

  • Überprüfen Sie Ihr Keycloak-Protokoll.

  • Wenn das Protokoll failed: org.keycloak.common.VerificationException: Client does not have a public key anzeigt, setzen Sie Encrypt Assertions in Ihrem Keycloak-Client auf OFF.

Keycloak-Fehler: "Es tut uns leid, ungültiger Anforderer"

  • Überprüfen Sie Ihr Keycloak-Protokoll.

  • Wenn das Protokoll request validation failed: org.keycloak.common.VerificationException: SigAlg was null anzeigt, setzen Sie Client Signature Required in Ihrem Keycloak-Client auf OFF.

Beliebtheit in der CNI-Community

Konfiguration des SAML Single Logout (SLO)

Rancher supports the ability to configure SAML SLO. Options include logging out of the Rancher application only, logging out of Rancher and registered applications tied to the external authentication provider, or a prompt asking the user to choose between the previous options. The steps below outline configuration from the application GUI:

The Log Out behavior configuration section only appears if the SAML authentication provider allows for SAML SLO.

  1. Sign in to Rancher using a standard user or an administrator role to configure SAML SLO.

  2. In the top left corner, click ☰ > Users & Authentication.

  3. In the left navigation menu, click Auth Provider.

  4. Under the section Log Out behavior, choose the appropriate SLO setting as described below:

    Setting Description

    Log out of Rancher and not authentication provider

    Choosing this option will only logout the Rancher application and not external authentication providers.

    Log out of Rancher and authentication provider (includes all other applications registered with authentication provider)

    Choosing this option will logout Rancher and all external authentication providers along with any registered applications linked to the provider.

    Allow the user to choose one of the above in an additional log out step

    Choosing this option presents users with a choice of logout method as described above.

SAML- und OpenLDAP-Gruppenberechtigungen

When you configure a SAML authentication provider backed by OpenLDAP, the SAML response might return only a subset of the groups that a user belongs to. The exact groups returned depend on the configuration of your external authentication provider.

Rancher assigns user permissions based strictly on the groups provided in the SAML response.

Even if you can search for and view specific OpenLDAP groups in the Rancher UI, you cannot use them to assign permissions if they are missing from the SAML response.

To assign permissions successfully, verify that your SAML authentication provider is configured to return all necessary OpenLDAP groups.