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 (OIDC) 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. Rancher unterstützt die Integration mit Keycloak über das OpenID Connect (OIDC)-Protokoll und das SAML-Protokoll. Beide Implementierungen sind funktional gleichwertig, wenn sie mit Rancher verwendet werden. Diese Seite beschreibt den Prozess zur Konfiguration von Rancher für die Zusammenarbeit mit Keycloak über das OIDC-Protokoll.

Wenn Sie Keycloak stattdessen mit dem SAML-Protokoll verwenden möchten, siehe diese Seite.

Wenn Sie eine vorhandene Konfiguration mit dem SAML-Protokoll haben und zum OIDC-Protokoll wechseln möchten, siehe diesen Abschnitt.

Voraussetzungen

  • In Rancher ist Keycloak (SAML) deaktiviert.

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

  • Befolgen Sie die Keycloak-Dokumentation, um einen neuen OIDC-Client mit den folgenden Einstellungen zu erstellen.

    Einstellung Wert

    Client ID

    <client-id> (z.B. rancher)

    Name

    <client-name> (z.B. rancher)

    Client type

    OpenID Connect

    Client authentication

    ON

    Valid Redirect URI

    https://yourRancherHostURL/verify-auth

  • Erstellen Sie im neuen OIDC-Client Mappers, um die Benutzerfelder offenzulegen.

    1. Klicken Sie im Navigationsmenü auf Clients.

    2. Klicken Sie auf die Registerkarte Clients-Liste.

    3. Suchen Sie den Client, den Sie erstellt haben, und klicken Sie darauf.

    4. Klicken Sie auf die Registerkarte Client-Bereiche.

    5. Suchen Sie den Link mit der Bezeichnung <client-name>-dedicated und klicken Sie darauf. Wenn Sie beispielsweise Ihren Client rancher genannt haben, suchen Sie nach dem Link mit dem Namen rancher-dedicated.

    6. Klicken Sie auf die Registerkarte Mappers.

    7. Klicken Sie auf einen neuen Mapper konfigurieren. Wenn Sie bereits vorhandene Mapper konfiguriert haben, klicken Sie auf den Pfeil neben Mapper hinzufügen und wählen Sie Nach Konfiguration aus. Wiederholen Sie diesen Prozess und erstellen Sie diese Mapper:

      • Wählen Sie aus der Mapping-Tabelle Gruppenmitgliedschaft aus und konfigurieren Sie einen neuen "Gruppenmapper" mit den folgenden Einstellungen. Für nicht erwähnte Einstellungen verwenden Sie den Standardwert.

        Einstellung Wert

        Name

        Groups Mapper

        Mapper Type

        Group Membership

        Token Claim Name

        groups

        Full group path

        OFF

        Add to ID token

        OFF

        Add to access token

        OFF

        Add to user info

        ON

      • Wählen Sie aus der Mapping-Tabelle Zielgruppe aus und konfigurieren Sie eine neue "Client-Zielgruppe" mit den folgenden Einstellungen. Für nicht erwähnte Einstellungen verwenden Sie den Standardwert.

        Einstellung Wert

        Name

        Client Audience

        Mapper Type

        Audience

        Included Client Audience

        <client-name>

        Add to ID token

        OFF

        Add to access token

        ON

      • Wählen Sie aus der Mapping-Tabelle Gruppenmitgliedschaft aus und konfigurieren Sie einen neuen "Gruppenpfad" mit den folgenden Einstellungen. Für nicht erwähnte Einstellungen verwenden Sie den Standardwert.

        Einstellung Wert

        Name

        Group Path

        Mapper Type

        Group Membership

        Token Claim Name

        full_group_path

        Full group path

        ON

        Add to ID token

        ON

        Add to access token

        ON

        Add to user info

        ON

  • Fügen Sie die folgenden Rollenzuordnungen allen Benutzern oder Gruppen hinzu, die die Keycloak-Benutzer abfragen müssen.

    • Benutzer

    • Gruppen

    1. Klicken Sie im Navigationsmenü auf Benutzer.

    2. Klicken Sie auf den Benutzer, dem Sie Rollenzuordnungen hinzufügen möchten.

    3. Klicken Sie auf die Registerkarte Rollenzuordnung.

    4. Klicken Sie auf Rolle zuweisen.

    5. Wählen Sie die folgenden Rollen aus:

      • benutzer-abfragen

      • gruppen-abfragen

      • benutzer-anzeigen

    6. Klicken Sie auf Zuweisen.

    1. Klicken Sie im Navigationsmenü auf Gruppen.

    2. Klicken Sie auf die Gruppe, der Sie Rollenzuordnungen hinzufügen möchten.

    3. Klicken Sie auf die Registerkarte Rollenzuordnung.

    4. Klicken Sie auf Rolle zuweisen.

    5. Wählen Sie die folgenden Rollen aus:

      • benutzer-abfragen

      • gruppen-abfragen

      • benutzer-anzeigen

    6. Klicken Sie auf Zuweisen.

Keycloak in Rancher konfigurieren

  1. Klicken Sie in der Rancher-Benutzeroberfläche auf ☰ > Benutzer & Authentifizierung.

  2. Klicken Sie in der linken Navigationsleiste auf Auth-Anbieter.

  3. Wählen Sie Keycloak (OIDC) aus.

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

    Beim Konfigurieren des Abschnitts Endpoints mit der Option Generieren fügt Rancher /auth als Teil des Kontextpfads in den Feldern Issuer und Auth Endpoint hinzu, was nur für Keycloak 16 oder älter gültig ist. Sie müssen Endpunkte mit der Option Festlegen für Keycloak 17 und neuer konfigurieren, die auf Quarkus migriert wurden.

  5. Nachdem Sie das Formular Keycloak OIDC-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 Anmeldeseite des IdP zu sehen.

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

Konfigurationsreferenz

Feld Beschreibung

Client-ID

Der Client ID Ihres Keycloak-Clients.

Client-Geheimnis

Der generierte Secret Ihres Keycloak-Clients. Wählen Sie in der Keycloak-Konsole Clients aus, wählen Sie den von Ihnen erstellten Client aus, wählen Sie die Registerkarte Credentials und kopieren Sie den Wert des Feldes Secret.

Privater Schlüssel / Zertifikat

Ein Schlüssel/Zertifikat-Paar zur Erstellung einer sicheren Shell zwischen Rancher und Ihrem IdP. Erforderlich, wenn HTTPS/SSL auf Ihrem Keycloak-Server aktiviert ist.

Endpunkte

Wählen Sie, ob Sie die generierten Werte für die Felder Rancher URL, Issue und Auth Endpoint verwenden oder manuelle Überschreibungen bereitstellen möchten, wenn diese falsch sind.

Keycloak-URL

Die URL für Ihren Keycloak-Server.

Keycloak-Bereich

Der Name des Bereichs, in dem der Keycloak-Client erstellt wurde.

Rancher-URL

Die URL für Ihren Rancher-Server.

Aussteller

Die URL Ihres IdP.

Auth-Endpunkt

Die URL, zu der Benutzer umgeleitet werden, um sich zu authentifizieren.

Migration von SAML zu OIDC

Dieser Abschnitt beschreibt den Prozess, um von der Verwendung von Rancher mit Keycloak (SAML) zu Keycloak (OIDC) zu wechseln.

  1. Keycloak neu konfigurieren.

    1. Konfigurieren Sie einen neuen OpenID Connect Client gemäß den Voraussetzungen. Stellen Sie sicher, dass dieselben Valid Redirect URIs festgelegt sind.

    2. Konfigurieren Sie Mapper für den neuen Client gemäß den Voraussetzungen.

  2. Bevor Sie Rancher so konfigurieren, dass es Keycloak (OIDC) verwendet, muss Keycloak (SAML) zuerst deaktiviert werden.

    1. Klicken Sie in der Rancher-Benutzeroberfläche auf ☰ > Benutzer & Authentifizierung.

    2. Klicken Sie in der linken Navigationsleiste auf Authentifizierungsanbieter.

    3. Wählen Sie Keycloak (SAML) aus.

    4. Klicken Sie auf Deaktivieren.

  3. Befolgen Sie die Schritte in Konfigurieren von Keycloak in Rancher.

    Nachdem die Konfiguration abgeschlossen ist, müssen die Benutzerberechtigungen in Rancher erneut angewendet werden, da sie nicht automatisch migriert werden.

OIDC-Unterstützung für PKCE-Erweiterung

Rancher supports the Proof Key for Code Exchange (PKCE) extension (RFC 7636) for OIDC authentication providers. SHA-256 (S256) is the only supported PKCE verification method. To enable this feature, your authentication provider must use PKCE with S256 for authorization requests.

You can enable this feature by selecting Enable PKCE (S256) in your authentication provider configuration in Rancher. Enabling S256 PKCE token verification allows you to mitigate authorization code interception attacks during OIDC authentication flows.

Anhang: Fehlerbehebung

Wenn Sie Probleme beim Testen der Verbindung zum Keycloak-Server haben, überprüfen Sie zuerst die Konfigurationsoptionen Ihres OIDC-Clients. Sie können auch die Rancher-Protokolle überprüfen, um herauszufinden, was die Probleme verursacht. 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.

Alle Keycloak-bezogenen Protokolleinträge werden entweder mit [generic oidc] oder [keycloak oidc] vorangestellt.

Sie werden nicht zu Keycloak umgeleitet.

Wenn Sie das Formular Konfigurieren eines Keycloak OIDC-Kontos ausfüllen und auf Aktivieren klicken, werden Sie nicht zu Ihrem IdP weitergeleitet.

Überprüfen Sie Ihre Keycloak-Clientkonfiguration.

Die generierten Issuer und Auth Endpoint sind inkorrekt

Ändern Sie im Formular Konfigurieren eines Keycloak OIDC-Kontos Endpunkte in Specify (advanced) und überschreiben Sie die Werte von Issuer und Auth Endpoint. Um die Werte zu finden, gehen Sie zur Keycloak-Konsole, wählen Sie Realm-Einstellungen, wählen Sie die Registerkarte Allgemein und klicken Sie auf OpenID-Endpunktkonfiguration. Die JSON-Ausgabe zeigt Werte für issuer und authorization_endpoint an.

Keycloak-Fehler: "Ungültiger grant_type"

In einigen Fällen kann diese Fehlermeldung irreführend sein und wird durch eine falsche Einstellung des Valid Redirect URI verursacht.

Gruppen können beim Zuweisen globaler Rollen nicht angezeigt werden.

Wenn Sie für die Erstkonfiguration einen Benutzer verwenden, der keiner Gruppe angehört, können Sie beim Versuch, eine globale Rolle zuzuweisen, keine Gruppen suchen. Um dies zu beheben, können Sie entweder:

  1. Das authconfig/keycloakoidc Objekt manuell bearbeiten, um die Gruppensuche zu aktivieren.

    1. Auf dem Rancher-Server:

        kubectl edit authconfigs.management.cattle.io keycloakoidc

    2. Setzen Sie groupSearchEnabled: true.

    3. Speichern Sie die Änderungen.

  2. Konfigurieren Sie Ihr Keycloak OIDC-Setup mit einem Benutzer, der mindestens einer Gruppe in Keycloak zugewiesen ist.

Konfigurieren von OIDC Single Logout (SLO)

Rancher supports the ability to configure OIDC Single Logout (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.

Prerequisites

Before configuring OIDC SLO, ensure the following is set up on your IdP:

  • SLO Support: The Log Out behavior configuration section only appears if your OIDC IdP allows for OIDC SLO.

  • Post-Logout Redirect URI: Your Rancher Server URL must be configured as an authorized post-logout redirect URI in your IdP’s OIDC client settings. This URL is used by the IdP to redirect a user back to Rancher after a successful external logout.

OIDC SLO Configuration

Configure the SLO settings when setting up or editing your OIDC authentication provider.

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

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

  3. In the left navigation menu, select 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.

  5. If you choose to log out of your IdP, provide an End Session Endpoint. Rancher uses this URL to initiate the external logout.

How to get the End Session Endpoint

The end_session_endpoint is one of the specific URLs published within a standardized JSON object containing the IdP’s metadata and is retrieved from the OIDC Discovery URL. To get the end_session_endpoint from the OIDC Discovery URL, follow these steps:

  1. Obtain the Discovery URL by appending the IdP Issuer URL with the well-known path (.well-known/openid-configuration).

  2. Send an HTTP GET request to the Discovery URL.

  3. In the JSON object, look for the key named end_session_endpoint and retrieve the URL.

    You can also use a curl command to retrieve end_session_endpoint:

    curl -s <ISSUER_URL>/.well-known/openid-configuration | jq '.end_session_endpoint'