この文書は自動機械翻訳技術を使用して翻訳されています。 正確な翻訳を提供するように努めておりますが、翻訳された内容の完全性、正確性、信頼性については一切保証いたしません。 相違がある場合は、元の英語版 英語 が優先され、正式なテキストとなります。

Keycloak (OIDC) を設定する

組織がユーザー認証に Keycloak アイデンティティプロバイダー (IdP) を使用している場合、Rancher を設定してユーザーが IdP の資格情報を使用してログインできるようにすることができます。Rancher は OpenID Connect (OIDC) プロトコルと SAML プロトコルを使用した Keycloak との統合をサポートしています。両方の実装は、Rancher で使用する際に機能的に同等です。このページでは、OIDC プロトコルを使用して Rancher を Keycloak と連携させるための設定手順を説明します。

SAML プロトコルを使用して Keycloak を利用したい場合は、このページを参照してください。

既存の SAML プロトコルを使用した設定があり、OIDC プロトコルに切り替えたい場合は、このセクションを参照してください。

前提条件

  • Rancher では、Keycloak (SAML) は無効になっています。

  • Keycloak IdP サーバー を設定する必要があります。

  • 以下の設定で新しい OIDC クライアントを作成するには、 Keycloak ドキュメントに従ってください。

    設定 値

    Client ID

    <client-id> (例: rancher)

    Name

    <client-name> (例: rancher)

    Client type

    OpenID Connect

    Client authentication

    ON

    Valid Redirect URI

    https://yourRancherHostURL/verify-auth

  • 新しい OIDC クライアントで、ユーザーのフィールドを公開するために マッパー を作成します。

    1. ナビゲーションメニューで、クライアント をクリックします。

    2. クライアントリスト タブをクリックします。

    3. 作成したクライアントを見つけてクリックします。

    4. クライアントスコープ タブをクリックします。

    5. `<client-name>-dedicated`とラベル付けされたリンクを見つけてクリックします。例えば、クライアントに`rancher`という名前を付けた場合、`rancher-dedicated`という名前のリンクを探します。

    6. マッパータブをクリックします。

    7. 新しいマッパーを設定するをクリックします。既存のマッパーが設定されている場合は、Add mapperの隣にある矢印をクリックして、設定によるを選択します。このプロセスを繰り返し、次のマッパーを作成します：

      • マッピングテーブルから、グループメンバーシップを選択し、以下の設定で新しい「グループマッパー」を設定します。言及されていない設定については、デフォルト値を使用してください。

        設定 値

        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

      • マッピングテーブルから、オーディエンスを選択し、以下の設定で新しい「クライアントオーディエンス」を設定します。言及されていない設定については、デフォルト値を使用してください。

        設定 値

        Name

        Client Audience

        Mapper Type

        Audience

        Included Client Audience

        <client-name>

        Add to ID token

        OFF

        Add to access token

        ON

      • マッピングテーブルから、グループメンバーシップを選択し、以下の設定で新しい「グループパス」を設定します。言及されていない設定については、デフォルト値を使用してください。

        設定 値

        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

  • Keycloakユーザーをクエリする必要があるすべてのユーザーまたはグループに、次のロールマッピングを追加します。

    • ユーザ

    • グループ

    1. ナビゲーションメニューで、ユーザーをクリックします。

    2. ロールマッピングを追加したいユーザーをクリックします。

    3. ロールマッピングタブをクリックします。

    4. ロールを割り当てるをクリックします。

    5. 次のロールを選択します：

      • query-users

      • query-groups

      • view-users

    6. 割り当てるをクリックします。

    1. ナビゲーションメニューで、グループをクリックします。

    2. ロールマッピングを追加したいグループをクリックします。

    3. ロールマッピングタブをクリックします。

    4. ロールを割り当てるをクリックします。

    5. 次のロールを選択します：

      • query-users

      • query-groups

      • view-users

    6. 割り当てるをクリックします。

RancherでのKeycloakの設定

  1. Rancher UIで、*☰ > ユーザーと認証*をクリックします。

  2. 左のナビゲーションバーで、*認証プロバイダー*をクリックします。

  3. *Keycloak (OIDC)*を選択します。

  4. *Keycloak OIDCアカウントの設定*フォームに入力します。フォームの記入に関するヘルプは、設定リファレンスを参照してください。

    生成オプションを使用してエンドポイントセクションを設定する際、Rancherは`/auth`を発行者および認証エンドポイントフィールドのコンテキストパスの一部として含めます。これはKeycloak 16またはそれ以前のバージョンにのみ有効です。 Keycloak 17以降のバージョンでは、指定オプションを使用してエンドポイントを設定する必要があります。これらは Quarkusに移行されたものです。

  5. *Keycloak OIDCアカウントの設定*フォームに入力した後、*有効化*をクリックします。

    RancherはIdPログインページにリダイレクトします。RancherのKeycloak設定を検証するために、Keycloak IdPで認証される資格情報を入力します。

    IdPログインページを見るためにポップアップブロッカーを無効にする必要があるかもしれません。

*結果:*RancherはOIDCプロトコルを使用してKeycloakと連携するように設定されています。ユーザーはKeycloakのログイン情報を使用してRancherにサインインできるようになりました。

構成リファレンス

フィールド 説明

クライアントID

あなたのKeycloakクライアントの`Client ID`。

クライアントシークレット

あなたのKeycloakクライアントの生成された`Secret`。Keycloakコンソールで、*クライアント*を選択し、作成したクライアントを選択し、*資格情報*タブを選択して`Secret`フィールドの値をコピーします。

秘密鍵 / 証明書

RancherとあなたのIdPの間に安全な接続を作成するための鍵/証明書ペアです。KeycloakサーバーでHTTPS/SSLが有効になっている場合は必須です。

エンドポイント

Rancher URL、Issue、および`Auth Endpoint`フィールドに生成された値を使用するか、誤っている場合は手動で上書きするかを選択してください。

Keycloak URL

あなたのKeycloakサーバーのURLです。

Keycloakレルム

Keycloakクライアントが作成されたレルムの名前です。

Rancher URL

あなたのRancherサーバーのURLです。

［発行者］

あなたのIdPのURLです。

認証エンドポイント

ユーザーが認証するためにリダイレクトされるURLです。

SAMLからOIDCへの移行

このセクションでは、RancherをKeycloak（SAML）からKeycloak（OIDC）に移行するプロセスについて説明します。

  1. Keycloakを再構成します。

    1. 前提条件に従って新しい`OpenID Connect`クライアントを構成します。同じ`Valid Redirect URIs`が設定されていることを確認してください。

    2. 前提条件に従って新しいクライアントのマッパーを構成します。

  2. RancherをKeycloak（OIDC）を使用するように構成する前に、最初にKeycloak（SAML）を無効にする必要があります。

    1. Rancher UIで、☰ > ユーザーと認証をクリックします。

    2. 左のナビゲーションバーで、認証プロバイダーをクリックします。

    3. Keycloak (SAML)を選択します。

    4. 無効をクリックします。

  3. RancherにおけるKeycloakの設定の手順に従ってください。

    設定が完了した後、Rancherのユーザー権限は自動的に移行されないため、再適用する必要があります。

PKCE拡張のためのOIDCサポート

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.

付録：トラブルシューティング

Keycloakサーバーへの接続をテストしている際に問題が発生した場合は、まずOIDCクライアントの設定オプションを再確認してください。Rancherのログを確認して、問題の原因を特定する手助けをすることもできます。デバッグログには、エラーに関するより詳細な情報が含まれている場合があります。このドキュメントのデバッグログを有効にする方法を参照してください。

すべてのKeycloak関連のログエントリは、[generic oidc]`または[keycloak oidc]`で前置きされています。

Keycloakにリダイレクトされません

*Keycloak OIDCアカウントの設定*フォームに記入し、*有効化*をクリックすると、IdPにリダイレクトされません。

Keycloakクライアントの設定を確認してください。

生成された`Issuer`と`Auth Endpoint`は不正確です。

*Keycloak OIDCアカウントの設定*フォームで、*エンドポイント*を`Specify (advanced)`に変更し、`Issuer`と`Auth Endpoint`の値を上書きしてください。値を見つけるには、Keycloakコンソールに移動し、*レルム設定*を選択し、*一般*タブを選択し、*OpenIDエンドポイント設定*をクリックします。JSON出力には、`issuer`と`authorization_endpoint`の値が表示されます。

Keycloakエラー："Invalid grant_type"

場合によっては、このエラーメッセージは誤解を招く可能性があり、`Valid Redirect URI`を不正に設定したことが原因です。

グローバルロールを割り当てる際にグループが見えない

初期設定のためにグループに属さないユーザーを使用すると、グローバルロールを割り当てようとしたときにグループを検索できません。これを解決するには、次のいずれかを行うことができます：

  1. `authconfig/keycloakoidc`オブジェクトを手動で編集して、グループ検索を有効にします。

    1. Rancherサーバーで：

        kubectl edit authconfigs.management.cattle.io keycloakoidc

    2. `groupSearchEnabled: true`を設定してください。

    3. 変更を保存します。

  2. Keycloakで少なくとも1つのグループに割り当てられたユーザーを使用して、Keycloak OIDCセットアップを再構成してください。

OIDCシングルログアウト（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'