検索
サポートコンソール開発者トライアルの開始お問い合わせ

第12章 OpenID Connect および SAML クライアントの管理

download PDF

クライアントは、ユーザーの認証を要求できるエンティティーです。クライアントは 2 つの形式で提供されます。クライアントの最初のタイプは、single-sign-on に参加するアプリケーションです。これらのクライアントが Red Hat build of Keycloak に期待するのは、セキュリティーの提供のみです。他のタイプのクライアントは、認証されたユーザーの代わりに他のサービスを呼び出すことができるように、アクセストークンを要求するものです。このセクションでは、クライアントの設定に関するさまざまな側面と、その方法について説明します。

12.1. OpenID Connect クライアントの管理

OpenID Connect は、アプリケーションのセキュリティーを保護するのに推奨されるプロトコルです。Web でも簡単に使用できるように、ゼロから設計されているので、HTML5/JavaScript アプリケーションで最適に動作します。

12.1.1. OpenID Connect クライアントの作成

OpenID 接続プロトコルを使用するアプリケーションを保護するには、クライアントを作成します。

手順

  1. メニューで Clients をクリックします。

  2. Create client をクリックします

    Create client

    Create Client

  3. Client type を OpenID Connect に設定したままにします。

  4. Client ID を入力します。

    この ID は、OIDC リクエストおよび Red Hat build of Keycloak データベースでクライアントを識別するために使用される英数字の文字列です。

  5. クライアントの Name を指定します。

    この名前をローカライズする予定がある場合は、置換文字列値を設定します。たとえば、${myapp} などの文字列値です。詳細は、サーバー開発者ガイド を参照してください。

  6. Save をクリックします。

この操作により、クライアントが作成され、Basic configuration を実行できる Settings タブが表示されます。

12.1.2. Basic configuration

Settings タブには、このクライアントを設定するための多くのオプションが含まれています。

Settings タブ

Settings tab

12.1.2.1. 一般設定

Client ID
OIDC リクエストおよび Red Hat build of Keycloak データベースでクライアントを識別するために使用される英数字の ID 文字列です。
名前
Red Hat build of Keycloak UI 画面に表示されるクライアントの名前。名前をローカライズするには、代替文字列値を設定します。たとえば、${myapp} などの文字列値です。詳細は、サーバー開発者ガイド を参照してください。
Description
クライアントの説明。この設定はローカライズすることもできます。
Always Display in Console
このユーザーがアクティブなセッションを持っていない場合でも、常にこのクライアントをアカウントコンソールにリストします。

12.1.2.2. Access Settings

Root URL
Red Hat build of Keycloak が設定済みの相対 URL を使用する場合、その背tン等にこの値が追加されます。
Home URL
認証サーバーがクライアントにリダイレクトまたはリンクバックする必要がある場合のデフォルト URL を提供します。
Valid Redirect URIs

必須フィールド。URL パターンを入力し、+ をクリックして既存の URL を追加し、-、Save の順にクリックします。有効なリダイレクト URI を比較するために、正確な (大文字と小文字を区別する) 文字列一致が使用されます。

URL パターンの最後にワイルドカードを使用できます。たとえば、http://host.com/path/* です。セキュリティー上の問題を回避するために、渡されたリダイレクト URI に userinfo 部分が含まれている場合、またはその path が親ディレクトリー (/../) へのアクセスを管理する場合、ワイルドカードの比較は実行されず、標準の安全な正確な文字列一致が実行されます。

完全なワイルドカード * 有効なリダイレクト URI を設定して、任意の http または https リダイレクト URI を許可することもできます。実稼働環境では使用しないでください。

通常、排他的リダイレクト URI パターンの方が安全です。詳細は unspecific Redirect URIs を参照してください。

Web Origins

URL パターンを入力し、+ をクリックして既存の URL を追加し、- をクリックして削除します。Save をクリックします。

このオプションは、CORS(Cross-Origin Resource Sharing) を処理します。ブラウザーの JavaScript が、JavaScript コードの元のドメインとは異なるドメインを持つサーバーに対して AJAX HTTP リクエストを試行する場合、リクエストは CORS を使用する必要があります。サーバーは、CORS リクエストを処理する必要があります。処理しないと、ブラウザーは表示されず、リクエストの処理を許可しません。このプロトコルは、XSS、CSRF、およびその他の JavaScript ベースの攻撃から保護します。

ここに記載のドメイン URL は、クライアントアプリケーションに送信されたアクセストークン内に埋め込まれています。クライアントアプリケーションはこの情報を使用して、CORS リクエストの呼び出しを許可するかどうかを決定します。Red Hat build of Keycloak クライアントアダプターのみがこの機能をサポートしています。詳細は、アプリケーションおよびサービスの保護ガイド を参照してください。

Admin URL
クライアントのコールバックエンドポイント。サーバーは、この URL を使用して失効ポリシーのプッシュ、バックチャネルログアウトの実行などのコールバックを行います。Red Hat build of Keycloak サーブレットアダプターの場合、この URL をサーブレットアプリケーションのルート URL にできます。詳細は、アプリケーションおよびサービスの保護ガイド を参照してください。

12.1.2.3. 機能設定

クライアント認証

OIDC クライアントのタイプ。

  • ON

    ブラウザーログインを実行し、アクセストークン要求の実行時にクライアントシークレットを必要とするサーバー側のクライアントの場合。この設定はサーバー側のアプリケーションに使用する必要があります。

  • OFF

    ブラウザーログインを実行するクライアント側のクライアントの場合。クライアント側のクライアントでシークレットを安全に保つことができないため、正しいリダイレクト URI を設定してアクセスを制限することが重要です。

Authorization
このクライアントに対する詳細な認可サポートを有効または無効にします。
Standard Flow
有効にすると、このクライアントは OIDC Authorization Code Flow を使用できます。
Direct Access Grants
有効にすると、このクライアントは OIDC Direct Access Grants を使用できます。
Implicit Flow
有効にすると、このクライアントは OIDC Implicit Flow を使用できます。
Service account roles
有効にすると、このクライアントは Red Hat build of Keycloak に対して認証を行い、このクライアント専用のアクセストークンを取得できます。OAuth2 仕様の観点から、これにより、このクライアントに対する Client Credentials Grant のサポートが有効になります。
Auth 2.0 Device Authorization Grant
有効にすると、このクライアントは OIDC Device Authorization Grant を使用できます。
OIDC CIBA Grant
有効にすると、このクライアントは OIDC Client Initiated Backchannel Authentication Grant を使用できます。

12.1.2.4. ログイン設定

Login theme
ログイン、OTP、許可登録、およびパスワードを忘れたページに使用するテーマ。
Consent required

有効にすると、ユーザーはクライアントアクセスに同意する必要があります。

ブラウザーログインを実行するクライアント側のクライアントの場合。クライアント側のクライアントでシークレットを安全に保つことができないため、正しいリダイレクト URI を設定してアクセスを制限することが重要です。

Display client on screen

このスイッチは、Consent Required が Off の場合に適用されます。

  • Off

    同意画面には、設定されたクライアントスコープに対応する同意のみが含まれます。

  • On

    同意画面には、このクライアント自体に関する項目も 1 つあります。

Client consent screen text
Consent required と Display client on screen が有効になっている場合に適用されます。このクライアントの権限に関する同意画面に表示されるテキストが含まれます。

12.1.2.5. ログアウト設定

Front channel logout
Front Channel Logout が有効になっている場合、アプリケーションは、OpenID Connect フロントチャネルログアウト 仕様に従って、フロントチャネルを介してユーザーをログアウトできる必要があります。有効になっている場合は、フロントチャネルログアウト URL も指定する必要があります。
Front-channel logout URL
フロントチャネルを介してクライアントにログアウト要求を送信するために Red Hat build of Keycloak が使用する URL。
Backchannel logout URL
ログアウト要求がこのレルムに (end_session_endpoint 経由で) 送信されたときにクライアントが自分自身をログアウトさせる URL。省略した場合、ログアウト要求はクライアントに送信されません。
Backchannel logout session required
Backchannel Logout URL が使用されている場合に、ログアウトトークンにセッション ID クレームを含めるかどうかを指定します。
Backchannel logout revoke offline sessions
バックチャネルログアウト URL が使用される場合に、revoke_offline_access イベントをログアウトトークンに含めるかどうかを指定します。Red Hat build of Keycloak は、このイベントでログアウトトークンを受信すると、オフラインセッションを取り消します。

12.1.3. 詳細設定

Settings タブのフィールドに入力したら、他のタブを使用して高度な設定を実行できます。

12.1.3.1. Advanced タブ

Advanced タブをクリックすると、追加のフィールドが表示されます。特定のフィールドの詳細は、そのフィールドの疑問符アイコンをクリックしてください。ただし、特定のフィールドは、このセクションで詳しく説明します。

12.1.3.2. Fine grain OpenID Connect configuration

Logo URL

クライアントアプリケーションのロゴを参照する URL。

Policy URL

プロファイルデータがどのように使用されるかについて読むために、証明書利用者クライアントがエンドユーザーに提供する URL。

Terms of Service URL

依拠当事者の利用規約について読むために、依拠当事者クライアントがエンドユーザーに提供する URL。

Signed and Encrypted ID Token Support

Red Hat build of Keycloak は、Json Web Encryption (JWE) 仕様に従って ID トークンを暗号化できます。管理者は、各クライアントに対して ID トークンが暗号化されているかどうかを判断します。

ID トークンの暗号化に使用されるキーは、コンテンツ暗号化キー (CEK) です。Red Hat build of Keycloak およびクライアントは、使用する CEK とその配信方法をネゴシエートする必要があります。CEK の決定に使用されるメソッドはキー管理モードです。Red Hat build of Keycloak がサポートするキー管理モードは、キー暗号化です。

キーの暗号化の場合:

  1. クライアントは非対称暗号キーペアを生成します。
  2. 公開鍵は CEK の暗号化に使用されます。
  3. Red Hat build of Keycloak は ID トークンごとに CEK を生成します
  4. Red Hat build of Keycloak は、この生成された CEK を使用して ID トークンを暗号化します
  5. Red Hat build of Keycloak は、クライアントの公開鍵を使用して CEK を暗号化します。
  6. クライアントは、秘密鍵を使用して暗号化された CEK を復号します。
  7. クライアントは復号化された CEK を使用して ID トークンを復号化します。

クライアント以外のパーティーは ID トークンを復号化できます。

クライアントは、CEK を暗号化する公開鍵を Red Hat build of Keycloak に渡す必要があります。Red Hat build of Keycloak は、クライアントが提供する URL からの公開鍵のダウンロードをサポートします。クライアントは、Json Web Keys(JWK) 仕様に従って公開鍵を提供する必要があります。

手順は以下のとおりです。

  1. クライアントの Keys タブを開きます。
  2. JWKS URL を ON に切り替えます。
  3. JWKS URL テキストボックスにクライアントの公開鍵 URL を入力します。

キー暗号化のアルゴリズムは、Json Web Algorithm (JWA) 仕様で定義されています。Red Hat build of Keycloak は以下をサポートします。

  • RSAES-PKCS1-v1_5(RSA1_5)
  • デフォルトパラメーターを使用した RSAES OAEP(RSA-OAEP)
  • SHA-256 と MFG1(RSA-OAEP-256) を使用した RSAES OAEP 256

アルゴリズムを選択する手順は次のとおりです。

  1. クライアントの Advanced タブを開きます。
  2. Fine Grain OpenID Connect Configuration を開きます。
  3. ID Token Encryption Content Encryption Algorithm プルダウンメニューからアルゴリズムを選択します。

12.1.3.3. OpenID Connect 互換モード

このセクションは下位互換性のために存在します。各フィールドの詳細については、疑問符アイコンをクリックしてください。

OAuth 2.0 Mutual TLS Certificate Bound Access Tokens Enabled

相互 TLS は、アクセストークンと更新トークンをクライアント証明書と共にバインドします。クライアント証明書は、TLS ハンドシェイク時に交換されます。このバインディングは、攻撃者が盗まれたトークンを使用するのを防ぎます。

このタイプのトークンは holder-of-key トークンです。Bearer トークンとは異なり、holder-of-key トークンの受信側は、トークンの送信側が正当であるかどうかを検証できます。

この設定が有効な場合に、ワークフローは以下のようになります。

  1. トークンリクエストが、認可コードフローまたはハイブリッドフローのトークンエンドポイントに送信されます。
  2. Red Hat build of Keycloak はクライアント証明書を要求します。
  3. Red Hat build of Keycloak はクライアント証明書を受け取ります。
  4. Red Hat build of Keycloak はクライアント証明書を正常に検証します。

検証が失敗した場合、Red Hat build of Keycloak はトークンを拒否します。

次の場合、Red Hat build of Keycloak は、アクセストークンまたは更新トークンを送信するクライアントを検証します。

  • トークンの更新リクエストは、holder-of-key 更新トークンでトークンエンドポイントに送信されます。
  • UserInfo リクエストは、holder-of-key アクセストークンで UserInfo エンドポイントに送信されます。
  • ログアウト要求は、holder-of-key リフレッシュトークンで、OIDC に準拠していない Red Hat build of Keycloak 独自のログアウトエンドポイントに送信されます。

詳細は、OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens の Mutual TLS Client Certificate Bound Access Tokens を参照してください。

注記

現在、Red Hat build of Keycloak クライアントアダプターは、キー所有者のトークン検証をサポートしていません。Red Hat build of Keycloak アダプターは、アクセストークンと更新トークンをベアラートークンとして扱います。

OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)

DPoP は、アクセストークンと更新トークンをクライアントのキーペアの公開部分とバインドします。このバインディングは、攻撃者が盗まれたトークンを使用するのを防ぎます。

このタイプのトークンは holder-of-key トークンです。Bearer トークンとは異なり、holder-of-key トークンの受信側は、トークンの送信側が正当であるかどうかを検証できます。

クライアントスイッチ OAuth 2.0 DPoP Bound Access Tokens Enabled がオンの場合、次のようなワークフローになります。

  1. トークンリクエストが、認可コードフローまたはハイブリッドフローのトークンエンドポイントに送信されます。
  2. Red Hat build of Keycloak が DPoP 証明を要求します。
  3. Red Hat build of Keycloak が DPoP 証明を受け取ります。
  4. Red Hat build of Keycloak が DPoP 証明の検証に成功します。

検証が失敗した場合、Red Hat build of Keycloak はトークンを拒否します。

スイッチ OAuth 2.0 DPoP Bound Access Tokens Enabled がオフの場合でも、クライアントはトークン要求で DPoP 証明を送信できます。その場合、Red Hat build of Keycloak は DPoP 証明を検証し、トークンにサムプリントを追加します。ただし、スイッチがオフの場合、このクライアントの Red Hat build of Keycloak サーバーによって DPoP バインディングが適用されません。特定のクライアントに常に DPoP バインディングを使用させる場合は、このスイッチをオンにすることを推奨します。

次の場合、Red Hat build of Keycloak は、アクセストークンまたは更新トークンを送信するクライアントを検証します。

  • トークンの更新リクエストは、holder-of-key 更新トークンでトークンエンドポイントに送信されます。この検証は、DPoP 仕様で説明されているように、パブリッククライアントに対してのみ実行されます。機密クライアントの場合、検証は実行されません。要求が正当なクライアントからのものであることを確認するために、適切なクライアント認証情報を使用したクライアント認証が実行されるためです。パブリッククライアントの場合、アクセストークンと更新トークンの両方が DPoP にバインドされます。機密クライアントの場合、アクセストークンのみが DPoP にバインドされます。
  • UserInfo リクエストは、holder-of-key アクセストークンで UserInfo エンドポイントに送信されます。
  • ログアウト要求は、holder-of-key リフレッシュトークンで、OIDC に準拠していない Red Hat build of Keycloak 独自のログアウトエンドポイントに送信されます。この検証は、上記のようにパブリッククライアントに対してのみ実行されます。

詳細は、OAuth 2.0 Demonstrating Proof of Possession (DPoP) を参照してください。

注記

現在、Red Hat build of Keycloak クライアントアダプターは、DPoP holder-of-key トークン検証をサポートしていません。Red Hat build of Keycloak アダプターは、アクセストークンと更新トークンをベアラートークンとして扱います。

注記

DPoP は テクノロジープレビュー であり、完全にはサポートされていません。デフォルトでは無効になっています。

有効にするには、--features=preview または --features=dpop を使用してサーバーを起動します。

OIDC の詳細設定

OpenID Connect の詳細設定を使用すると、クライアントレベルで セッションタイムアウトとトークンタイムアウト のオーバーライドを設定できます。

Advanced Settings

設定説明

Access Token Lifespan

この値は、同じ名前のレルムオプションをオーバーライドします。

Client Session Idle

この値は、同じ名前のレルムオプションをオーバーライドします。この値は、グローバルの SSO Session Idle よりも小さくする必要があります。

Client Session Max

この値は、同じ名前のレルムオプションをオーバーライドします。この値は、グローバルの SSO Session Max よりも小さくする必要があります。

Client Offline Session Idle

この設定を使用すると、クライアントのオフラインセッションのアイドルタイムアウトを短く設定できます。タイムアウトは、Red Hat build of Keycloak がオフライントークンを取り消すまで、セッションがアイドル状態に留まる時間です。設定されていない場合、レルムの Offline Session Idle が使用されます。

Client Offline Session Max

この設定を使用すると、クライアントのオフラインセッションの最大ライフスパンを短く設定できます。ライフスパンは、Red Hat build of Keycloak が対応するオフライントークンを取り消すまでの最大時間です。このオプションを使用するには、レルム内でグローバルに Offline Session Max Limited が有効になっている必要があります。デフォルトは Offline Session Max です。

Proof Key for Code Exchange Code Challenge Method

攻撃者が正当なクライアントの認可コードを盗んだ場合には、PKCE (Proof Key for Code Exchange) により、コードに適用されるトークンを、攻撃者が受け取れないようにします。

管理者は、以下のオプションのいずれかを選択できます。

(blank)
Red Hat build of Keycloak は、クライアントが Offline Session Idle の認証エンドポイントに適切な PKCE パラメーターを送信しなければ、PKCE を適用しません。
S256
Red Hat build of Keycloak は、コードチャレンジメソッドが S256 であるクライアント PKCE に適用されます。
plain
Red Hat build of Keycloak は、コードチャレンジメソッドが plain のクライアント PKCE に適用されます。

詳細は、OAuth パブリッククライアントによるコード Exchange の RFC 7636 Proof キー を参照してください。

ACR から認証レベル (LoA) へのマッピング

クライアントの詳細設定では、どの Authentication Context Class Reference (ACR) 値をどの Level of Authentication (LoA) マップするかを定義できます。このマッピングは、ACR から LoA へのマッピング で説明されているように、レルムでも指定できます。ベストプラクティスは、このマッピングをレルムレベルで設定することです。これにより、複数のクライアント間で同じ設定を共有できます。

Default ACR Values を使用すると、acr_values パラメーターと、acr クレームがアタッチされた claims パラメーターがない状態で、ログイン要求がこのクライアントから Red Hat build of Keycloak に送信される場合のデフォルト値を指定できます。公式の OIDC 動的クライアント登録仕様 を参照してください。

警告

デフォルトの ACR 値がデフォルトのレベルとして使用されますが、特定のレベルでのログインを強制するために確実に使用できるわけではないことに注意してください。たとえば、Default ACR Values をレベル 2 に設定するとします。次に、デフォルトで、ユーザーはレベル 2 で認証する必要があります。ただし、ユーザーが acr_values=1 などのログイン要求にパラメーターを明示的にアタッチすると、レベル 1 が使用されます。その結果、クライアントが本当にレベル 2 を必要とする場合、クライアントは ID トークン内の acr クレームの存在を確認し、要求されたレベル 2 が含まれていることを再確認することが推奨されます。

ACR to LoA mapping

詳細は、Step-up Authentication と 公式の OIDC 仕様 を参照してください。

12.1.4. 機密なクライアント認証情報

クライアントの Client authentication がON に設定されている場合は、クライアントの認証情報を Credentials タブで設定する必要があります。

認証情報タブ

Credentials Tab

Client Authenticator ドロップダウンリストは、クライアントに使用する認証情報のタイプを指定します。

クライアント ID およびシークレット

この選択はデフォルトの設定です。シークレットは自動的に生成されます。必要に応じて、Regenerate をクリックしてシークレットを再作成します。

署名付き JWT

Signed JWT

署名済み JWT は Signed Json Web Token です。

この認証情報タイプを選択すると、Keys タブでクライアントの秘密鍵と証明書も生成する必要があります。秘密鍵は JWT に署名するために使用されます。一方、証明書は、署名の検証にサーバーによって使用されます。

keys タブ

Keys tab

Generate new keys ボタンをクリックして、このプロセスを開始します。

キーの生成

generate client keys

  1. 使用するアーカイブ形式を選択します。
  2. 鍵パスワード を入力します。
  3. ストアパスワード を入力します。
  4. Generate をクリックします。

これらの鍵を生成する場合、Red Hat build of Keycloak は証明書を保存し、ユーザーはクライアントが使用する秘密鍵と証明書をダウンロードする必要があります。

外部ツールを使用して鍵を生成し、Import Certificate をクリックしてクライアントの証明書をインポートすることもできます。

証明書のインポート

Import Certificate

  1. 証明書のアーカイブ形式を選択します。
  2. ストアパスワードを入力します。
  3. Import File をクリックして証明書ファイルを選択します。
  4. Import をクリックします。

JWKS URL を使用 をクリックすると、証明書をインポートする必要がなくなります。この場合、公開鍵が JWK 形式で公開される URL を指定できます。このオプションを使用すると、鍵が変更されると Red Hat build of Keycloak はキーを再インポートします。

Red Hat build of Keycloak アダプターで保護されたクライアントを使用している場合は、https://myhost.com/myapp がクライアントアプリケーションのルート URL であると仮定して、この形式で JWKS URL を設定できます。 

https://myhost.com/myapp/k_jwks

詳細は、サーバー開発者ガイド を参照してください。

クライアントシークレットでの署名済み JWT

このオプションを選択する場合は、秘密鍵の代わりにクライアントシークレットで署名された JWT を使用できます。

このクライアントシークレットは、クライアントによって JWT に署名するために使用されます。

X509 証明書

Red Hat build of Keycloak は、TLS ハンドシェイク中にクライアントが適切な X509 証明書を使用しているか検証します。

X509 証明書

x509 client auth

バリデーターは、設定された正規表現検証式を使用して、証明書のサブジェクト DN フィールドも確認します。いくつかのユースケースでは、すべての証明書を受け入れるだけで十分です。この場合は、(.*?)(?:$) 式を使用できます。

Red Hat build of Keycloak では、次の 2 つの方法でリクエストからクライアント ID を取得できます。

  • クエリー内の client_id パラメーター (OAuth 2.0 仕様 のセクション 2.2 で説明されています)。
  • client_id をフォームパラメーターとして指定します。

12.1.5. クライアントのシークレットローテーション

重要

クライアントシークレットローテーションのサポートは開発中であることに注意してください。この機能は実験的に使用してください。

Confidential Client authentication を使用するクライアントの場合、Red Hat build of Keycloak は、クライアントポリシー を通じてクライアントシークレットをローテーションする機能をサポートします。

クライアントシークレットローテーションポリシーは、シークレットの漏えいなどの問題を軽減するため、セキュリティーが強化されます。有効にすると、Red Hat build of Keycloak ではクライアントごとに最大 2 つの同時アクティブシークレットがサポートされます。ポリシーは、以下の設定に従ってローテーションを管理します。

  • シークレットの有効期限: [秒]:- シークレットがローテーションされると、これは新しいシークレットの有効期限です。シークレット作成日に追加された量 (秒単位)。ポリシー実行時に計算されます。
  • ローテーションされたシークレットの有効期限: [秒]: シークレットがローテーションされた場合、この値は古いシークレットの残りの有効期限です。この値は、常にシークレットの有効期限よりも小さくする必要があります。値が 0 の場合、クライアントのローテーション時に古いシークレットはすぐに削除されます。シークレットローテーションの日付に追加された量 (秒単位)。ポリシー実行時に計算されます。
  • 更新中のローテーションの残りの有効期限: [秒]: 動的クライアントへの更新でクライアントシークレットローテーションを実行する必要がある期間。ポリシー実行時に計算されます。

クライアントシークレットのローテーションが発生すると、新規のメインシークレットが生成され、古いクライアントシークレットが新しい有効期限を持つセカンダリーシークレットになります。

12.1.5.1. クライアントシークレットローテーションのルール

ローテーションは自動的に行われないか、バックグラウンドプロセスを介して行われません。ローテーションを実行するには、Red Hat build of Keycloak 管理コンソールにおけるクライアントの認証情報タブで Regenerate Secret 機能を使用するか、Admin REST API を使用して、クライアント上で更新アクションを実行する必要があります。クライアント更新アクションを呼び出すと、シークレットのローテーションはルールに基づいて行われます。

  • シークレットの有効期限の値が現在の日付未満の場合。
  • 動的クライアント登録クライアント更新要求中に、更新中のローテーションの残りの有効期限 の値が現在の日付と シークレットの有効期限 の間の期間と一致する場合、クライアントシークレットは自動的にローテーションされます。

さらに、Admin REST API を介して、いつでもクライアントシークレットローテーションを強制することができます。

注記

新規クライアントの作成時に、クライアントシークレットのローテーションポリシーがアクティブになると、動作が自動的に適用されます。

警告

シークレットローテーション動作を既存のクライアントに適用するには、ポリシーを定義した後でそのクライアントを更新して、動作が適用されるようにします。

12.1.6. OIDC クライアントシークレットローテーションポリシーの作成

以下は、シークレットローテーションポリシーを定義する例です。

手順

  1. メニューで Realm Settings をクリックします。
  2. Client Policies タブをクリックします。

  3. Profiles ページで、Create client profile をクリックします。

    プロファイルの作成

    Create Client Profile

  4. Name に任意の名前を入力します。
  5. Description のプロファイルの目的を特定するのに役立つ説明を入力します。

  6. Save をクリックします。

    このアクションによりプロファイルが作成され、エグゼキューターを設定できます。

  7. Add executor をクリックして、このプロファイルにエグゼキューターを設定します。

    プロファイルエグゼキューターを作成する

    Client Profile Executor

  8. Executor Type に secret-rotation を選択します。
  9. Secret Expiration の各シークレットの最大継続時間を秒単位で入力します。

  10. Rotated Secret Expiration について、ローテーションされた各シークレットの最大継続時間を秒単位で入力します。

    警告

    Rotated Secret Expiration の値は、常に Secret Expiration りも小さくする必要があることに注意してください。

  11. 更新アクションがクライアントの RemainExpirationTime を更新するまでの時間を秒単位で入力します。

  12. Add をクリックします。

    上記の例では、以下のようになります。

    • 各シークレットは 1 週間で有効です。
    • ローテーションされたシークレットは 2 日後に有効期限が切れます。
    • 動的クライアントを更新するウィンドウは、シークレットの有効期限が切れる前に 1 日後に開始します。
  13. Client Policies タブに戻ります。
  14. Policies をクリックします。

  15. Create client policy をクリックします。

    クライアントシークレットローテーションポリシーの作成

    Client Rotation Policy

  16. Name に任意の名前を入力します。
  17. Description のポリシーの目的を特定するのに役立つ説明を入力します。

  18. Save をクリックします。

    このアクションによりポリシーが作成され、ポリシーをプロファイルに関連付けることができます。また、ポリシー実行の条件を設定することもできます。

  19. 条件 で、Add condition をクリックします。

    クライアントシークレットローテーションポリシー条件の作成

    Client Rotation Policy Condition

  20. すべての機密クライアントに動作を適用するには、Condition Type フィールドで client-access-type を選択します。

    注記

    クライアントの特定のグループに適用するには、Condition Type フィールドに client-roles タイプを選択する方法もあります。これにより、特定のロールを作成し、カスタムのローテーション設定を各ロールに割り当てることができます。

  21. Client Access Type フィールドに confidential を追加します。
  22. Add をクリックします。

  23. ポリシー設定に戻り、Client Profiles で、Add client profile をクリックし、リストから Weekly Client Secret Rotation Profile を選択して、Add をクリックします。

    クライアントシークレットローテーションポリシー

    Client Rotation Policy

注記

シークレットのローテーション動作を既存のクライアントに適用するには、以下の手順に従います。

管理コンソールの使用

  1. メニューで Clients をクリックします。
  2. クライアントをクリックします。
  3. Credentials タブをクリックします。
  4. クライアントシークレットの Re-generate をクリックします。

クライアント REST サービスを使用すると、以下のいずれかの方法で実行できます。

  • クライアントでの更新操作経由
  • 再生成クライアントシークレットエンドポイント経由

12.1.7. サービスアカウントの使用

各 OIDC クライアントには、ビルトインの サービスアカウント があります。この サービスアカウント を使用してアクセストークンを取得します。

手順

  1. メニューで Clients をクリックします。
  2. クライアントを選択します。
  3. Settings タブをクリックします。
  4. Client authentication を On に切り替えます。
  5. Service accounts roles を選択します。
  6. Save をクリックします。
  7. クライアント認証情報 を設定します。
  8. Scope タブをクリックします。
  9. ロールがあることを確認するか、Full Scope Allowed を ON に切り替えます。
  10. Service Account Roles タブをクリックします。
  11. クライアントのこのサービスアカウントで利用可能なロールを設定します。

アクセストークンからのロールは、以下の交差部分になります。

  • クライアントのロールスコープと、リンクされたクライアントスコープから継承されたロールスコープのマッピング
  • サービスアカウントロール

呼び出す REST URL は、/realms/{realm-name}/protocol/openid-connect/token です。この URL は POST 要求として呼び出され、要求でクライアントクレデンシャルを投稿する必要があります。

デフォルトでは、クライアント認証情報は Authorization: Basic ヘッダーでクライアントの clientId および clientSecret によって表されますが、署名付きの JWT アサーションやその他のクライアント認証用のカスタムメカニズムを使用してクライアントを認証することもできます。

OAuth2 仕様に従って、grant_type パラメーターを client_credentials に設定する必要があります。

たとえば、サービスアカウントを取得する POST 呼び出しは以下のようになります。 

    POST /realms/demo/protocol/openid-connect/token
    Authorization: Basic cHJvZHVjdC1zYS1jbGllbnQ6cGFzc3dvcmQ=
    Content-Type: application/x-www-form-urlencoded

    grant_type=client_credentials

応答は、OAuth 2.0 仕様からのこの アクセストークン応答 と似ています。 

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":60
}

デフォルトでは、アクセストークンのみが返されます。認証が成功した場合、デフォルトでは更新トークンは返されず、Red Hat build of Keycloak 側にユーザーセッションは作成されません。更新トークンがないため、アクセストークンの期限が切れると再認証が必要になります。ただし、セッションはデフォルトでは作成されないため、この状況で Red Hat build of Keycloak サーバーにオーバーヘッドが追加されることはありません。

このような状況では、ログアウトは必要ありません。ただし、発行されたアクセストークンは、OpenID Connect Endpoints セクションで説明するように、OAuth2 Revocation Endpoint にリクエストを送信して取り消すことができます。

関連情報

詳細については、クライアント認証情報の付与 を参照してください。

12.1.8. オーディエンスのサポート

通常、Red Hat build of Keycloak のデプロイ環境は、認証に Red Hat build of Keycloak を使用する 機密 または 公開 クライアントアプリケーションのセットで設定されます。

また、クライアントアプリケーションからの要求に対応し、これらのアプリケーションにリソースを提供する サービス (OAuth 2 仕様 のリソースサーバー) も利用できます。これらのサービスでは、要求の認証に アクセストークン (Bearer トークン) を送信する必要があります。このトークンは、Red Hat build of Keycloak へのログイン時にフロントエンドアプリケーションによって取得されます。

サービス間の信頼性が低い環境では、以下のシナリオが発生する可能性があります。

  1. フロントエンドクライアントアプリケーションには、Red Hat build of Keycloak に対する認証が必要です。
  2. Red Hat build of Keycloak はユーザーを認証します。
  3. Red Hat build of Keycloak はアプリケーションにトークンを発行します。
  4. アプリケーションはトークンを使用して信頼できないサービスを呼び出す。
  5. 信頼できないサービスはアプリケーションへの応答を返す。ただし、アプリケーショントークンを保持します。
  6. その後、信頼されていないサービスは、アプリケーショントークンを使用して信頼されるサービスを呼び出す。これにより、信頼できないサービスがトークンを使用してクライアントアプリケーションの代わりに他のサービスにアクセスするため、セキュリティーが損なわれます。

このシナリオは、サービス間の信頼度が高い環境では発生する可能性が低いですが、信頼度が低い環境では発生する可能性があります。一部の環境では、信頼されていないサービスが信頼できるサービスからデータを取得して、元のクライアントアプリケーションにデータを返す必要があるため、このワークフローは正しい場合があります。

対象範囲に制限がないと、サービス間で高いレベルの信頼が存在する場合に役立ちます。そうでない場合は、対象範囲を制限する必要があります。対象範囲を制限しつつ、信頼できないサービスが信頼できるサービスからデータを取得できるようにしますこの場合は、信頼できないサービスと信頼できるサービスが対象としてトークンに追加されていることを確認します。

アクセストークンの誤用を防ぐには、トークンの対象範囲を制限し、トークンの対象を確認するようにサービスを設定します。フローは以下のように変わります。

  1. フロントエンドアプリケーションは、Red Hat build of Keycloak に対して認証を行います。
  2. Red Hat build of Keycloak はユーザーを認証します。

  3. Red Hat build of Keycloak はアプリケーションにトークンを発行します。アプリケーションは、信頼されていないサービスを呼び出す必要があることを認識しているため、Red Hat build of Keycloak に送信される認証リクエストに scope=<untrusted service> を配置します (scope パラメーターの詳細については、クライアントスコープ セクションを参照してください)。

    アプリケーションに発行されたトークンには、対象範囲内の信頼できないサービスへの参照 ("audience": [ "<untrusted service>" ]) が含まれます。これで、クライアントがこのアクセストークンを使用して信頼できないサービスを呼び出すことを宣言します。

  4. 信頼されないサービスは、トークンを使用して信頼できるサービスを呼び出します。信頼できるサービスがトークンのオーディエンスをチェックし、そのオーディエンスが信頼できないサービスのみを対象としていることを検出したため、呼び出しは成功しません。これは想定内の動作であり、セキュリティーが破損していません。

クライアントが後で信頼されるサービスを呼び出す場合は、scope=<trusted service> で SSO ログインを再発行して別のトークンを取得する必要があります。返されるトークンには、信頼できるサービスが対象として含まれます。 

"audience": [ "<trusted service>" ]

この値を使用して <trusted service> を起動します。

12.1.8.1. 設定

対象チェックを設定する場合は、以下を行います。

  • アダプター設定に verify-token-audience フラグを追加して、サービスが送信されたアクセストークンのオーディエンスを確認するように設定されていることを確認します。詳細は、アダプターの設定 を参照してください。
  • Red Hat build of Keycloak によって発行されたアクセストークンに、必要なすべてのオーディエンスが含まれていることを確認します。オーディエンスは、次のセクション で説明するように、クライアントロールを使用するか、ハードコーディングして追加できます。ハードコーディングされたオーディエンス を参照してください。

12.1.8.2. 対象の自動追加

Audience Resolve プロトコルマッパーは、デフォルトのクライアントスコープ roles で定義されます。マッパーは、現在のトークンで使用可能なクライアントロールが少なくとも 1 つあるクライアントをチェックします。その後、各クライアントのクライアント ID がオーディエンスとして追加されます。これは、サービスクライアントがクライアントロールに依存する場合に役立ちます。通常、サービスクライアントはフローが有効になっていないクライアントの可能性があり、それ自体に直接発行されたトークンを持たない場合があります。これは OAuth 2 リソースサーバー を表します。

たとえば、サービスクライアントと機密クライアントの場合、機密クライアントに対して発行されたアクセストークンを使用して、サービスクライアントの REST サービスを呼び出すことができます。以下が true の場合、サービスクライアントは機密クライアント向けに発行されたアクセストークンのオーディエンスとして自動的に追加されます。

  • サービスクライアントには、それ自体に定義されたクライアントロールがあります。
  • ターゲットユーザーには、少なくとも 1 つのクライアントロールが割り当てられている。
  • 機密クライアントには割り当てられたロールのロールスコープマッピングがある。
注記

対象が自動的に追加されないようにする場合は、機密クライアントに直接ロールスコープマッピングを設定しないでください。代わりに、専用のクライアントスコープのクライアントロールにロールスコープマッピングが含まれる専用のクライアントスコープを作成できます。

クライアントスコープが任意のクライアントスコープとし気密クライアントに追加されると、scope=<trusted service> パラメーターで明示的に要求されている場合は、クライアントロールと対象がトークンに追加されます。

注記

フロントエンドクライアント自体はアクセストークンオーディエンスに自動的に追加されないため、アクセストークンには、トークンが対象として発行されるクライアントが含まれないので、アクセストークンと ID トークンを簡単に区別できます。

クライアント自体がオーディエンスとして必要な場合は、ハードコーディングされたオーディエンス オプションを参照してください。ただし、フロントエンドと REST サービスと同じクライアントを使用することは推奨されていません。

12.1.8.3. ハードコードされたオーディエンス

サービスがレルムロールに依存する場合や、トークンのロールに依存しない場合は、ハードコーディングされた対象範囲を使用すると便利です。ハードコーディングされた対象範囲は、指定されたサービスクライアントのクライアント ID を対象としてトークンに追加するプロトコルマッパーです。クライアント ID 以外の対象を使用する場合は、URL などのカスタム値を使用できます。

プロトコルマッパーを直接フロントエンドクライアントに追加できます。プロトコルマッパーが直接追加される場合、対象も常に追加されます。

プロトコルマッパーをより詳細に制御するには、 good-service などとして呼ばれる、専用のクライアントスコープでプロトコルマッパーを作成できます。

オーディエンスプロトコルマッパー

audience mapper

  • good-service のクライアントの Client details タブ から、アダプター設定を生成し、verify-token-audience が true に設定されていることを確認できます。この設定を使用する場合、このアクションによりアダプターは対象ユーザーを検証するように強制されます。

  • 機密クライアントがトークン内の対象として good-service を要求できます。

    機密クライアントで以下を行います。

    1. Client Scopes タブをクリックします。

    2. good-service をオプション (またはデフォルト) クライアント範囲として割り当てます。

      詳細は、クライアントスコープのリンクセクション を参照してください。

  • 必要に応じて、クライアントスコープを評価 し、サンプルアクセストークンを生成することができます。任意のクライアントスコープとして割り当てられた場合は、good-service が scope パラメーターに含まれている場合に、生成されるアクセストークンの対象者に good-service が追加されます。

  • 機密クライアントアプリケーションで、scope パラメーターが使用されていることを確認します。good-service にアクセスするためのトークンを発行する場合は、good-service の値を含める必要があります。

    参照:

注記

Audience および Audience Resolve プロトコルマッパーの両方はデフォルトで、対象をアクセストークンに追加します。ID トークンには通常、OpenID Connect 仕様の要件である単一の対象のみ (トークンが発行されたクライアント ID) が含まれます。ただし、アクセストークンには、対象マッパーが追加されない限り、トークンが発行されたクライアント ID があるとは限りません。

Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.