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.

Generic OIDC konfigurieren

Generisches OpenID Connect (OIDC) ermöglicht es Benutzern, sich bei Rancher mit ihren Anmeldedaten von ihrem bestehenden Konto bei einem OIDC-Identitätsanbieter (IdP) anzumelden. Rancher unterstützt die Integration mit dem OIDC-Protokoll und dem SAML-Protokoll. Beide Implementierungen sind funktional gleichwertig, wenn sie mit Rancher verwendet werden. Die folgenden Anweisungen beschreiben, wie Sie einen OIDC-Client erstellen und Rancher konfigurieren, um mit Ihrem Authentifizierungsanbieter zu arbeiten. Benutzer können sich dann mit ihren Anmeldedaten vom OIDC IdP bei Rancher anmelden.

Voraussetzungen

Identitätsanbieter

In Rancher ist generisches OIDC deaktiviert.

Konsultieren Sie die Dokumentation Ihres spezifischen IdP, um die aufgeführten Voraussetzungen zu erfüllen.

OIDC-Client

Erstellen Sie in Ihrem IdP einen neuen Client mit den folgenden Einstellungen:

Einstellung Wert

Client ID

(z.B. rancher)

Name

(z.B. rancher)

Client Protocol

openid-connect

Access Type

confidential

Valid Redirect URI

https://yourRancherHostURL/verify-auth

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

Die groups und full_group_path Ansprüche, die von den Gruppen- und Gruppenpfad-Mappern generiert werden, die Sie im OIDC-Client in Ihrem Identitätsanbieter erstellen, sollten JSON-Arrays sein, z.B. "groups":["admins","devs","qa"] und "full_group_path":["/admins","/devs","/qa"].

  1. Erstellen Sie einen neuen Groups Mapper mit den folgenden Einstellungen:

    Einstellung Wert

    Name

    Groups Mapper

    Mapper Type

    Group Membership

    Token Claim Name

    groups

    Add to ID token

    OFF

    Add to access token

    OFF

    Add to user info

    ON

  2. Erstellen Sie einen neuen Client Audience mit den folgenden Einstellungen:

    Einstellung Wert

    Name

    Client Audience

    Mapper Type

    Audience

    Included Client Audience

    Add to access token

    ON

  3. Erstellen Sie einen neuen Groups Path mit den folgenden Einstellungen.

    Einstellung Wert

    Name

    Group Path

    Mapper Type

    Group Membership

    Token Claim Name

    full_group_path

    Full group path

    ON

    Add to user info

    ON

Rancher verwendet den Wert, der im "sub" Anspruch empfangen wird, um die PrincipalID zu bilden, die der eindeutige Identifikator in Rancher ist. Es ist wichtig, dies zu einem Wert zu machen, der einzigartig und unveränderlich ist.

Konfigurieren von Generic OIDC in Rancher

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

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

  3. Wählen Sie Generic OIDC aus.

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

  5. Klicken Sie auf Aktivieren.

    Rancher wird Sie zur Anmeldeseite des IdP weiterleiten. Geben Sie Ihre IdP-Anmeldeinformationen ein, 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 Ihrem Anbieter über das OIDC-Protokoll funktioniert. Ihre Benutzer können sich jetzt mit ihren IdP-Anmeldedaten bei Rancher anmelden.

Benutzerdefinierte Anspruchszuordnung

Die benutzerdefinierte Anspruchszuordnung innerhalb der Generic OIDC-Konfiguration wird für name, email und groups Ansprüche unterstützt. Dies ermöglicht es Ihnen, diese OIDC-Ansprüche manuell zuzuordnen, wenn Ihr IdP keine Standardnamen in Token verwendet.

Wie ein benutzerdefinierter Gruppenanspruch funktioniert

Ein benutzerdefinierter Gruppenanspruch beeinflusst, wie Benutzergruppen funktionieren:

  • Wenn sowohl der Standard-OIDC-groups-Anspruch als auch der benutzerdefinierte Gruppenanspruch im Token des Benutzers vorhanden sind, ergänzt der benutzerdefinierte Anspruch die Liste der Gruppen, die durch den Standardanspruch bereitgestellt wird.

  • Wenn im Token kein Standardgruppenanspruch vorhanden ist, bilden die im benutzerdefinierten Anspruch aufgeführten Gruppen die einzigen Gruppen des Benutzers.

Für Gruppen, die aus einem benutzerdefinierten Anspruch stammen, steht keine Suchfunktion zur Verfügung. Um einer dieser Gruppen eine Rolle zuzuweisen, müssen Sie den genauen Namen der Gruppe manuell in das RBAC-Feld eingeben.

Benutzerdefinierte Ansprüche konfigurieren

Wenn Sie sich im Formular OIDC-Konto konfigurieren befinden:

  1. Wählen Sie Benutzerdefinierte Ansprüche hinzufügen.

  2. Fügen Sie Ihre benutzerdefinierten name, email oder groups Ansprüche in das entsprechende Feld für benutzerdefinierte Ansprüche ein.

Wenn Ihr IdP beispielsweise groups in einem Anspruch mit dem Namen custom_roles sendet, geben Sie custom_roles in das Feld für benutzerdefinierte Gruppenansprüche ein. Rancher ergänzt dann den standardmäßigen OIDC-groups Anspruch oder sucht nach diesem spezifischen Anspruch, wenn das Token des Benutzers verarbeitet wird.

Konfigurationsreferenz

Feld Beschreibung

Client-ID

Die Client-ID Ihres OIDC-Clients.

Client-Geheimnis

Das generierte Geheimnis Ihres OIDC-Clients.

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 OIDC-Server aktiviert ist.

Endpunkte

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

Rancher-URL

Die URL für Ihren Rancher-Server.

Aussteller

Die URL Ihres IdP. Wenn Ihr Anbieter die Entdeckung aktiviert hat, verwendet Rancher die Issuer-URL, um alle erforderlichen URLs abzurufen.

Auth-Endpunkt

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

Benutzerdefinierte Ansprüche

Benutzerdefiniertes Anspruchsfeld Standard OIDC Anspruch Beschreibung des benutzerdefinierten Anspruchs

Benutzerdefinierter Namensanspruch

name

Der Name des Anspruchs im OIDC-Token, der den vollständigen Namen oder den Anzeigenamen des Benutzers enthält.

Benutzerdefinierter E-Mail-Anspruch

email

Der Name des Anspruchs im OIDC-Token, der die E-Mail-Adresse des Benutzers enthält.

Benutzerdefinierter Gruppenanspruch

groups

Der Name des Anspruchs im OIDC-Token, der die Gruppenmitgliedschaften des Benutzers enthält (verwendet für RBAC).

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.

Fehlerbehebung

Wenn Sie Probleme beim Testen der Verbindung zum OIDC-Server haben, überprüfen Sie zuerst die Konfiguration 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 generischen OIDC-bezogenen Protokolleinträge werden entweder mit [generic oidc] oder [oidc] vorangestellt.

Sie werden nicht zu Ihrem Authentifizierungsanbieter umgeleitet.

Wenn Sie das Formular Ein generisches OIDC-Konto konfigurieren ausfüllen und auf Aktivieren klicken und nicht zu Ihrem IdP umgeleitet werden, überprüfen Sie die Konfiguration Ihres OIDC-Clients.

Die generierten Issuer und Auth Endpoint sind inkorrekt

Wenn die Issuer und Auth Endpoint inkorrekt generiert werden, öffnen Sie das Formular Ein OIDC-Konto konfigurieren, ändern Sie Endpunkte zu Specify (advanced) und überschreiben Sie den Issuer Wert.

Fehler: "Ungültiger grant_type"

In einigen Fällen kann die Fehlermeldung "Ungültiger grant_type" irreführend sein und wird tatsächlich durch eine falsche Einstellung des Valid Redirect URI verursacht.

Konfiguration 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'