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

アプリケーションおよびサービスの保護ガイド

Red Hat build of Keycloak 26.0

Red Hat Customer Content Services

概要

このガイドには、Red Hat build of Keycloak 26.0 を使用してアプリケーションとサービスを保護するための情報が記載されています。

第1章 アプリケーションとサービスのセキュア化のプランニング
リンクのコピー

Red Hat build of Keycloak は、OAuth2、OpenID Connect、および SAML 準拠のサーバーとして、使用しているテクノロジースタックがこれらのプロトコルのいずれかをサポートしている限り、あらゆるアプリケーションとサービスを保護できます。Red Hat build of Keycloak でサポートされているセキュリティープロトコルの詳細は、サーバー管理ガイド を参照してください。

これらのプロトコルの一部は、使用しているプログラミング言語、フレームワーク、またはリバースプロキシーですでにサポートされています。アプリケーションエコシステムから利用できるサポートを活用することは、アプリケーションをセキュリティー標準とベストプラクティスに完全に準拠させ、ベンダーロックインを回避するために重要です。

Red Hat build of Keycloak は、一部のプログラミング言語について、特定のセキュリティープロトコルにおけるサポート不足を解消するため、またはより緊密で充実したサーバーとの統合を提供するために、ライブラリーを提供しています。これらのライブラリーは Keycloak クライアントアダプター として知られており、アプリケーションエコシステムで利用できるものがない場合の最終手段として使用するものとします。

1.1. アプリケーションとサービスを保護する基本的な手順
リンクのコピー

以下は、Red Hat build of Keycloak のアプリケーションまたはサービスを保護するための基本的な手順です。

  1. 次のオプションのいずれかを使用して、クライアントをレルムに登録します。

    • Red Hat build of Keycloak 管理コンソール
    • クライアント登録サービス
    • CLI

  2. 次のオプションのいずれかを使用して、アプリケーションで OpenID Connect または SAML プロトコルを有効にします。

    • アプリケーションエコシステムから OpenID Connect と SAML の既存サポートを活用する
    • Red Hat build of Keycloak アダプターを使用する

このガイドでは、これらのステップを詳細に説明します。管理コンソールを通じて Red Hat build of Keycloak にクライアントを登録する方法の詳細は、サーバー管理ガイド を参照してください。

1.2. スタートガイド
リンクのコピー

Red Hat build of Keycloak クイックスタートリポジトリー には、さまざまなプログラミング言語とフレームワークを使用してアプリケーションとサービスを保護する方法の例があります。ドキュメントとコードベースを確認することで、Red Hat build of Keycloak を使用してアプリケーションとサービスを保護するために必要な最小限の変更を理解できます。

OpenID Connect プロトコルと SAML プロトコルの両方で信頼される、クライアント側の一般的な実装に関する推奨事項は、次のセクションを参照してください。

1.2.1. OpenID Connect
リンクのコピー

1.2.1.1. JavaScript (クライアント側)
リンクのコピー
1.2.1.2. Node.js (サーバー側)
リンクのコピー

1.2.2. SAML
リンクのコピー

1.2.2.1. Java
リンクのコピー

1.3. 用語
リンクのコピー

このガイドでは、以下の用語を使用しています。

  • Clients は、Red Hat build of Keycloak と対話してユーザーを認証し、トークンを取得するエンティティーです。多くの場合、クライアントは、そのユーザーにシングルサインオンエクスペリエンスを提供し、サーバーが発行するトークンを使用して他のサービスにアクセスするユーザーの代わりに機能するアプリケーションおよびサービスです。クライアントは、トークンの取得のみに関心があり、他のサービスにアクセスするために機能するエンティティーである場合もあります。
  • Applications には、それぞれのプロトコルについて特定のプラットフォームで動作する幅広いアプリケーションが含まれます。
  • Client adapters は、Red Hat build of Keycloak を使用したアプリケーションとサービスの保護を簡単にするライブラリーです。基礎となるプラットフォームやフレームワークへの密接な統合を提供します。
  • Creating a client と registering a client は、同じアクションです。Creating a Client は、管理コンソールを使用してクライアントを作成するのに使用する用語です。Registering a client は、Red Hat build of Keycloak クライアント登録サービスを使用してクライアントを登録することを意味する用語です。
  • A service account は、自分自身のためにトークンを取得できるクライアントの一種です。

第2章 OpenID Connect を使用したアプリケーションとサービスの保護
リンクのコピー

2.1. 利用可能なエンドポイント
リンクのコピー

Red Hat build of Keycloak は、完全に準拠した OpenID Connect プロバイダーの実装として、アプリケーションとサービスがユーザーの認証と認可に使用できるエンドポイントのセットを公開します。

このセクションでは、アプリケーションとサービスが Red Hat build of Keycloak と対話する際に使用する必要がある、いくつかの主要なエンドポイントを説明します。

2.1.1. エンドポイント
リンクのコピー

理解すべき最も重要なエンドポイントは、well-known 設定エンドポイントです。Red Hat build of Keycloak の OpenID Connect 実装に関連するエンドポイントおよびその他の設定オプションをリスト表示します。エンドポイントは次のとおりです。 

/realms/{realm-name}/.well-known/openid-configuration
Copy to Clipboard Toggle word wrap

完全な URL を取得するには、Red Hat build of Keycloak のベース URL を追加し、{realm-name} をレルムの名前に置き換えます。以下に例を示します。

http://localhost:8080/realms/master/.well-known/openid-configuration

一部の RP ライブラリーは、このエンドポイントから必要なすべてのエンドポイントを取得しますが、その他のライブラリーでは、エンドポイントを個別にリスト表示しないといけない場合があります。

2.1.1.1. 認可エンドポイント
リンクのコピー
/realms/{realm-name}/protocol/openid-connect/auth
Copy to Clipboard Toggle word wrap

認可エンドポイントはエンドユーザーの認証を実行します。この認証は、ユーザーエージェントをこのエンドポイントにリダイレクトすることによって行われます。

詳細は、OpenID Connect 仕様の 認可エンドポイント セクションを参照してください。

2.1.1.2. トークンエンドポイント
リンクのコピー
/realms/{realm-name}/protocol/openid-connect/token
Copy to Clipboard Toggle word wrap

トークンエンドポイントは、トークンの取得に使用されます。トークンは、認可コードを調べるか、使用するフローに応じて認証情報を直接指定して取得できます。トークンエンドポイントは、有効期限が切れたときに新しいアクセストークンの取得にも使用されます。

詳細は、OpenID Connect 仕様の トークンエンドポイント セクションを参照してください。

2.1.1.3. Userinfo エンドポイント
リンクのコピー
/realms/{realm-name}/protocol/openid-connect/userinfo
Copy to Clipboard Toggle word wrap

Userinfo エンドポイントは、認証されたユーザーに関する標準クレームを返します。このエンドポイントは、ベアラートークンによって保護されています。

詳細は、OpenID Connect 仕様の Userinfo Endpoint セクションを参照してください。

2.1.1.4. ログアウトエンドポイント
リンクのコピー
/realms/{realm-name}/protocol/openid-connect/logout
Copy to Clipboard Toggle word wrap

ログアウトエンドポイントは、認証されたユーザーをログアウトします。

ユーザーエージェントはエンドポイントにリダイレクトされる可能性があり、これによりアクティブなユーザーセッションがログアウトされます。その後、ユーザーエージェントはアプリケーションにリダイレクトされます。

エンドポイントはアプリケーションによって直接呼び出すこともできます。このエンドポイントを直接呼び出すには、リフレッシュトークンと、クライアントの認証に必要な認証情報を追加する必要があります。

2.1.1.5. 証明書エンドポイント
リンクのコピー
/realms/{realm-name}/protocol/openid-connect/certs
Copy to Clipboard Toggle word wrap

証明書エンドポイントは、レルムが有効にした公開鍵を返し、JSON Web Key (JWK) としてエンコードされます。レルム設定に応じて、トークンを検証するために 1 つ以上のキーを有効にできます。詳細は、サーバー管理ガイド および JSON Web キーの仕様 を参照してください。

2.1.1.6. イントロスペクションエンドポイント
リンクのコピー
/realms/{realm-name}/protocol/openid-connect/token/introspect
Copy to Clipboard Toggle word wrap

イントロスペクションエンドポイントは、トークンのアクティブな状態を取得するために使用されます。つまり、これを使用してアクセストークンを検証したり、更新したりできます。このエンドポイントは、機密クライアントによってのみ呼び出せます。

このエンドポイントで呼び出す方法の詳細は、OAuth 2.0 Token Introspection specification を参照してください。

2.1.1.6.1. application/jwt ヘッダーでトリガーされるイントロスペクションエンドポイント
リンクのコピー

Accept: application/json の代わりに、HTTP ヘッダー Accept: application/jwt を使用してイントロスペクションエンドポイントを呼び出すことができます。application/jwt の場合、応答には完全な JWT アクセストークンを含む追加のクレーム jwt が含まれることがあります。これは、イントロスペクトされるトークンが 軽量アクセストークン であった場合に特に役立ちます。これには、クライアントの詳細設定の Support JWT claim in Introspection Response を有効にする必要があります。これにより、トークンのイントロスペクションがトリガーされます。

2.1.1.7. 動的クライアント登録エンドポイント
リンクのコピー
/realms/{realm-name}/clients-registrations/openid-connect
Copy to Clipboard Toggle word wrap

動的クライアント登録エンドポイントは、クライアントを動的に登録するのに使用されます。

詳細は、<@links.securingapps id="client-registration" /> の章と OpenID Connect Dynamic Client Registration 仕様 を参照してください。

2.1.1.8. トークン失効エンドポイント
リンクのコピー
/realms/{realm-name}/protocol/openid-connect/revoke
Copy to Clipboard Toggle word wrap

トークン失効エンドポイントは、トークンの取り消しに使用されます。このエンドポイントでは、リフレッシュトークンとアクセストークンの両方がサポートされます。リフレッシュトークンを取り消すと、対応するクライアントに対するユーザーの同意も取り消されます。

このエンドポイントで呼び出す方法の詳細は、OAuth 2.0 Token Revocation specification を参照してください。

2.1.1.9. デバイス認可エンドポイント
リンクのコピー
/realms/{realm-name}/protocol/openid-connect/auth/device
Copy to Clipboard Toggle word wrap

デバイス認可エンドポイントは、デバイスコードとユーザーコードを取得するために使用されます。これは、機密またはパブリッククライアントで呼び出すことができます。

このエンドポイントで呼び出す方法の詳細は、OAuth 2.0 Device Authorization Grant specification を参照してください。

2.1.1.10. backchannel 認証エンドポイント
リンクのコピー
/realms/{realm-name}/protocol/openid-connect/ext/ciba/auth
Copy to Clipboard Toggle word wrap

backchannel 認証エンドポイントは、クライアントによる認証要求を識別する auth_req_id を取得するために使用されます。これは、機密クライアントでのみ呼び出すことができます。

このエンドポイントで呼び出す方法の詳細は、OpenID Connect Client Initiated Backchannel Authentication Flow specification を参照してください。

このガイドの クライアントが開始したバックチャネル認証の付与 セクションおよびサーバー管理ガイドの クライアントが開始したバックチャネル認証の付与 セクションなど、Red Hat build of Keycloak ドキュメントの別の箇所も参照してください。

2.2. サポートされている許可タイプ
リンクのコピー

このセクションでは、リレーパーティーが利用できる様々な許可タイプを説明します。

2.2.1. 認可コード
リンクのコピー

認可コードフローは、ユーザーエージェントを Red Hat build of Keycloak にリダイレクトします。Red Hat build of Keycloak でユーザーが正常に認証されると、認可コードが作成され、ユーザーエージェントはアプリケーションにリダイレクトされます。その後、アプリケーションは認証情報と共に認可コードを使用して、Red Hat build of Keycloak からアクセストークン、リフレッシュトークン、および ID トークンを取得します。

フローは Web アプリケーションにターゲットとして設定されていますが、ユーザーエージェントを組み込むことができるモバイルアプリケーションなど、ネイティブアプリケーションに推奨されます。

詳細は、OpenID Connect 仕様の Authorization Code Flow を参照してください。

2.2.2. 暗黙的
リンクのコピー

暗黙的フローは認可コードフローと同じような機能ですが、アクセストークンおよび ID トークンが返される認可コードを返す代わりに、このフローが返されます。このアプローチにより、追加の呼び出しでアクセストークンの認可コードを交換する必要がなくなります。ただし、リフレッシュトークンは含まれません。そのため、有効期限の長いアクセストークンを許可する必要があります。しかし、これらのトークンを無効にするのは非常に難しいため、このアプローチは現実的ではありません。あるいは、最初のアクセストークンの有効期限が切れた後、新しいアクセストークンを取得するために新しいリダイレクトを要求できます。暗黙的フローは、アプリケーションがユーザーを認証し、ログアウト自体を処理する場合に便利です。

代わりに、アクセストークンと認可コードの両方が返されるハイブリッドフローを使用できます。

注意すべき点は、アクセストークンが Web サーバーのログやブラウザーの履歴から漏洩する可能性があるため、暗黙的なフローとハイブリッドフローの両方に潜在的なセキュリティーリスクがあることです。アクセストークンの有効期限を短くすることで、この問題をある程度軽減できます。

詳細は、OpenID Connect 仕様の 暗黙的フロー を参照してください。

現在の OAuth 2.0 セキュリティーのベストプラクティス によれば、このフローは使用するべきではありません。このフローは、将来の OAuth 2.1 仕様 から削除されます。

2.2.3. リソースオーナーパスワード認証情報
リンクのコピー

Red Hat build of Keycloak では Direct Grant と呼ばれるリソース所有者のパスワード認証情報を使用すると、ユーザー認証情報をトークンと交換できます。現在の OAuth 2.0 セキュリティーベストプラクティス によれば、このフローは使用すべきではありません。「デバイス認可グラント」 や 「認可コード」 などの代替方法を推奨します。

このフローの使用には次のような制限があります。

  • ユーザーの認証情報がアプリケーションに公開される
  • アプリケーションにはログインページが必要です。
  • アプリケーションは認証スキームを認識する必要があります。
  • 認証フローへの変更にはアプリケーションへの変更が必要です。
  • アイデンティティーブローカーまたはソーシャルログインはサポートされません。
  • フロー (ユーザー自己登録、必要なアクションなど) はサポートされません。

このフローのセキュリティー上の懸念点は次のとおりです。

  • Red Hat build of Keycloak が認証情報の処理に関与する
  • 認証情報の漏洩が発生する可能性のある脆弱な領域が増加する
  • ユーザーが認証情報の入力に Red Hat build of Keycloak ではなく別のアプリケーションを信頼するような環境が生まれる

クライアントでリソースオーナーパスワード認証情報の使用を許可するには、クライアントの Direct Access Grants Enabled オプションを有効にする必要があります。

このフローは OpenID Connect に含まれず、OAuth 2.0 仕様の一部です。将来の OAuth 2.1 仕様 からは削除されます。

詳細は、OAuth 2.0 仕様の リソースオーナーパスワード認証情報の付与 の章を参照してください。

2.2.3.1. CURL の使用例
リンクのコピー

以下の例は、ユーザー名 user およびパスワード password を使用して、レルムの master ユーザーのアクセストークンを取得する方法を示しています。この例では、機密クライアント myclient を使用しています。 

curl \
  -d "client_id=myclient" \
  -d "client_secret=40cc097b-2a57-4c17-b36a-8fdf3fc2d578" \
  -d "username=user" \
  -d "password=password" \
  -d "grant_type=password" \
  "http://localhost:8080/realms/master/protocol/openid-connect/token"
Copy to Clipboard Toggle word wrap

2.2.4. クライアントクレデンシャル
リンクのコピー

クライアント認証情報は、クライアント (アプリケーションおよびサービス) がユーザーの代わりにではなく、自身の代わりにアクセスを取得する場合に使用されます。たとえば、これらの認証情報は、特定のユーザーではなく、一般的なシステムに変更を適用するバックグラウンドサービスなどに役立ちます。

Red Hat build of Keycloak は、クライアントがシークレットまたは公開鍵/秘密鍵のいずれかを使用して認証するためのサポートを提供します。

このフローは OpenID Connect に含まれず、OAuth 2.0 仕様の一部です。

詳細は、OAuth 2.0 仕様の クライアント認証情報の付与 の章を参照してください。

2.2.5. デバイス認可グラント
リンクのコピー

デバイス認可グラントは、入力機能が制限されているか、適切なブラウザーがないインターネット接続デバイスで実行されているクライアントによって使用されます。

  1. アプリケーションが、Red Hat build of Keycloak にデバイスコードとユーザーコードを提供するよう要求します。
  2. Red Hat build of Keycloak が、デバイスコードとユーザーコードを作成します。
  3. Red Hat build of Keycloak が、デバイスコードおよびユーザーコードなどの応答をアプリケーションに返します。
  4. アプリケーションが、ユーザーにユーザーコードと検証 URI を提供します。ユーザーは検証 URI にアクセスし、別のブラウザーを使用して認証されます。
  5. Red Hat build of Keycloak がユーザー認証を完了するまで、アプリケーションが Red Hat build of Keycloak を繰り返しポーリングします。
  6. ユーザー認証が完了すると、アプリケーションはデバイスコードを取得します。
  7. アプリケーションは認証情報と共にデバイスコードを使用して、Red Hat build of Keycloak からアクセストークン、リフレッシュトークン、および ID トークンを取得します。

詳細は、OAuth 2.0 デバイス認可グラントの仕様 参照してください。

2.2.6. Client Initiated Backchannel Authentication Grant
リンクのコピー

クライアントが開始したバックチャネル認証の付与は、OAuth 2.0 の認可コードグラントのように、ユーザーのブラウザーを介してリダイレクトせずに、OpenID プロバイダーと直接通信することで認可フローを開始するクライアントによって使用されます。

クライアントは、クライアントによる認証要求を識別する auth_req_id を Red Hat build of Keycloak に要求します。Red Hat build of Keycloak は auth_req_id を作成します。

クライアントは、auth_req_id を受信してからユーザーが認証されるまで、Red Hat build of Keycloak からアクセストークン、リフレッシュトークン、および ID トークンを取得するために、auth_req_id と引き換えに Red Hat build of Keycloak を繰り返しポーリングする必要があります。

クライアントが ping モードを使用する場合は、トークンエンドポイントを繰り返しポーリングする必要はありませんが、Red Hat build of Keycloak から指定されたクライアント通知エンドポイントに送信される通知を待つことができます。クライアント通知エンドポイントは、Red Hat build of Keycloak 管理コンソールで設定できます。クライアント通知エンドポイントのコントラクトの詳細は、CIBA 仕様を参照してください。

詳細は、OpenID Connect クライアントが開始したバックチャンネル認証フローの仕様 を参照してください。

また、このガイドの バックチャンネル認証エンドポイント やサーバー管理ガイドの クライアントが開始したバックチャネル認証の付与 セクションなど、Red Hat build of Keycloak ドキュメントの別の箇所も参照してください。FAPI CIBA 準拠の詳細は、このガイドの FAPI セクション を参照してください。

2.3. Red Hat build of Keycloak 固有のエラー
リンクのコピー

Red Hat build of Keycloak サーバーは、error=temporarily_unavailable および error_description=authentication_expired パラメーターを使用して、OIDC 認証応答でクライアントアプリケーションにエラーを送信できます。Red Hat build of Keycloak は、ユーザーが認証され SSO セッションがあるものの、現在のブラウザータブで認証セッションが期限切れとなり、そのために Red Hat build of Keycloak サーバーが自動的にユーザーの SSO 再認証を行い、クライアントに成功応答でリダイレクトすることができない場合に、このエラーを送信します。クライアントアプリケーションがこのタイプのエラーを受信した場合は、すぐに認証を再試行し、新しい OIDC 認証要求を Red Hat build of Keycloak サーバーに送信することが理想的です。通常、このサーバーは SSO セッションにより常にユーザーを認証し、リダイレクトします。詳細は、サーバー管理ガイド を参照してください。

2.4. Financial-grade API (FAPI) サポート
リンクのコピー

Red Hat build of Keycloak を使用すると、管理者はクライアントが以下の仕様に準拠していることを簡単に確認できます。

このコンプライアンスは、Red Hat build of Keycloak サーバーが、これらの仕様に記載されている認可サーバーの要件を検証することを意味します。Red Hat build of Keycloak アダプターには FAPI に対する特別なサポートがないため、クライアント (アプリケーション) 側で必要な検証は、引き続き手動で行うか、その他のサードパーティーソリューションを介して実行する必要がある場合があります。

2.4.1. FAPI クライアントプロファイル
リンクのコピー

クライアントが FAPI に準拠していることを確認するには、サーバー管理ガイド の説明に従って、レルムでクライアントポリシーを設定し、FAPI サポート用のグローバルクライアントプロファイルにリンクします。このプロファイルは、各レルムで自動的に使用可能になります。クライアントが準拠する必要のある FAPI プロファイルに基づいて、fapi-1-baseline または fapi-1-advanced プロファイルのいずれかを使用できます。また、FAPI 2 Draft 仕様に準拠させる場合は、プロファイル fapi-2-security-profile または fapi-2-message-signing を使用できます。

Pushed Authorization Request (PAR) を使用する場合は、クライアントが fapi-1-baseline プロファイルおよび fapi-1-advanced の両方を PAR 要求に使用することが推奨されます。具体的には、fapi-1-baseline プロファイルには、pkce-enforcer エグゼキューターが含まれています。これにより、クライアントはセキュリティーで保護された S256 アルゴリズムで PKCE を確実に使用します。これは、PAR 要求を使用しない限り、FAPI Advanced クライアントには必須ではありません。

FAPI に準拠する方法で CIBA を使用する場合は、クライアントが fapi-1-advanced および fapi-ciba クライアントプロファイルの両方を使用していることを確認してください。fapi-ciba プロファイルには CIBA 固有のエクゼキューターのみが含まれるため、fapi-1-advanced プロファイル、または要求されたエクゼキューターを含む他のクライアントプロファイルを使用する必要があります。FAPI CIBA 仕様の要件を実施する場合は、機密クライアントまたは証明書をバインドしたアクセストークンの適用など、より多くの要件が必要になります。

2.4.2. Open Finance Brasil Financial-grade API Security Profile
リンクのコピー

Red Hat build of Keycloak は、Open Finance Brasil Financial-grade API Security Profile 1.0 Implementers Draft 3 に準拠しています。この仕様は、一部の要件が FAPI 1 Advanced 仕様よりも厳格であるため、一部の要件を適用するには、より厳格な方法で クライアントポリシー を設定する必要が出てくる場合があります。以下の場合は、特にその必要があります。

  • クライアントが PAR を使用しない場合は、暗号化された OIDC 要求オブジェクトが使用されていることを確認してください。これは、Encryption Required を有効にして設定された secure-request-object エグゼキューターを持つクライアントプロファイルを使用して実現できます。
  • JWS の場合は、クライアントが PS256 アルゴリズムを使用していることを確認してください。JWE の場合、クライアントは A256GCM による RSA-OAEP を使用する必要があります。これらのアルゴリズムが適用可能なすべての クライアント設定 で、これを設定する必要がある場合があります。

2.4.3. Australia Consumer Data Right (CDR) Security Profile
リンクのコピー

Red Hat build of Keycloak は、Australia Consumer Data Right Security Profile に準拠しています。

Australia CDR セキュリティープロファイルを適用する場合、fapi-1-advanced プロファイルを使用する必要があります。Australia CDR セキュリティープロファイルは FAPI 1.0 Advanced セキュリティープロファイルに基づいているためです。クライアントが PAR も適用する場合は、クライアントが RFC 7637 Proof Key for Code Exchange (PKCE) を適用することを確認してください。Australia CDR セキュリティープロファイルでは、PAR を適用するときに PKCE を適用することが要求されるためです。これは、pkce-enforcer エクゼキューターでクライアントプロファイルを使用することで実現できます。

2.4.4. TLS に関する考慮事項
リンクのコピー

機密情報が交換されるため、すべての対話は TLS (HTTPS) で暗号化される必要があります。さらに、使用される暗号スイートおよび TLS プロトコルバージョンの FAPI 仕様にはいくつかの要件があります。これらの要件に合致するには、許可された暗号を設定することを検討してください。これは、https-protocols および https-cipher-suites オプションで設定できます。Red Hat build of Keycloak はデフォルトで TLSv1.3 を使用し、このデフォルト設定は変更する必要がないこともあります。ただし、何らかの理由で下位の TLS バージョンにフォールバックする必要がある場合は、暗号化を調整する必要がある場合があります。詳細は、TLS の設定 の章を参照してください。

2.5. OAuth 2.1 のサポート
リンクのコピー

Red Hat build of Keycloak を使用すると、管理者はクライアントが以下の仕様に準拠していることを簡単に確認できます。

このコンプライアンスは、Red Hat build of Keycloak サーバーが、これらの仕様に記載されている認可サーバーの要件を検証することを意味します。Red Hat build of Keycloak アダプターには OAuth 2.1 に対する特別なサポートがないため、クライアント (アプリケーション) 側で必要な検証は、引き続き手動で行うか、その他のサードパーティーソリューションを介して実行する必要がある場合があります。

2.5.1. OAuth 2.1 クライアントプロファイル
リンクのコピー

クライアントが OAuth 2.1 に準拠していることを確認するには、サーバー管理ガイド の説明に従って、レルムでクライアントポリシーを設定し、OAuth 2.1 サポート用のグローバルクライアントプロファイルにリンクします。このプロファイルは、各レルムで自動的に使用可能になります。機密クライアントには oauth-2-1-for-confidential-client プロファイル、パブリッククライアントには oauth-2-1-for-public-client プロファイルを使用できます。

注記

OAuth 2.1 仕様はまだドラフト段階であり、将来変更される可能性があります。したがって、Red Hat build of Keycloak の組み込み OAuth 2.1 クライアントも変更される可能性があります。

注記

パブリッククライアントに OAuth 2.1 プロファイルを使用する場合、サーバー管理ガイド で説明されているように、DPoP プレビュー機能を使用することを推奨します。DPoP は、アクセストークンとリフレッシュトークンをクライアントのキーペアのパブリック部分とバインドするためです。このバインディングは、攻撃者が盗まれたトークンを使用するのを防ぎます。

2.6. 推奨事項
リンクのコピー

このセクションでは、Red Hat build of Keycloak を使用してアプリケーションを保護する場合のいくつかの推奨事項を説明します。

2.6.1. アクセストークンの検証
リンクのコピー

Red Hat build of Keycloak が発行したアクセストークンを手動で検証する必要がある場合は、イントロスペクションエンドポイント を呼び出すことができます。このアプローチの欠点は、Red Hat build of Keycloak サーバーに対してネットワーク呼び出しを行う必要があることです。同時に実行される検証要求が多すぎると、これは遅くなり、サーバーが過負荷になる可能性があります。Red Hat build of Keycloak が発行したアクセストークンは、JSON Web Signature (JWS) を使用してデジタル署名およびエンコードされた JSON Web Tokens (JWT) です。この方法でエンコードされるため、発行したレルムの公開鍵を使用してアクセストークンをローカルで検証できます。レルムの公開鍵を検証コードでハードコードするか、JWS 内に埋め込まれた Key ID (KID) で 証明書エンドポイント を使用して、公開鍵を検索してキャッシュします。コーディングする言語に応じて、多くのサードパーティーライブラリーが存在し、JWS の検証に使用できます。

2.6.2. リダイレクト URI
リンクのコピー

リダイレクトベースのフローを使用する場合は、必ずクライアントに有効なリダイレクト URI を使用してください。リダイレクト URI は可能な限り具体的にする必要があります。これは特に、クライアント側の (パブリッククライアント) アプリケーションに適用されます。これを行わないと、以下が発生する可能性があります。

  • オープンリダイレクト - これにより、攻撃者はドメインから来ているように見えるなりすましリンクを作成できます
  • 不正なエントリー - ユーザーが Red Hat build of Keycloak ですでに認証されている場合、攻撃者はリダイレクト URI が正しく設定されていないパブリッククライアントを使用し、ユーザーが知らないうちにユーザーをリダイレクトしてアクセスを取得できる可能性があります。

Web アプリケーションで実稼働環境では常にすべてのリダイレクト URI に https を使用します。http へのリダイレクトを許可しないでください。

いくつかの特別なリダイレクト URI もあります。

http://127.0.0.1
このリダイレクト URI はネイティブアプリケーションに役立ち、ネイティブアプリケーションは認可コードの取得に使用できるランダムポートで Web サーバーを作成できます。このリダイレクト URI は任意のポートを許可します。OAuth 2.0 for Native Apps にあるとおり、localhost の使用は 推奨されません。代わりに、IP リテラル 127.0.0.1 を使用する必要があることに注意してください。
urn:ietf:wg:oauth:2.0:oob
クライアントで Web サーバーを起動できない場合 (またはブラウザーが使用できない場合)、特別な urn:ietf:wg:oauth:2.0:oob リダイレクト URI を使用できます。このリダイレクト URI を使用すると、Red Hat build of Keycloak は、タイトルとページ上のボックスにコードを含むページを表示します。アプリケーションは、ブラウザーのタイトルが変更されたことを検出するか、ユーザーがコードを手動でアプリケーションにコピーして貼り付けることができます。このリダイレクト URI を使用すると、ユーザーは別のデバイスを使用してコードを取得し、アプリケーションに貼り付けることができます。

第3章 Red Hat build of Keycloak JavaScript アダプター
リンクのコピー

Red Hat build of Keycloak には、Web アプリケーションの保護に使用できる、keycloak-js と呼ばれるクライアント側の JavaScript ライブラリーが付属しています。このアダプターには、Cordova アプリケーションのビルトインサポートもあります。アダプターは内部で OpenID Connect プロトコルを使用します。OpenID Connect のエンドポイントと機能に関するより一般的な情報は、OpenID Connect を使用したアプリケーションとサービスの保護 の章を参照してください。

3.1. インストール
リンクのコピー

NPM から keycloak-js パッケージをインストールすることを推奨します。 

npm install keycloak-js
Copy to Clipboard Toggle word wrap

3.2. Red Hat build of Keycloak サーバーの設定
リンクのコピー

クライアント側のアプリケーションの使用に関しては、クライアントの認証情報をクライアント側のアプリケーションに保存する安全な方法がないため、クライアントはパブリッククライアントでなければならない点を考慮する必要があります。これにより、クライアント用に設定したリダイレクト URI が正しく、可能な限り具体的であることを確認することが非常に重要になります。

アダプターを使用するには、Red Hat build of Keycloak 管理コンソールででアプリケーションのクライアントを作成します。Capability config ページで Client authentication を Off に切り替えて、クライアントを公開します。

また、Valid Redirect URI と Web Origins を設定する必要があります。そうしないと、セキュリティーの脆弱性が生じる可能性があるため、できるだけ具体的にしてください。

3.3. アダプターの使用
リンクのコピー

次の例は、アダプターを初期化する方法を示しています。Keycloak コンストラクターに渡されるオプションは、必ず設定したクライアントのオプションに置き換えてください。 

import Keycloak from 'keycloak-js';

const keycloak = new Keycloak({
    url: "http://keycloak-server",
    realm: "my-realm",
    clientId: "my-app"
});

try {
    const authenticated = await keycloak.init();
    if (authenticated) {
        console.log('User is authenticated');
    } else {
        console.log('User is not authenticated');
    }
} catch (error) {
    console.error('Failed to initialize adapter:', error);
}
Copy to Clipboard Toggle word wrap

認証するには、login 関数を呼び出します。アダプターを自動的に認証する場合、2 つのオプションがあります。init() 関数に login-required または check-sso を渡すことができます。

  • login-required は、ユーザーが Red Hat build of Keycloak にログインしている場合はクライアントを認証し、ユーザーがログインしていない場合はログインページを表示します。
  • check-sso は、ユーザーがすでにログインしている場合にのみクライアントを認証します。ユーザーがログインしていない場合、ブラウザーはアプリケーションにリダイレクトされ、認証されないままになります。

silent check-sso オプションを設定できます。この機能を有効にすると、ブラウザーは Red Hat build of Keycloak サーバーの完全なリダイレクトを実行せず、アプリケーションには戻りません。しかし、このこのアクションは非表示の iframe で実行されます。したがって、ブラウザーはアプリケーションの初期化時に一度だけアプリケーションリソースをロードして解析し、Red Hat build of Keycloak からアプリケーションにリダイレクトされた後にこれを再び実行することはありません。このアプローチは、SPA (Single Page Applications) の場合に特に役立ちます。

silent check-sso を有効にするには、init メソッドで silentCheckSsoRedirectUri 属性を指定します。この URI が、アプリケーション内の有効なエンドポイントであることを確認してください。Red Hat build of Keycloak 管理コンソールの有効なリダイレクトとして設定する必要があります。 

await keycloak.init({
    onLoad: 'check-sso',
    silentCheckSsoRedirectUri: `${location.origin}/silent-check-sso.html`
});
Copy to Clipboard Toggle word wrap

認証の状態が正常にチェックされ、Red Hat build of Keycloak サーバーからトークンを取得すると、サイレント check-sso リダイレクト URI のページが iframe に読み込まれます。受信したトークンをメインアプリケーションに送信する以外のタスクはなく、次のようになります。 

<!doctype html>
<html>
<body>
    <script>
        parent.postMessage(location.href, location.origin);
    </script>
</body>
</html>
Copy to Clipboard Toggle word wrap

このページは、アダプターの 一部ではなく、silentCheckSsoRedirectUri の指定された場所にあるアプリケーションによって提供される必要がある点に注意してください。

警告

サイレント check-sso 機能は、一部の最新のブラウザーで制限さていれます。追跡保護機能を備えた最新のブラウザー セクションを参照してください。

login-required を有効にするには、onLoad を login-required に設定し、init メソッドに渡します。 

await keycloak.init({
    onLoad: 'login-required'
});
Copy to Clipboard Toggle word wrap

ユーザーが認証された後、Authorization ヘッダーにベアラートークンを含めることで、アプリケーションは Red Hat build of Keycloak で保護された RESTful サービスへのリクエストを実行できます。以下に例を示します。 

async function fetchUsers() {
    const response = await fetch('/api/users', {
        headers: {
            accept: 'application/json',
            authorization: `Bearer ${keycloak.token}`
        }
    });

    return response.json();
}
Copy to Clipboard Toggle word wrap

注意すべきことの 1 つは、アクセストークンの有効期限はデフォルトで短いため、リクエストを送信する前にアクセストークンの更新が必要になることが場合があることです。このトークンを更新するには、updateToken() メソッドを呼び出します。このメソッドは、トークンが正常に更新された場合にのみサービスを呼び出し、そうでない場合にはユーザーにエラーを表示することを容易にする Promise を返します。以下に例を示します。 

try {
    await keycloak.updateToken(30);
} catch (error) {
    console.error('Failed to refresh token:', error);
}

const users = await fetchUsers();
Copy to Clipboard Toggle word wrap
注記

アクセストークンとリフレッシュトークンは両方ともメモリーに保存され、どの種類のストレージにも永続化されません。したがって、ハイジャック攻撃を防ぐために、これらのトークンは永続化すべきではありません。

3.4. セッションステータスの iframe
リンクのコピー

デフォルトでは、アダプターは、Single-Sign Out が発生したかどうかを検出するために使用される非表示の iframe を作成します。この iframe はネットワークトラフィックを必要としません。代わりに、ステータスは特別なステータス Cookie を参照して取得されます。init() メソッドに渡されるオプションで checkLoginIframe: false を設定すると、この機能を無効化できます。

このクッキーを直接参照する必要はありません。その形式は変更される可能性があり、アプリケーションではなく Red Hat build of Keycloak サーバーの URL にも関連付けられます。

警告

セッションステータスの iframe 機能は、一部の最新のブラウザーで制限されています。追跡保護機能を備えた最新のブラウザー セクションを参照してください。

3.5. 暗黙的フローおよびハイブリッドフロー
リンクのコピー

デフォルトでは、アダプターは 認可コード フローを使用します。

このフローでは、Red Hat build of Keycloak は、認証トークンではなく認可コードをアプリケーションに返します。JavaScript アダプターは、ブラウザーがアプリケーションにリダイレクトされた後に、アクセストークンと更新トークンの コード を交換します。

Red Hat build of Keycloak は、Red Hat build of Keycloak で認証が成功した直後にアクセストークンが送信される Implicit フローもサポートしています。このフローは、コードをトークンと交換する追加のリクエストがないため、標準フローよりもパフォーマンスが向上する可能性がありますが、アクセストークンの有効期限が切れると影響があります。

ただし、URL フラグメントでアクセストークンを送信すると、セキュリティー脆弱性が発生する可能性があります。たとえば、トークンは Web サーバーログやブラウザー履歴によってリークされる可能性があります。

暗黙的フローを有効にするには、Red Hat build of Keycloak 管理コンソールで、クライアントの Implicit Flow Enabled フラグを有効にします。また、パラメーター flow を implicit の値とともに init メソッドに渡します。 

await keycloak.init({
    flow: 'implicit'
})
Copy to Clipboard Toggle word wrap

アクセストークンのみが提供され、更新トークンは存在しないことに注意してください。この状況は、アクセストークンの有効期限が切れると、アプリケーションは Red Hat build of Keycloak に再度リダイレクトして、新しいアクセストークンを取得する必要があることを意味します。

Red Hat build of Keycloak は、Hybrid フローもサポートしています。

このフローでは、クライアントは管理コンソールで 標準フロー と 暗黙的フロー の両方を有効にする必要があります。Red Hat build of Keycloak サーバーは、コードとトークンの両方をアプリケーションに送信します。アクセストークンは、コードのアクセスと更新トークンを交換して、すぐに使用できます。暗黙的なフローと同様に、アクセストークンがすぐに利用できるため、ハイブリッドフローはパフォーマンスに適しています。ただし、トークンは URL で依然として送信され、前述のセキュリティーの脆弱性は引き続き適用されます。

Hybrid フローの利点の 1 つは、更新トークンがアプリケーションで利用できることです。

ハイブリッドフローの場合は、パラメーター flow の値 hybrid を init メソッドに渡す必要があります。 

await keycloak.init({
    flow: 'hybrid'
});
Copy to Clipboard Toggle word wrap

3.6. Cordova でのハイブリッドアプリケーション
リンクのコピー

Red Hat build of Keycloak は、Apache Cordova で開発されたハイブリッドモバイルアプリをサポートします。アダプターには、cordova と cordova-native という 2 つのモードがあります。

デフォルトは cordova で、アダプタータイプが明示的に設定されておらず、window.cordova が存在する場合、アダプターは自動的にこれを選択します。ログインすると、InApp Browser が開き、ユーザーは Red Hat build of Keycloak と対話できるようになります。その後 http://localhost にリダイレクトしてアプリに戻ります。この動作のために、管理コンソールのクライアント設定セクションで、この URL を有効な redirect-uri としてホワイトリスト化します。

このモードの設定は簡単ですが、いくつかの欠点もあります。

  • InApp-Browser はアプリに組み込まれたブラウザーで、電話のデフォルトブラウザーではありません。したがって、設定が異なり、保存されている認証情報は利用できません。
  • 特に複雑な内容をレンダリングする場合は、InApp-Browser も遅くなる可能性があります。
  • このモードを使用する前に、アプリがログインページをレンダリングするブラウザーを完全に制御できるため、アプリがユーザーの認証情報にアクセスできる可能性があるなど、セキュリティー上の懸念事項を考慮する必要があります。そのため、信頼できないアプリの使用は許可しないでください。

代替モードは、異なるアプローチをする `cordova-native` です。システムのブラウザーを使用してログインページが開きます。ユーザーが認証されると、ブラウザーは特別な URL を使用してアプリケーションにリダイレクトします。そこから、Red Hat build of Keycloak アダプターは、URL からコードまたはトークンを読み取り、ログインを終了できます。

init() メソッドにアダプター型の cordova-native を渡すことで、ネイティブモードを有効できます。 

await keycloak.init({
    adapter: 'cordova-native'
});
Copy to Clipboard Toggle word wrap

このアダプターには 2 つの追加プラグインが必要です。

アプリへのリンクの技術情報は、各プラットフォームや特別な設定によって異なります。詳細は、deeplinks プラグインのドキュメント の Android と iOS のセクションを参照してください。

アプリケーションを開くためのさまざまな種類のリンクが存在します。

前者はセットアップが簡単で信頼性が高い傾向がありますが、後者は一意であり、ドメインの所有者のみが登録できるため、セキュリティーが強化されます。カスタム URL は iOS で非推奨になりました。最高の信頼性を得るためには、ユニバーサルリンクをカスタム URL リンクを仕様するフォールバックサイトと組み合わせて使用することが推奨されます。

さらに、アダプターとの互換性を改善するには、以下の手順が推奨されます。

  • iOS のユニバーサルリンクは、response-mode を query に設定すると、より確実に動作するようです。
  • リダイレクト時に Android がアプリの新しいインスタンスを開かないようにするには、次のスニペットを config.xml に追加します。 
<preference name="AndroidLaunchMode" value="singleTask" />
Copy to Clipboard Toggle word wrap

3.7. カスタムアダプター
リンクのコピー

状況によっては、Capacitor など、デフォルトでサポートされていない環境でアダプターを実行する必要がある場合があります。これらの環境で JavaScript クライアントを使用するには、カスタムアダプターを渡すことができます。たとえば、サードパーティーのライブラリーは、確実に実行できるようにするためのアダプターを提供できます。 

import Keycloak from 'keycloak-js';
import KeycloakCapacitorAdapter from 'keycloak-capacitor-adapter';

const keycloak = new Keycloak({
    url: "http://keycloak-server",
    realm: "my-realm",
    clientId: "my-app"
});

await keycloak.init({
    adapter: KeycloakCapacitorAdapter,
});
Copy to Clipboard Toggle word wrap

この特定のパッケージは存在しませんが、そのようなアダプターをクライアントに渡す方法に関する適切な例を示すことができます。

独自のアダプターを作成することもできます。そのためには、KeycloakAdapter インターフェイスで説明されているメソッドを実装する必要があります。たとえば、以下の TypeScript コードは、すべてのメソッドが適切に実装されていることを確認します。 

import Keycloak, { KeycloakAdapter } from 'keycloak-js';

// Implement the 'KeycloakAdapter' interface so that all required methods are guaranteed to be present.
const MyCustomAdapter: KeycloakAdapter = {
    async login(options) {
        // Write your own implementation here.
    }

    // The other methods go here...
};

const keycloak = new Keycloak({
    url: "http://keycloak-server",
    realm: "my-realm",
    clientId: "my-app"
});

await keycloak.init({
    adapter: MyCustomAdapter,
});
Copy to Clipboard Toggle word wrap

タイプ情報を省略することで TypeScript を使用せずにこれを実行することもできますが、インターフェイスを確実に適切に実装することは、完全にユーザー次第となります。

3.8. 追跡保護機能を備えた最新のブラウザー
リンクのコピー

一部のブラウザーの最新版では、Chrome の SameSite や完全にブロックされたサードパーティーの cookie など、サードパーティーによるユーザーの追跡を防ぐためにさまざまな cookie ポリシーが適用されています。これらのポリシーは、時間の経過とともにさらに制限が厳しくなり、他のブラウザーでも採用される可能性があります。最終的には、サードパーティーコンテキストの Cookie が完全にサポートされなくなり、ブラウザーによってブロックされる可能性があります。その結果、影響を受けるアダプター機能が、最終的に非推奨になる可能性があります。

アダプターは、セッションステータスの iframe、サイレント check-sso、および部分的に通常の (非サイレント) check-sso についても、サードパーティーの cookie に依存しています。これらの機能は、機能が制限されているか、ブラウザーが cookie に関してどのように制限されているかに基づいて完全に無効になっています。アダプターはこの設定を検出しようとし、それに応じて反応します。

3.8.1. "SameSite=Lax by Default" ポリシーを持つブラウザー
リンクのコピー

Red Hat build of Keycloak 側およびアプリケーション側で SSL / TLS 接続が設定されている場合、すべての機能がサポートされます。たとえば、Chrome はバージョン 84 以降が影響を受けます。

3.8.2. サードパーティーの Cookie がブロックされているブラウザー
リンクのコピー

セッションステータス iframe はサポートされず、このようなブラウザーの動作がアダプターによって検出されると自動的に無効になります。これは、アダプターは Single Sign-Out 検出にセッション cookie を使用できず、純粋にトークンに依存する必要があることを意味します。その結果、ユーザーが別のウィンドウでログアウトしても、アダプターを使用しているアプリケーションは、アプリケーションがアクセストークンの更新を試行するまでログアウトされません。したがって、ログアウトができるだけ早く検出されるように、アクセストークンの有効期間を比較的短く設定することを検討してください。詳細は、セッションとトークンのタイムアウト を参照してください。

サイレント check-sso はサポートされず、デフォルトで通常の (非サイレント) check-sso にフォールバックします。この動作は、init メソッドに渡されるオプションで silentCheckSsoFallback: false を設定することで変更できます。この場合、制限的なブラウザー動作が検出されると、check-sso は完全に無効になります。

通常の check-sso も影響を受けます。セッションステータス iframe がサポートされていないため、アダプターがユーザーのログインステータスをチェックするために初期化される際に、Red Hat build of Keycloak への追加のリダイレクトを行う必要があります。このチェックは、ユーザーがログインしているかどうかを示すために iframe を使用する標準の動作とは異なり、リダイレクトはユーザーがログアウトしている場合にのみ実行されます。

影響を受けるブラウザーは、たとえば、バージョン 13.1 以降の Safari などです。

3.9. API リファレンス
リンクのコピー

3.9.1. コンストラクター
リンクのコピー

// Recommended way to initialize the adapter.
new Keycloak({
    url: "http://keycloak-server",
    realm: "my-realm",
    clientId: "my-app"
});

// Alternatively a string to the path of the `keycloak.json` file.
// Has some performance implications, as it will load the keycloak.json file from the server.
// This version might also change in the future and is therefore not recommended.
new Keycloak("http://keycloak-server/keycloak.json");
Copy to Clipboard Toggle word wrap

3.9.2. プロパティー
リンクのコピー

authenticated
ユーザーが認証されている場合は true、そうでない場合は false です。
token
サービスへのリクエストで Authorization ヘッダーで送ることができる base64 エンコードされたトークン。
tokenParsed
解析されたトークンを JavaScript オブジェクトとして実行します。
subject
ユーザー id
idToken
base64 でエンコードされた ID トークン。
idTokenParsed
解析された id トークンを JavaScript オブジェクトとして実行します。
realmAccess
トークンに関連付けられたレルムロール。
resourceAccess
トークンに関連付けられたリソースロール。
refreshToken
新しいトークンの取得に使用できる base64 でエンコードされた更新トークン。
refreshTokenParsed
JavaScript オブジェクトとして解析された更新トークン。
timeSkew
ブラウザー時間と Red Hat build of Keycloak サーバー間の推定時間差 (秒単位)。この値は見積りませんが、トークンの有効期限が切れているかどうかを判断します。
responseMode
init で渡される応答モード (デフォルト値は fragment)。
flow
init に渡されるフロー。
adapter

リダイレクトする方法と、その他のブラウザー関連の機能がライブラリーによって処理される方法を上書きできます。利用可能なオプション:

  • "default" - ライブラリーがリダイレクトにブラウザー api を使用します (これがデフォルトです)。
  • "cordova" - ライブラリーは、InAppBrowser cordova プラグインを使用して keycloak のログイン/登録ページのロードを試みます (ライブラリーが cordova エコシステムで動作している場合、このオプションが自動的に使用されます)
  • "cordova-native" - ライブラリーは、BrowserTabs cordova プラグインを使用して、電話のシステムブラウザーでログインおよび登録ページを開くことを試みます。これには、アプリケーションにリダイレクトするための追加のセットアップが必要です (「Cordova でのハイブリッドアプリケーション」 を参照)。
  • "custom" - カスタムアダプターを実装できます (高度な使用ケースのみ)。
responseType
ログインリクエストとともに Red Hat build of Keycloak に送信される応答タイプ。これは初期化時に使用されるフロー値に基づいて決定されますが、この値を設定すると上書きできます。

3.9.3. メソッド
リンクのコピー

init(options)

アダプターを初期化するために呼び出されます。

オプションはオブジェクトです。ここでは、以下のようになります。

  • useNonce - 暗号化ナンスを追加して、認証応答がリクエストと一致することを確認します (デフォルトは true)。
  • onLoad - 読み込み時に実行するアクションを指定します。サポートされている値は、login-required または check-sso です。
  • silentCheckSsoRedirectUri - onLoad が 'check-sso' に設定されている場合に、サイレント認証チェックのリダイレクト URI を設定します。
  • silentCheckSsoFallback: サイレント check-sso がブラウザーでサポートされない場合に、通常の check-sso へのフォールバックを有効にします (デフォルトは true)。
  • token - トークンに初期値を設定します。
  • refreshToken - 更新トークンの初期値を設定します。
  • idToken - id トークンに初期値を設定します (トークンまたは refreshToken とともにのみ)。
  • scope - デフォルトのスコープパラメーターを Red Hat build of Keycloak ログインエンドポイントに設定します。スコープのスペースで区切られたリストを使用します。これらは通常、特定のクライアントで定義された クライアントスコープ を参照します。スコープの openid は、アダプターによって常にスコープのリストに追加されることに注意してください。たとえば、スコープオプションの address phone を入力すると、Red Hat build of Keycloak へのリクエストにはスコープパラメーター scope=openid address phone が含まれます。login() オプションでスコープを明示的に指定すると、ここで指定したデフォルトのスコープが上書きされることに注意してください。
  • timeSkew - ローカルタイムと Red Hat build of Keycloak サーバー間のスキュー用に初期値を設定します (トークンと refreshToken の場合のみ)。
  • checkLoginIframe - ログイン状態の監視を有効にするかどうかを設定します (デフォルト値は true)。
  • checkLoginIframeInterval - ログイン状態を確認する間隔を設定します (デフォルトは 5 秒です)。
  • responseMode - ログイン要求時に OpenID Connect 応答モードを Red Hat build of Keycloak サーバーに送信します。有効な値は query または fragment です。デフォルト値は fragment で、認証に成功した後、OpenID Connect パラメーターを URL フラグメントに追加した JavaScript アプリケーションに Red Hat build of Keycloak がリダイレクトすることを意味します。これは一般的には、より安全で、query を介して推奨されています。
  • flow - OpenID Connect フローを設定します。有効な値は、standard、implicit、または hybrid です。
  • enableLogging - Keycloak からコンソールへのログメッセージを有効にします (デフォルトは false です)。

  • pkceMethod - 使用する Proof Key Code Exchange (PKCE) 方式。この値を設定すると、PKCE メカニズムが有効になります。利用可能なオプション:

    • "S256" - SHA256 ベースの PKCE 方式 (デフォルト)。
    • false - PKCE は無効です。
  • acrValues - 認証コンテキストクラス参照を参照し、クライアントが必要なアシュアランスレベル要件 (認証メカニズムなど) を宣言できるようにする acr_values パラメーターを生成します。Section 4. acr_values request values and level of assurance in OpenID Connect MODRNA Authentication Profile 1.0 を参照してください。
  • messageReceiveTimeout: Keycloak サーバーからのメッセージ応答を待つタイムアウトをミリ秒単位で設定します。これは、たとえば、サードパーティーの Cookie チェック中に、メッセージを待機するときに使用されます。デフォルト値は 10000 です。
  • locale - onLoad が 'login-required' の場合、OIDC 1.0 仕様のセクション 3.1.2.1 に従って 'ui_locales' クエリーパラメーターを設定します。

初期化の完了時に解決する promise を返します。

login(options)

ログインフォームにリダイレクトし、Promise を返します。

options は任意のオブジェクトです。ここでは、以下のようになります。

  • redirectUri - ログイン後にリダイレクトする URI を指定します。
  • prompt - Red Hat build of Keycloak サーバー側でログインフローを若干カスタマイズできるようにします。たとえば、値が login の場合にログイン画面を表示するように強制します。または、クライアントに Consent Required がある場合に、consent 値の同意画面を強制的に表示します。最後に、値 none を使用して、ログイン画面がユーザーに対して表示されないようにすることができます。これは、ユーザーが以前にすでに認証されている場合に SSO をチェックするのに便利です (これは、上で説明した値 check-sso を使用した onLoad チェックに関連しています)。
  • maxAge - ユーザーがすでに認証されている場合にのみ使用します。ユーザーの認証が発生した時点の最大時間を指定します。ユーザーが maxAge よりも長い期間認証されている場合、SSO は無視されるため、再認証が必要になります。
  • loginHint - ログインフォームの username/email フィールドを事前に入力するのに使用されます。
  • scope - init で設定されたスコープを、この特定ログインの別の値でオーバーライドします。
  • idpHint - Red Hat build of Keycloak に対して、ログインページの表示を省略し、代わりに指定されたアイデンティティープロバイダーに自動的にリダイレクトするように指示するために使用されます。詳細は、アイデンティティープロバイダーのドキュメント を参照してください。
  • acr: acr 要求の情報が含まれます。これは、claims パラメーター内で Red Hat build of Keycloak サーバーに送信されます。一般的な用途は、段階的な認証です。使用例: { values: ["silver", "gold"], essential: true }詳細は、OpenID Connect 仕様と ステップアップ認証のドキュメント を参照してください。
  • acrValues - 認証コンテキストクラス参照を参照し、クライアントが必要なアシュアランスレベル要件 (認証メカニズムなど) を宣言できるようにする acr_values パラメーターを生成します。Section 4. acr_values request values and level of assurance in OpenID Connect MODRNA Authentication Profile 1.0 を参照してください。
  • action - 値が register の場合、ユーザーは登録ページにリダイレクトされます。詳細は、クライアントから要求される登録 セクションを参照してください。値が UPDATE_PASSWORD またはサポートされている別の必須アクションの場合、ユーザーはパスワードのリセットページまたはその他の必須アクションページにリダイレクトされます。ただし、ユーザーが認証されていない場合は、ユーザーはログインページへ移動され、認証後にリダイレクトされます。詳細は、アプリケーション起点のアクション セクションを参照してください。
  • locale - OIDC 1.0 仕様のセクション 3.1.2.1 に従って 'ui_locales' クエリーパラメーターを設定します。
  • cordovaOptions - Cordova in-app-browser (該当する場合) に渡される引数を指定します。hidden オプションおよび location オプションは、これらの引数の影響を受けません。利用可能なすべてのオプションは https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-inappbrowser/ で定義されています。使用例: { zoom: "no", hardwareback: "yes" };

createLoginUrl(options)

ログインフォームへの URL を含む Promise を返します。

options は任意のオブジェクトで、関数 login と同じオプションをサポートします。

logout(options)

ログアウトにリダイレクトされます。

オプションはオブジェクトです。ここでは、以下のようになります。

  • redirectUri - ログアウト後にリダイレクトする URI を指定します。

createLogoutUrl(options)

ユーザーをログアウトするための URL を返します。

オプションはオブジェクトです。ここでは、以下のようになります。

  • redirectUri - ログアウト後にリダイレクトする URI を指定します。

register(options)

登録フォームにリダイレクトされます。オプション action = 'register' を使用したログインのショートカット

オプションは login メソッドと同じですが、'action' は 'register' に設定されます。

createRegisterUrl(options)

登録ページへの URL を含む Promise を返します。オプション action = 'register' を持つ createLoginUrl のショートカット

オプションは createLoginUrl メソッドと同じですが、'action' は 'register' に設定されます。

accountManagement()

アカウントコンソールにリダイレクトします。

createAccountUrl(options)

アカウントコンソールへの URL を返します。

オプションはオブジェクトです。ここでは、以下のようになります。

  • redirectUri: アプリケーションにリダイレクトする際にリダイレクトする URI を指定します。

hasRealmRole(role)

トークンに指定のレルムロールがある場合は true を返します。

hasResourceRole(role, resource)

トークンにリソースの指定されたロールがある場合に true を返します (指定の clientId が使用されていない場合、リソースは任意です)。

loadUserProfile()

ユーザープロファイルを読み込みます。

プロファイルで解決する promise を返します。

以下に例を示します。 

try {
    const profile = await keycloak.loadUserProfile();
    console.log('Retrieved user profile:', profile);
} catch (error) {
    console.error('Failed to load user profile:', error);
}
Copy to Clipboard Toggle word wrap

isTokenExpired(minValidity)

トークンの有効期限が切れる前にトークンが minValidity 秒未満の場合は true を返します (minValidity は任意であり、指定されていない場合は 0 が使用されます)。

updateToken(minValidity)

トークンが minValidity 秒以内に期限切れになると (minValidity は任意で、指定されていない場合は 5 が使用されます)、トークンが更新されます。-1 が minValidity として渡された場合、トークンは強制的に更新されます。セッションステータスが iframe が有効になっている場合は、セッションステータスもチェックされます。

トークンが更新されているかどうかを示すブール値で解決する promise を返します。

以下に例を示します。 

try {
    const refreshed = await keycloak.updateToken(5);
    console.log(refreshed ? 'Token was refreshed' : 'Token is still valid');
} catch (error) {
    console.error('Failed to refresh the token:', error);
}
Copy to Clipboard Toggle word wrap

clearToken()

トークンを含む認証状態を消去します。これは、トークンの更新が失敗した場合など、セッションの期限が切れたことをアプリケーションが検出する場合に役立ちます。

これを呼び出すと、onAuthLogout コールバックリスナーが呼び出されます。

3.9.4. コールバックイベント
リンクのコピー

アダプターは、特定のイベントの callback リスナーの設定をサポートします。これらは init() メソッドを呼び出す前に設定する必要があることに注意してください。

以下に例を示します。 

keycloak.onAuthSuccess = () => console.log('Authenticated!');
Copy to Clipboard Toggle word wrap

利用可能なイベントは以下のとおりです。

  • onReady(authenticated) - アダプターが初期化されると呼び出されます。
  • onAuthSuccess - ユーザーが正常に認証されると呼び出しされます。
  • onAuthError - 認証中にエラーが発生した場合に呼び出しされます。
  • onAuthRefreshSuccess - トークンの更新時に呼び出しされます。
  • onAuthRefreshError - トークンの更新中にエラーが発生した場合に呼び出します。
  • onAuthLogout - ユーザーがログアウトした場合に呼び出されます (セッションステータス iframe が有効になっている場合、または Cordova モードの場合にのみ呼び出されます)。
  • onTokenExpired - アクセストークンの期限が切れたときに呼び出しされます。更新トークンが利用可能な場合、トークンは updateToken で更新できます。利用できない場合 (つまり暗黙的なフローの場合) は、ログイン画面にリダイレクトして新しいアクセストークンを取得できます。

第4章 Red Hat build of Keycloak Node.js アダプター
リンクのコピー

Red Hat build of Keycloak は、サーバー側の JavaScript アプリケーションを保護するために Connect 上に構築された Node.js アダプターを提供します。これは、Express.js などのフレームワークと統合できる柔軟性を備えることが目的でした。アダプターは内部で OpenID Connect プロトコルを使用します。OpenID Connect のエンドポイントと機能に関するより一般的な情報は、OpenID Connect を使用したアプリケーションとサービスの保護 の章を参照してください。

Node.js アダプターを使用するには、まず Red Hat build of Keycloak 管理コンソールでアプリケーションのクライアントを作成する必要があります。アダプターは、パブリック、機密、およびベアラーのみのアクセスタイプをサポートします。どちらを選択しても、ユースケースのシナリオにより異なります。

クライアントが作成されたら、右上の Action をクリックし、Download adapter config を選択します。Format で Keycloak OIDC JSON を選択し、Download をクリックします。ダウンロードした keycloak.json ファイルは、プロジェクトのルートフォルダーにあります。

4.1. インストール
リンクのコピー

Node.js がすでにインストールされている場合は、アプリケーションのディレクトリーを作成します。 

mkdir myapp && cd myapp
Copy to Clipboard Toggle word wrap

npm init コマンドを使用して、アプリケーションの package.json を作成します。次に、依存関係リストに Red Hat build of Keycloak 接続アダプターを追加します。 

    "dependencies": {
        "keycloak-connect": "file:keycloak-connect-26.0.15.tgz"
    }
Copy to Clipboard Toggle word wrap

4.2. 使用方法
リンクのコピー

Keycloak クラスをインスタンス化します。
Keycloak クラスは、アプリケーションとの設定および統合の中心的な場所を提供します。最も単純な作成には引数は含まれません。

プロジェクトのルートディレクトリーに server.js という名前のファイルを作成し、以下のコードを追加します。 

    const session = require('express-session');
    const Keycloak = require('keycloak-connect');

    const memoryStore = new session.MemoryStore();
    const keycloak = new Keycloak({ store: memoryStore });
Copy to Clipboard Toggle word wrap

express-session 依存関係をインストールします。 

    npm install express-session
Copy to Clipboard Toggle word wrap

server.js スクリプトを起動するには、package.json の 'scripts' セクションに以下のコマンドを追加します。 

    "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "start": "node server.js"
    },
Copy to Clipboard Toggle word wrap

これで、以下のコマンドでサーバーを実行できるようになりました。 

    npm run start
Copy to Clipboard Toggle word wrap

デフォルトでは、これはアプリケーションの主な実行ファイルとともに keycloak.json という名前のファイルを見つけ (ここではルートフォルダー)、Red Hat build of Keycloak 固有の設定を初期化します (公開鍵、レルム名、さまざまな URL など)。

この場合、Red Hat build of Keycloak 管理コンソールにアクセスするために Red Hat build of Keycloak デプロイメントが必要です。

Podman または Docker を使用して Red Hat build of Keycloak 管理コンソールをデプロイする方法の詳細は、それぞれのリンクを参照してください。

これで、Red Hat build of Keycloak Admin Console → clients (左サイドバー) → choose your client → Installation → Format Option → Keycloak OIDC JSON → Download に移動して、keycloak.json ファイルを取得できます。

ダウンロードしたファイルをプロジェクトのルートディレクトリーに貼り付けます。

この方法を使用したインスタンス化により、妥当なデフォルトがすべて使用されます。または、keycloak.json ファイルの代わりに、設定オブジェクトを指定することもできます。 

    const kcConfig = {
        clientId: 'myclient',
        bearerOnly: true,
        serverUrl: 'http://localhost:8080',
        realm: 'myrealm',
        realmPublicKey: 'MIIBIjANB...'
    };

    const keycloak = new Keycloak({ store: memoryStore }, kcConfig);
Copy to Clipboard Toggle word wrap

アプリケーションは、以下を使用して、ユーザーを優先しているアイデンティティープロバイダーにリダイレクトすることもできます。 

    const keycloak = new Keycloak({ store: memoryStore, idpHint: myIdP }, kcConfig);
Copy to Clipboard Toggle word wrap
Web セッションストアの設定
Web セッションを使用して認証のサーバー側の状態を管理する場合は、少なくとも store パラメーターで Keycloak(…​) を初期化し、express-session が使用している実際のセッションストアを渡します。 
    const session = require('express-session');
    const memoryStore = new session.MemoryStore();

    // Configure session
    app.use(
      session({
        secret: 'mySecret',
        resave: false,
        saveUninitialized: true,
        store: memoryStore,
      })
    );

    const keycloak = new Keycloak({ store: memoryStore });
Copy to Clipboard Toggle word wrap
カスタムスコープの値の指定
デフォルトでは、スコープ値の openid はクエリーパラメーターとして Red Hat build of Keycloak のログイン URL に渡されますが、さらにカスタム値を追加することができます。 
    const keycloak = new Keycloak({ scope: 'offline_access' });
Copy to Clipboard Toggle word wrap

4.3. ミドルウェアのインストール
リンクのコピー

インスタンス化したら、ミドルウェアを接続対応のアプリケーションにインストールします。

これを行うには、まず Express をインストールする必要があります。 

    npm install express
Copy to Clipboard Toggle word wrap

次に、以下で説明されているようにプロジェクトに Express が必要になります。 

    const express = require('express');
    const app = express();
Copy to Clipboard Toggle word wrap

また、以下のコードを追加して Express で Keycloak ミドルウェアを設定します。 

    app.use( keycloak.middleware() );
Copy to Clipboard Toggle word wrap

最後に、以下のコードを main.js に追加して、3000 ポートで HTTP 要求をリッスンするようにサーバーをセットアップしましょう。 

    app.listen(3000, function () {
        console.log('App listening on port 3000');
    });
Copy to Clipboard Toggle word wrap

4.4. プロキシーの設定
リンクのコピー

SSL 接続を終了するプロキシーの背後でアプリケーション実行されている場合は、express behind proxies ガイドに従って、Express を設定する必要があります。誤ったプロキシー設定を使用すると、無効なリダイレクト URI が生成されることがあります。

設定例: 

    const app = express();

    app.set( 'trust proxy', true );

    app.use( keycloak.middleware() );
Copy to Clipboard Toggle word wrap

4.5. リソースの保護
リンクのコピー

簡易認証
リソースにアクセスする前にユーザーを認証する必要があるように強制するには、単に keycloak.protect() の非引数バージョンを使用します。 
    app.get( '/complain', keycloak.protect(), complaintHandler );
Copy to Clipboard Toggle word wrap
ロールベースの認可
現在のアプリケーションのアプリケーションロールでリソースのセキュリティーを保護するには、以下を実行します。 
    app.get( '/special', keycloak.protect('special'), specialHandler );
Copy to Clipboard Toggle word wrap

別 のアプリケーションのアプリケーションロールでリソースを保護するには、以下を行います。 

    app.get( '/extra-special', keycloak.protect('other-app:special'), extraSpecialHandler );
Copy to Clipboard Toggle word wrap

レルムロールでリソースをセキュアにするには、以下を実行します。 

    app.get( '/admin', keycloak.protect( 'realm:admin' ), adminHandler );
Copy to Clipboard Toggle word wrap
リソースベースの認可
リソースベースの認可を使用すると、Keycloak で定義された一連のポリシーに基づいて、リソースとその特定のメソッド/アクション ** を保護できるため、アプリケーションからの認可を外部化できます。これは、リソースを保護するために使用できる keycloak.enforcer メソッドを公開することで実現されます。* 
    app.get('/apis/me', keycloak.enforcer('user:profile'), userProfileHandler);
Copy to Clipboard Toggle word wrap

keycloak-enforcer メソッドは、response_mode 設定オプションの値に応じて 2 つのモードで動作します。 

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), userProfileHandler);
Copy to Clipboard Toggle word wrap

response_mode が token に設定されている場合は、アプリケーションに送信されたベアラートークンで表されるサブジェクトの代わりにパーミッションがサーバーから取得されます。この場合、新しいアクセストークンは、サーバーによって付与されたアクセス許可を使用して、Keycloak により発行されます。サーバーが予想されるパーミッションを持つトークンに応答しなかった場合、要求は拒否されます。このモードを使用すると、以下のようにリクエストからトークンを取得できるはずです。 

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), function (req, res) {
        const token = req.kauth.grant.access_token.content;
        const permissions = token.authorization ? token.authorization.permissions : undefined;

        // show user profile
    });
Copy to Clipboard Toggle word wrap

アプリケーションがセッションを使用していて、サーバーからの以前の決定をキャッシュし、更新トークンを自動的に処理する場合は、このモードが推奨されます。このモードは、クライアントとリソースサーバーとして動作するアプリケーションに特に便利です。

response_mode が permissions (デフォルトモード) に設定されている場合、サーバーは新しいアクセストークンを発行せずに付与されたパーミッションのリストのみを返します。このメソッドは、新しいトークンを発行しないだけでなく、以下のように リクエスト を介してサーバーに付与されたパーミッションを公開します。 

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'permissions'}), function (req, res) {
        const permissions = req.permissions;

        // show user profile
    });
Copy to Clipboard Toggle word wrap

使用中の response_mode に関係なく、keycloak.enforcer メソッドは、アプリケーションに送信されたベアラートークン内のパーミッションを確認します。ベアラートークンで予想される権限がすでに引き継がれている場合は、サーバーと対話して意思決定を取得する必要はありません。これは、クライアントが、保護されたリソースにアクセスする前に予想されるパーミッションでサーバーからアクセストークンを取得できる場合に特に便利です。そのため、増分認可などの Keycloak Authorization Services が提供する機能を使用し、keycloak.enforcer がリソースへのアクセスを強制している場合に、サーバーへの追加のリクエストを回避できます。

デフォルトでは、ポリシーエンフォーサーはアプリケーション (例: keycloak.json) に定義された client_id を使用して、Keycloak Authorization Services をサポートする Keycloak のクライアントを参照します。この場合、クライアントは実際にはリソースサーバーであることをパブリックにすることはできません。

アプリケーションがパブリッククライアント (フロントエンド) とリソースサーバー (バックエンド) の両方として機能している場合は、次の設定を使用して、適用するポリシーで Keycloak 内の別のクライアントを参照できます。 

      keycloak.enforcer('user:profile', {resource_server_id: 'my-apiserver'})
Copy to Clipboard Toggle word wrap

フロントエンドおよびバックエンドを表すために、Keycloak で個別のクライアントを使用することが推奨されます。

保護するアプリケーションが Keycloak 認可サービスで有効になり、keycloak.json でクライアント認証情報を定義している場合は、サーバーに追加の要求をプッシュして決定のためにポリシーで利用できるようにすることができます。そのため、プッシュする要求と共に JSON を返す 関数 を想定する claims 設定オプションを定義できます。 

      app.get('/protected/resource', keycloak.enforcer(['resource:view', 'resource:write'], {
          claims: function(request) {
            return {
              "http.uri": ["/protected/resource"],
              "user.agent": // get user agent  from request
            }
          }
        }), function (req, res) {
          // access granted
Copy to Clipboard Toggle word wrap

Keycloak を設定してアプリケーションリソースを保護する方法の詳細は、認可サービスガイド を参照してください。

高度な認可
URL 自体の一部に基づいてリソースを保護するには、各セクションにロールが存在することを前提としています。 
    function protectBySection(token, request) {
      return token.hasRole( request.params.section );
    }

    app.get( '/:section/:page', keycloak.protect( protectBySection ), sectionHandler );
Copy to Clipboard Toggle word wrap

高度なログイン設定:

デフォルトでは、クライアントがベアラーのみでない限り、承認されていないすべてのリクエストは Red Hat build of Keycloak のログインページにリダイレクトされます。ただし、機密またはパブリッククライアントは、閲覧可能なエンドポイントと API エンドポイントの両方をホストする場合があります。認証されていない API 要求でのリダイレクトを防ぎ、代わりに HTTP 401 を返すようにするには、redirectToLogin 関数をオーバーライドします。

たとえば、このオーバーライドでは URL に /api/ が含まれているかどうかを確認し、ログインリダイレクトを無効にします。 

    Keycloak.prototype.redirectToLogin = function(req) {
    const apiReqMatcher = /\/api\//i;
    return !apiReqMatcher.test(req.originalUrl || req.url);
    };
Copy to Clipboard Toggle word wrap

4.6. 追加の URL
リンクのコピー

明示的なユーザーがトリガーされたログアウト
デフォルトでは、ミドルウェアは /logout への呼び出しをキャッチし、Red Hat build of Keycloak 中心のログアウトワークフローを介してユーザーを送信します。これは、logout 設定パラメーターを middleware() 呼び出しに指定することで変更できます。 
    app.use( keycloak.middleware( { logout: '/logoff' } ));
Copy to Clipboard Toggle word wrap

ユーザーがトリガーするログアウトが呼び出されると、クエリーパラメーター redirect_url を渡すことができます。 

https://example.com/logoff?redirect_url=https%3A%2F%2Fexample.com%3A3000%2Flogged%2Fout
Copy to Clipboard Toggle word wrap

次に、このパラメーターは OIDC ログアウトエンドポイントのリダイレクト URL として使用され、ユーザーは https://example.com/logged/out にリダイレクトされます。

Red Hat build of Keycloak 管理者コールバック
ミドルウェアは、Red Hat build of Keycloak コンソールのコールバックもサポートし、単一のセッションまたはすべてのセッションをログアウトします。デフォルトでは、これらの管理コールバックのタイプは / のルート URL に関連して行われますが、middleware() 呼び出しに admin パラメーターを指定して変更できます。 
    app.use( keycloak.middleware( { admin: '/callbacks' } );
Copy to Clipboard Toggle word wrap

4.7. 完全な例
リンクのコピー

Node.js アダプターの完全な使用例は、Keycloak quickstarts for Node.js を参照してください。

第5章 mod_auth_openidc Apache HTTPD モジュール
リンクのコピー

警告

Red Hat build of Keycloak では、mod_auth_openidc に対する公式サポートは提供されません。以下の手順は最善を尽くしたものですが、最新の情報ではない可能性があります。詳細は、公式の mod_auth_openidc ドキュメントを参照することを推奨します。

mod_auth_openidc は、OpenID Connect 用の Apache HTTP プラグインです。言語/環境がプロキシーとしての Apache HTTPD の使用をサポートしている場合は、mod_auth_openidc を使用して、OpenID Connect で Web アプリケーションを保護できます。このモジュールの設定は、このドキュメントの範囲外です。設定の詳細は、mod_auth_openidc GitHub リポジトリーを参照してください。

mod_auth_openidc を設定するには、以下が必要です。

  • client_id
  • client_secret
  • アプリケーションへの redirect_uri
  • Red Hat build of Keycloak openid-configuration url
  • mod_auth_openidc 固有の Apache HTTPD モジュール設定

設定例は次のようになります。 

LoadModule auth_openidc_module modules/mod_auth_openidc.so

ServerName ${HOSTIP}

<VirtualHost *:80>

    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html

    #this is required by mod_auth_openidc
    OIDCCryptoPassphrase a-random-secret-used-by-apache-oidc-and-balancer

    OIDCProviderMetadataURL ${KC_ADDR}/realms/${KC_REALM}/.well-known/openid-configuration

    OIDCClientID ${CLIENT_ID}
    OIDCClientSecret ${CLIENT_SECRET}
    OIDCRedirectURI http://${HOSTIP}/${CLIENT_APP_NAME}/redirect_uri

    # maps the preferred_username claim to the REMOTE_USER environment variable
    OIDCRemoteUserClaim preferred_username

    <Location /${CLIENT_APP_NAME}/>
        AuthType openid-connect
        Require valid-user
    </Location>
</VirtualHost>
Copy to Clipboard Toggle word wrap

mod_auth_openidc の設定方法の詳細は、mod_auth_openidc プロジェクトページを参照してください。

第6章 WildFly および EAP 向け Red Hat build of Keycloak SAML Galleon 機能
リンクのコピー

SAML アダプターは、wildfly 29 以降の Galleon 機能パックとして配布されます。この件に関する詳細は、WildFly のドキュメント を参照してください。JBoss EAP 8 GA にも同じオプションが提供されています。

最新の Wildfly/EAP 上で実行されている JakartaEE アプリケーションと Keycloak を統合する方法の例は、Keycloak Quickstart GitHub リポジトリー の servlet-saml-service-provider Jakarta フォルダーを参照してください。

6.1. インストール
リンクのコピー

機能パックのプロビジョニングは、それぞれ wildfly-maven-plugin、wildfly-jar-maven-plugin、または eap-maven-plugin を使用して行われます。

6.1.1. wildfly maven プラグインを使用したプロビジョニングの例
リンクのコピー

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-maven-plugin</artifactId>
    <version>5.0.0.Final</version>
    <configuration>
        <feature-packs>
            <feature-pack>
                <location>wildfly@maven(org.jboss.universe:community-universe)#32.0.1.Final</location>
            </feature-pack>
            <feature-pack>
                <groupId>org.keycloak</groupId>
                <artifactId>keycloak-saml-adapter-galleon-pack</artifactId>
                <version>26.0.15</version>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>core-server</layer>
            <layer>web-server</layer>
            <layer>jaxrs-server</layer>
            <layer>datasources-web-server</layer>
            <layer>webservices</layer>
            <layer>keycloak-saml</layer>
            <layer>keycloak-client-saml</layer>
            <layer>keycloak-client-saml-ejb</layer>
        </layers>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>
Copy to Clipboard Toggle word wrap

6.1.2. wildfly jar maven プラグインを使用したプロビジョニングの例
リンクのコピー

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-jar-maven-plugin</artifactId>
    <version>11.0.2.Final</version>
    <configuration>
        <feature-packs>
            <feature-pack>
                <location>wildfly@maven(org.jboss.universe:community-universe)#32.0.1.Final</location>
            </feature-pack>
            <feature-pack>
                <groupId>org.keycloak</groupId>
                <artifactId>keycloak-saml-adapter-galleon-pack</artifactId>
                <version>26.0.15</version>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>core-server</layer>
            <layer>web-server</layer>
            <layer>jaxrs-server</layer>
            <layer>datasources-web-server</layer>
            <layer>webservices</layer>
            <layer>keycloak-saml</layer>
            <layer>keycloak-client-saml</layer>
            <layer>keycloak-client-saml-ejb</layer>
        </layers>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>
Copy to Clipboard Toggle word wrap

6.1.3. EAP Maven プラグインを使用したプロビジョニングの例
リンクのコピー

<plugin>
    <groupId>org.jboss.eap.plugins</groupId>
    <artifactId>eap-maven-plugin</artifactId>
    <version>1.0.0.Final-redhat-00014</version>
    <configuration>
        <channels>
            <channel>
                <manifest>
                    <groupId>org.jboss.eap.channels</groupId>
                    <artifactId>eap-8.0</artifactId>
                </manifest>
            </channel>
        </channels>
        <feature-packs>
            <feature-pack>
                <location>org.keycloak:keycloak-saml-adapter-galleon-pack</location>
            </feature-pack>
        </feature-packs>
        <layers>
            <layer>core-server</layer>
            <layer>web-server</layer>
            <layer>jaxrs-server</layer>
            <layer>datasources-web-server</layer>
            <layer>webservices</layer>
            <layer>keycloak-saml</layer>
            <layer>keycloak-client-saml</layer>
            <layer>keycloak-client-saml-ejb</layer>
        </layers>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
</plugin>
Copy to Clipboard Toggle word wrap

6.2. 設定
リンクのコピー

SAML クライアントアダプターは、WAR デプロイメント内に配置された XML ファイル /WEB-INF/keycloak-saml.xml によって設定されます。設定は次のようになります。 

<keycloak-saml-adapter xmlns="urn:keycloak:saml:adapter"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                       xsi:schemaLocation="urn:keycloak:saml:adapter https://www.keycloak.org/schema/keycloak_saml_adapter_1_10.xsd">
    <SP entityID="http://localhost:8081/sales-post-sig/"
        sslPolicy="EXTERNAL"
        nameIDPolicyFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
        logoutPage="/logout.jsp"
        forceAuthentication="false"
        isPassive="false"
        turnOffChangeSessionIdOnLogin="false"
        autodetectBearerOnly="false">
        <Keys>
            <Key signing="true" >
                <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
                    <PrivateKey alias="http://localhost:8080/sales-post-sig/" password="test123"/>
                    <Certificate alias="http://localhost:8080/sales-post-sig/"/>
                </KeyStore>
            </Key>
        </Keys>
        <PrincipalNameMapping policy="FROM_NAME_ID"/>
        <RoleIdentifiers>
            <Attribute name="Role"/>
        </RoleIdentifiers>
        <RoleMappingsProvider id="properties-based-role-mapper">
            <Property name="properties.resource.location" value="/WEB-INF/role-mappings.properties"/>
        </RoleMappingsProvider>
        <IDP entityID="idp"
             signaturesRequired="true">
        <SingleSignOnService requestBinding="POST"
                             bindingUrl="http://localhost:8081/realms/demo/protocol/saml"
                    />

            <SingleLogoutService
                    requestBinding="POST"
                    responseBinding="POST"
                    postBindingUrl="http://localhost:8081/realms/demo/protocol/saml"
                    redirectBindingUrl="http://localhost:8081/realms/demo/protocol/saml"
                    />
            <Keys>
                <Key signing="true">
                    <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
                        <Certificate alias="demo"/>
                    </KeyStore>
                </Key>
            </Keys>
        </IDP>
     </SP>
</keycloak-saml-adapter>
Copy to Clipboard Toggle word wrap

システムプロパティーの置換として ${…} エンクロージャーを使用できます。たとえば ${jboss.server.config.dir} になります。XML 設定ファイル内のさまざまな要素の詳細情報を取得するには、Red Hat build of Keycloak SAML Galleon 機能パックの詳細な設定 を参照してください。

6.2.1. WAR のセキュリティー保護
リンクのコピー

このセクションでは、WAR パッケージ内に設定ファイルを追加してファイルを編集することにより、WAR を直接保護する方法を説明します。

keycloak-saml.xml が作成され、WAR の WEB-INF ディレクトリーに配置されたら、web.xml で auth-method を KEYCLOAK-SAML に設定する必要があります。また、標準のサーブレットセキュリティーを使用して URL に role-base 制約を指定する必要があります。以下は web.xml ファイルの例です。 

<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
         version="6.0">

	<module-name>customer-portal</module-name>

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>Admins</web-resource-name>
            <url-pattern>/admin/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>admin</role-name>
        </auth-constraint>
        <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint>
    </security-constraint>
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>Customers</web-resource-name>
            <url-pattern>/customers/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>user</role-name>
        </auth-constraint>
        <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint>
    </security-constraint>

    <login-config>
        <auth-method>KEYCLOAK-SAML</auth-method>
        <realm-name>this is ignored currently</realm-name>
    </login-config>

    <security-role>
        <role-name>admin</role-name>
    </security-role>
    <security-role>
        <role-name>user</role-name>
    </security-role>
</web-app>
Copy to Clipboard Toggle word wrap

auth-method 設定を除くすべての標準サーブレット設定。

6.2.2. Red Hat build of Keycloak SAML サブシステムを使用して WAR を保護する
リンクのコピー

Red Hat build of Keycloak で保護するために WAR を開く必要はありません。または、Red Hat build of Keycloak SAML Adapter Subsystem を介して外部的に保護することもできます。KEYCLOAK-SAML を auth-method として指定する必要はありませんが、web.xml で security-constraints を定義する必要があります。ただし、WEB-INF/keycloak-saml.xml ファイルを作成する必要はありません。このメタデータは、サーバーのサブシステム設定 domain.xml または standalone.xml の XML 内で定義されます。 

<extensions>
  <extension module="org.keycloak.keycloak-saml-adapter-subsystem"/>
</extensions>

<profile>
  <subsystem xmlns="urn:jboss:domain:keycloak-saml:1.1">
    <secure-deployment name="WAR MODULE NAME.war">
      <SP entityID="APPLICATION URL">
        ...
      </SP>
    </secure-deployment>
  </subsystem>
</profile>
Copy to Clipboard Toggle word wrap

secure-deployment name 属性は、セキュリティーを保護する WAR を識別します。この値は web.xml に .war を追加した module-name です。残りの設定は、一般的なアダプター設定 で定義される keycloak-saml.xml 設定と同じ XML 構文を使用します。

設定例: 

<subsystem xmlns="urn:jboss:domain:keycloak-saml:1.1">
  <secure-deployment name="saml-post-encryption.war">
    <SP entityID="http://localhost:8080/sales-post-enc/"
        sslPolicy="EXTERNAL"
        nameIDPolicyFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
        logoutPage="/logout.jsp"
        forceAuthentication="false">
      <Keys>
        <Key signing="true" encryption="true">
          <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
            <PrivateKey alias="http://localhost:8080/sales-post-enc/" password="test123"/>
            <Certificate alias="http://localhost:8080/sales-post-enc/"/>
          </KeyStore>
        </Key>
      </Keys>
      <PrincipalNameMapping policy="FROM_NAME_ID"/>
      <RoleIdentifiers>
        <Attribute name="Role"/>
      </RoleIdentifiers>
      <IDP entityID="idp">
        <SingleSignOnService signRequest="true"
            validateResponseSignature="true"
            requestBinding="POST"
            bindingUrl="http://localhost:8080/realms/saml-demo/protocol/saml"/>

        <SingleLogoutService
            validateRequestSignature="true"
            validateResponseSignature="true"
            signRequest="true"
            signResponse="true"
            requestBinding="POST"
            responseBinding="POST"
            postBindingUrl="http://localhost:8080/realms/saml-demo/protocol/saml"
            redirectBindingUrl="http://localhost:8080/realms/saml-demo/protocol/saml"/>
        <Keys>
          <Key signing="true" >
            <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
              <Certificate alias="saml-demo"/>
            </KeyStore>
          </Key>
        </Keys>
      </IDP>
    </SP>
   </secure-deployment>
</subsystem>
Copy to Clipboard Toggle word wrap

6.2.3. JSESSIONID cookie の SameSite 値の設定
リンクのコピー

ブラウザーは、cookie の SameSite 属性の値を Lax に設定することを計画しています。この設定は、リクエストが同じドメインにある場合にのみ、cookie がアプリケーションに送信されることを意味します。この動作は SAML POST バインディングに影響を与える可能性があり、機能しなくなる可能性があります。SAML アダプターのすべての機能を保持するには、コンテナーによって作成された JSESSIONID クッキーの SameSite の値を None に設定することを推奨します。これを行わないと、Red Hat build of Keycloak へのリクエストごとにコンテナーのセッションがリセットされる可能性があります。

注記

SameSite 属性を None に設定しないようにするには、許容できる場合は REDIRECT バインディングに切り替えるか、この回避策が不要な場合は OIDC プロトコルに切り替えることを検討してください。

Wildfly/EAP の JSESSIONID cookie の SameSite 値を None に設定するには、以下の内容の undertow-handlers.conf ファイルをアプリケーションの WEB-INF ディレクトリーに追加します。 

samesite-cookie(mode=None, cookie-pattern=JSESSIONID)
Copy to Clipboard Toggle word wrap

この設定のサポートは、バージョン 19.1.0 以降の Wildfly で利用可能です。

6.3. ID プロバイダーを使用した登録
リンクのコピー

サーブレットベースのアダプターごとに、アサートコンシューマーサービス URL およびシングルログアウトサービスに登録するエンドポイントは /saml が追加されたサーブレットアプリケーションのベース URL、つまり https://example.com/contextPath/saml である必要があります。

6.4. ログアウト
リンクのコピー

Web アプリケーションからログアウトする方法は複数あります。Jakarta EE サーブレットコンテナーでは、HttpServletRequest.logout() を呼び出すことができます。他のブラウザーアプリケーションでは、ブラウザーをセキュリティー制約のある Web アプリケーションの任意の URL に指定し、クエリーパラメーター GLO (つまり http://myapp?GLO=true) に渡すことができます。ブラウザーに SSO セッションがある場合は、ログアウトします。

6.4.1. クラスター化された環境でのログアウト
リンクのコピー

SAML アダプターは内部的には、SAML セッションインデックス、プリンシパル名 (既知の場合)、および HTTP セッション ID 間のマッピングを保存します。このマッピングは、分散可能なアプリケーションのクラスター全体で、JBoss アプリケーションサーバーファミリー (WildFly 10/11、EAP 6/7) で維持できます。前提条件として、HTTP セッションをクラスター全体に分散する必要があります (つまり、アプリケーションはアプリケーションの web.xml の <distributable/> タグでマークされます)。

この機能を有効にするには、以下のセクションを /WEB_INF/web.xml ファイルに追加します。 

<context-param>
    <param-name>keycloak.sessionIdMapperUpdater.classes</param-name>
    <param-value>org.keycloak.adapters.saml.wildfly.infinispan.InfinispanSessionCacheIdMapperUpdater</param-value>
</context-param>
Copy to Clipboard Toggle word wrap

デプロイメントのセッションキャッシュの名前が deployment-cache の場合、SAML マッピングに使用されるキャッシュの名前が deployment-cache.ssoCache になります。キャッシュの名前は、コンテキストパラメーター keycloak.sessionIdMapperUpdater.infinispan.cacheName で上書きできます。キャッシュを含むキャッシュコンテナーはデプロイメントセッションキャッシュを含むものと同じですが、コンテキストパラメーター keycloak.sessionIdMapperUpdater.infinispan.containerName で上書きできます。

デフォルトでは、SAML マッピングキャッシュの設定はセッションキャッシュから派生します。この設定は、他のキャッシュと同じように、サーバーのキャッシュ設定セクションで手動でオーバーライドできます。

現在、信頼できるサービスを提供するには、SAML セッションキャッシュにレプリケートされたキャッシュを使用することが推奨されます。分散キャッシュを使用すると、SAML のログアウト要求が HTTP セッションマッピングへの SAML セッションインデックスにアクセスできないノードに到達する結果となり、ログアウトに失敗する可能性があります。

6.4.2. クロスサイトシナリオにおけるログアウト
リンクのコピー

複数のデータセンターにまたがるセッションを処理するには、特別な処理が必要です。以下のシナリオを見てみましょう。

  1. ログイン要求は、データセンター 1 のクラスター内で処理されます。
  2. 管理者は、特定の SAML セッションに対してログアウト要求を発行し、要求はデータセンター 2 に送信されます。

データセンター 2 は、データセンター 1 (および HTTP セッションを共有する他のすべてのデータセンター) にあるすべてのセッションをログアウトする必要があります。

この場合、上記 の SAML セッションキャッシュを個別のクラスター内だけでなく、たとえば、スタンドアロン Infinispan/JDG サーバーを介して すべてのデータセンターにレプリケートする必要があります。

  1. スタンドアロン Infinispan/JDG サーバーにキャッシュを追加する必要があります。
  2. 各 SAML セッションキャッシュのリモートストアとして、以前のアイテムからのキャッシュを追加する必要があります。

デプロイメント中にリモートストアが SAML セッションキャッシュに存在することが検出されると、変更がないか監視され、それに応じてローカル SAML セッションキャッシュが更新されます。

6.5. assertion 属性の取得
リンクのコピー

正常な SAML ログインの後、アプリケーションコードが SAML アサーションで渡される属性値を取得することを推奨します。HttpServletRequest.getUserPrincipal() は、org.keycloak.adapters.saml.SamlPrincipal と呼ばれる Red Hat build of Keycloak 固有のクラスに型変換できる Principal オブジェクトを返します。このオブジェクトを使用すると、raw アサーションを確認でき、属性値を検索するための便利な関数もあります。 

package org.keycloak.adapters.saml;

public class SamlPrincipal implements Serializable, Principal {
    /**
     * Get full saml assertion
     *
     * @return
     */
    public AssertionType getAssertion() {
       ...
    }

    /**
     * Get SAML subject sent in assertion
     *
     * @return
     */
    public String getSamlSubject() {
        ...
    }

    /**
     * Subject nameID format
     *
     * @return
     */
    public String getNameIDFormat() {
        ...
    }

    @Override
    public String getName() {
        ...
    }

    /**
     * Convenience function that gets Attribute value by attribute name
     *
     * @param name
     * @return
     */
    public List<String> getAttributes(String name) {
        ...

    }

    /**
     * Convenience function that gets Attribute value by attribute friendly name
     *
     * @param friendlyName
     * @return
     */
    public List<String> getFriendlyAttributes(String friendlyName) {
        ...
    }

    /**
     * Convenience function that gets first  value of an attribute by attribute name
     *
     * @param name
     * @return
     */
    public String getAttribute(String name) {
        ...
    }

    /**
     * Convenience function that gets first  value of an attribute by attribute name
     *
     *
     * @param friendlyName
     * @return
     */
    public String getFriendlyAttribute(String friendlyName) {
        ...
    }

    /**
     * Get set of all assertion attribute names
     *
     * @return
     */
    public Set<String> getAttributeNames() {
        ...
    }

    /**
     * Get set of all assertion friendly attribute names
     *
     * @return
     */
    public Set<String> getFriendlyNames() {
        ...
    }
}
Copy to Clipboard Toggle word wrap

6.6. エラー処理
リンクのコピー

Red Hat build of Keycloak には、サーブレットベースのクライアントアダプター用のエラー処理機能がいくつかあります。認証でエラーが発生した場合、クライアントアダプターは HttpServletResponse.sendError() を呼び出します。web.xml ファイル内に error-page を設定して、必要なエラーを処理できます。クライアントアダプターは 400、401、403、および 500 のエラーを出力できます。 

<error-page>
    <error-code>403</error-code>
    <location>/ErrorHandler</location>
</error-page>
Copy to Clipboard Toggle word wrap

クライアントアダプターは、取得可能な HttpServletRequest 属性も設定します。属性名は org.keycloak.adapters.spi.AuthenticationError です。このオブジェクトは、org.keycloak.adapters.saml.SamlAuthenticationError に型変換されます。このクラスは、何が起こったのかを正確に知ることができます。この属性が設定されていない場合、アダプターはエラーコードを担当しませんでした。 

public class SamlAuthenticationError implements AuthenticationError {
    public static enum Reason {
        EXTRACTION_FAILURE,
        INVALID_SIGNATURE,
        ERROR_STATUS
    }

    public Reason getReason() {
        return reason;
    }
    public StatusResponseType getStatus() {
        return status;
    }
}
Copy to Clipboard Toggle word wrap

6.7. トラブルシューティング
リンクのコピー

問題をトラブルシューティングする最善の方法は、クライアントアダプターと Red Hat build of Keycloak サーバーの両方で SAML のデバッグをオンにすることです。ロギングフレームワークを使用して、org.keycloak.saml パッケージのログレベルを DEBUG に設定します。これをオンにすると、サーバーとの間で送受信される SAML 要求および応答ドキュメントを確認できます。

6.8. マルチテナンシー
リンクのコピー

SAML はマルチテナンシーを提供します。つまり、単一のターゲットアプリケーション (WAR) を複数の Red Hat build of Keycloak レルムで保護できます。レルムは、同じ Red Hat build of Keycloak インスタンス上に配置することも、異なるインスタンス上に配置することもできます。

これを実行するには、複数の keycloak-saml.xml アダプター設定ファイルが必要です。

異なるアダプター設定ファイルを含む WAR の複数のインスタンスを異なるコンテキストパスにデプロイすることができますが、これは不便である可能性があるため、コンテキストパス以外のものに基づいてレルムを選択することを推奨します。

Red Hat build of Keycloak を使用すると、カスタム設定リゾルバーを使用できるため、各リクエストに使用するアダプター設定を選択できます。SAML では、設定はログイン処理のみに関連し、ユーザーがログインするとセッションが認証され、返された keycloak-saml.xml が異なるかどうかは問題ありません。そのため、同じセッションで同じ設定を返すことが、適切な方法になります。

そのためには、org.keycloak.adapters.saml.SamlConfigResolver の実装を作成します。以下の例では、Host ヘッダーを使用して適切な設定を検索し、アプリケーションの Java クラスパスから関連する要素を読み込みます。 

package example;

import java.io.InputStream;
import org.keycloak.adapters.saml.SamlConfigResolver;
import org.keycloak.adapters.saml.SamlDeployment;
import org.keycloak.adapters.saml.config.parsers.DeploymentBuilder;
import org.keycloak.adapters.saml.config.parsers.ResourceLoader;
import org.keycloak.adapters.spi.HttpFacade;
import org.keycloak.saml.common.exceptions.ParsingException;

public class SamlMultiTenantResolver implements SamlConfigResolver {

    @Override
    public SamlDeployment resolve(HttpFacade.Request request) {
        String host = request.getHeader("Host");
        String realm = null;
        if (host.contains("tenant1")) {
            realm = "tenant1";
        } else if (host.contains("tenant2")) {
            realm = "tenant2";
        } else {
            throw new IllegalStateException("Not able to guess the keycloak-saml.xml to load");
        }

        InputStream is = getClass().getResourceAsStream("/" + realm + "-keycloak-saml.xml");
        if (is == null) {
            throw new IllegalStateException("Not able to find the file /" + realm + "-keycloak-saml.xml");
        }

        ResourceLoader loader = new ResourceLoader() {
            @Override
            public InputStream getResourceAsStream(String path) {
                return getClass().getResourceAsStream(path);
            }
        };

        try {
            return new DeploymentBuilder().build(is, loader);
        } catch (ParsingException e) {
            throw new IllegalStateException("Cannot load SAML deployment", e);
        }
    }
}
Copy to Clipboard Toggle word wrap

また、web.xml のコンテキストパラメーター keycloak.config.resolver で使用する SamlConfigResolver 実装を設定する必要があります。 

<web-app>
    ...
    <context-param>
        <param-name>keycloak.config.resolver</param-name>
        <param-value>example.SamlMultiTenantResolver</param-value>
    </context-param>
</web-app>
Copy to Clipboard Toggle word wrap

6.9. Red Hat build of Keycloak 固有のエラー
リンクのコピー

Red Hat build of Keycloak サーバーは、SAML 応答でクライアントアプリケーションにエラーを送信できます。これには、次のような SAML ステータスが含まれる場合があります。 

<samlp:Status>
  <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Responder">
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:AuthnFailed"/>
  </samlp:StatusCode>
  <samlp:StatusMessage>authentication_expired</samlp:StatusMessage>
</samlp:Status>
Copy to Clipboard Toggle word wrap

Red Hat build of Keycloak は、ユーザーが認証され SSO セッションがあるものの、現在のブラウザータブで認証セッションが期限切れとなり、そのために Red Hat build of Keycloak サーバーが自動的にユーザーの SSO 再認証を行い、クライアントに成功応答でリダイレクトすることができない場合に、このエラーを送信します。クライアントアプリケーションがこのタイプのエラーを受信した場合は、すぐに認証を再試行し、新しい SAML 要求を Red Hat build of Keycloak サーバーに送信することが理想的です。通常、このサーバーは SSO セッションにより常にユーザーを認証し、リダイレクトします。コメントされたステータスがサーバーから返された場合、SAML アダプターは自動的に再試行を実行します。詳細は、サーバー管理ガイド を参照してください。

第7章 Red Hat build of Keycloak SAML Galleon 機能パックの詳細な設定
リンクのコピー

この章には、Red Hat build of Keycloak SAML Galleon 機能パックで使用される keycloak-saml.xml 設定ファイルの要素の詳細なリストが記載されています。

7.1. SP 要素
リンクのコピー

SP 要素属性の説明は次のとおりです。 

<SP entityID="sp"
    sslPolicy="ssl"
    nameIDPolicyFormat="format"
    forceAuthentication="true"
    isPassive="false"
    keepDOMAssertion="true"
    autodetectBearerOnly="false">
...
</SP>
Copy to Clipboard Toggle word wrap
entityID
これは、このクライアントの ID です。IdP では、クライアントが通信しているユーザーを判別するためにこの値が必要です。この設定は 必須 です。
sslPolicy
これは、アダプターが強制する SSL ポリシーです。有効な値は ALL、EXTERNAL、および NONE です。ALL の場合、すべてのリクエストは HTTPS 経由で受信する必要があります。EXTERNAL の場合、非プライベート IP アドレスのみが HTTPS 経由で有線を通過する必要があります。NONE の場合、HTTPS 経由のリクエストはありません。この設定は 任意 です。デフォルト値は EXTERNAL です。
nameIDPolicyFormat
SAML クライアントは、特定の NameID Subject 形式を要求できます。特定の形式が必要な場合は、この値を入力します。標準の SAML 形式の識別子である urn:oasis:names:tc:SAML:2.0:nameid-format:transient ある必要があります。この設定は 任意 です。デフォルトでは、特別な形式は要求されません。
forceAuthentication
SAML クライアントは、ユーザーが IdP にすでにログインしていても、再認証することをリクエストできます。有効にするには、これを true に設定します。この設定は 任意 です。デフォルト値は false です。
isPassive
SAML クライアントは、IdP にログインしていない場合でも、ユーザーの認証が要求されないように要求できます。必要に応じてこれを true に設定します。forceAuthentication は逆の設定なので、一緒に使用しないでください。この設定は 任意 です。デフォルト値は false です。
turnOffChangeSessionIdOnLogin
セッション ID は、一部のプラットフォームで正常にログインしてセキュリティー攻撃ベクトルをプラグインするためにデフォルトで変更されます。これを無効にするには、これを true に変更します。オフにしないことが推奨されます。デフォルト値は false です。
autodetectBearerOnly
アプリケーションが Web アプリケーションと Web サービス (例: SOAP または REST) の両方に対応する場合は、true に設定する必要があります。これにより、Web アプリケーションの未認証ユーザーを Red Hat build of Keycloak ログインページにリダイレクトできますが、SOAP または REST クライアントのような未認証のクライアントには、ログインページへのリダイレクトが理解できないため、HTTP 401 ステータスコードを送信します。Red Hat build of Keycloak は、X-Requested-With、SOAPAction、Accept などの一般的なヘッダーに基づいて SOAP または REST クライアントを自動検出します。デフォルト値は false です。
logoutPage
これにより、ログアウト後に表示するページが設定されます。ページが http://web.example.com/logout.html などの完全な URL の場合、ユーザーは HTTP 302 ステータスコードを使用してログアウト後にそのページにリダイレクトされます。スキーム部分のないリンク (例: /logout.jsp) が指定されると、web.xml の security-constraint 宣言に従って保護領域に存在するかどうかに関係なく、ログアウトの後にページが表示され、ページがデプロイメントコンテキストルートとの関連で解決されます。
keepDOMAssertion
この属性は true に設定して、要求に関連付けられた SamlPrincipal 内の元の形式でアダプターストアにアサーションの DOM 表現を設定します。アサーションドキュメントは、プリンシパル内の getAssertionDocument メソッドを使用して取得できます。これは、署名済みアサーションの再生時に特に便利です。返されるドキュメントは、Red Hat build of Keycloak サーバーによって受信された SAML 応答を解析して生成されたものです。この設定は 任意 で、デフォルト値は false です (ドキュメントはプリンシパルに保存されません)。

7.2. サービスプロバイダーキーおよびキー要素
リンクのコピー

IdP で、クライアントアプリケーション (または SP) がすべての要求に署名するか、IdP がアサーションを暗号化する場合は、これを実行するために使用するキーを定義する必要があります。クライアント署名のドキュメントでは、ドキュメントの署名に使用される秘密鍵、および公開鍵または証明書の両方を定義する必要があります。暗号化の場合は、復号に使用する秘密鍵のみを定義する必要があります。

キーを記述する方法は 2 つあります。キーは Java KeyStore 内に格納することも、PEM 形式の keycloak-saml.xml にキーを直接コピー/貼り付けることもできます。 

        <Keys>
            <Key signing="true" >
               ...
            </Key>
        </Keys>
Copy to Clipboard Toggle word wrap

Key 要素には、2 つの任意の属性の signing および encryption があります。true に設定すると、これらはアダプターにキーの使用目的を通知します。両方の属性が true に設定されていると、キーはドキュメントの署名と暗号化されたアサーションの復号の両方に使用されます。少なくとも 1 つの属性を true に設定する必要があります。

7.2.1. KeyStore 要素
リンクのコピー

Key 要素内で、Java Keystore から鍵と証明書を読み込みます。これは KeyStore 要素内で宣言されます。 

        <Keys>
            <Key signing="true" >
                <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
                    <PrivateKey alias="myPrivate" password="test123"/>
                    <Certificate alias="myCertAlias"/>
                </KeyStore>
            </Key>
        </Keys>
Copy to Clipboard Toggle word wrap

以下は、KeyStore 要素で定義されている XML 設定属性です。

file
キーストアへのファイルパス。このオプションは 任意 です。file または resource 属性を設定する必要があります。
resource
KeyStore への WAR リソースパス。これは、ServletContext.getResourceAsStream() へのメソッド呼び出しで使用されるパスです。このオプションは 任意 です。file または resource 属性を設定する必要があります。
password
KeyStore のパスワード。このオプションは 必須 です。

SP がドキュメントの署名に使用するキーを定義する場合は、Java KeyStore 内の秘密鍵および証明書への参照も指定する必要があります。上記の例の PrivateKey および Certificate 要素は、キーストア内のキーまたは証明書を参照する エイリアス を定義します。キーストアには、秘密鍵にアクセスするために追加のパスワードが必要です。PrivateKey 要素で、password 属性内にこのパスワードを定義する必要があります。

7.2.2. キーの PEMS
リンクのコピー

Key 要素内で、PrivateKeyPem、PublicKeyPem および CertificatePem のサブ要素を使用して、キーと証明書を直接宣言します。これらの要素に含まれる値は PEM キー形式に準拠する必要があります。通常、openssl または同様のコマンドラインツールを使用してキーを生成する場合は、このオプションを使用します。 

<Keys>
   <Key signing="true">
      <PrivateKeyPem>
         2341251234AB31234==231BB998311222423522334
      </PrivateKeyPem>
      <CertificatePem>
         211111341251234AB31234==231BB998311222423522334
      </CertificatePem>
   </Key>
</Keys>
Copy to Clipboard Toggle word wrap

7.3. SP PrincipalNameMapping 要素
リンクのコピー

この要素は任意です。HttpServletRequest.getUserPrincipal() などのメソッドから取得する Java Principal オブジェクトを作成する場合は、Principal.getName() メソッドによって返される名前を定義できます。 

<SP ...>
  <PrincipalNameMapping policy="FROM_NAME_ID"/>
</SP>

<SP ...>
  <PrincipalNameMapping policy="FROM_ATTRIBUTE" attribute="email" />
</SP>
Copy to Clipboard Toggle word wrap

policy 属性は、この値に設定するために使用されるポリシーを定義します。この属性に使用できる値は次のとおりです。

FROM_NAME_ID
このポリシーは SAML サブジェクト値を使用するだけです。これはデフォルト設定です。
FROM_ATTRIBUTE
これにより、サーバーから受信した SAML アサーションで宣言された属性のいずれかから値をプルします。XML 属性 attribute 内で使用する SAML の assertion 属性の名前を指定する必要があります。

7.4. RoleIdentifiers 要素
リンクのコピー

RoleIdentifiers 要素は、ユーザーから受け取ったアサーション内の SAML 属性を、ユーザーの Jakarta EE Security Context 内のロール識別子として使用する必要があります。 

<RoleIdentifiers>
     <Attribute name="Role"/>
     <Attribute name="member"/>
     <Attribute name="memberOf"/>
</RoleIdentifiers>
Copy to Clipboard Toggle word wrap

デフォルトでは、Role 属性値は Jakarta EE ロールに変換されます。一部の IdP は、member または memberOf 属性アサーションを使用してロールを送信します。1 つ以上の Attribute 要素を定義して、ロールに変換する必要のある SAML 属性を指定できます。

7.5. RoleMappingsProvider 要素
リンクのコピー

RoleMappingsProvider は、SAML アダプターによって使用される SPI 実装 org.keycloak.adapters.saml.RoleMappingsProvider の ID および設定を許可するオプションの要素です。

Red Hat build of Keycloak を IDP として使用する場合、組み込みのロールマッパーを使用して、ロールを SAML アサーションに追加する前にマップできます。ただし、SAML アダプターを使用して、SAML リクエストをサードパーティーの IDP に送信するびに使用できます。この場合は、SP の必要に応じてアサーションからデプロイメントされたロールを異なるロールセットにマッピングすることが必要になる場合があります。RoleMappingsProvider SPI は、必要なマッピングを実行するのに使用できるプラグ可能なロールマッパーの設定を可能にします。

プロバイダーの設定は以下のようになります。 

...
<RoleIdentifiers>
    ...
</RoleIdentifiers>
<RoleMappingsProvider id="properties-based-role-mapper">
    <Property name="properties.resource.location" value="/WEB-INF/role-mappings.properties"/>
</RoleMappingsProvider>
<IDP>
    ...
</IDP>
Copy to Clipboard Toggle word wrap

id 属性は、使用するインストール済みプロバイダーを特定します。Property サブ要素は複数回使用してプロバイダーの設定プロパティーを指定できます。

7.5.1. プロパティーベースのロールマッピングプロバイダー
リンクのコピー

Red Hat build of Keycloak には、properties ファイルを使用してロールマッピングを実行する RoleMappingsProvider 実装が含まれています。このプロバイダーは id properties-based-role-mapper によって識別され、org.keycloak.adapters.saml.PropertiesBasedRoleMapper クラスによって実装されます。

このプロバイダーは、使用される properties ファイルの場所を指定するために使用できる 2 つの設定プロパティーに依存します。最初に、設定値を使用して、ファイルシステムで properties ファイルを見つけることで、properties.file.location プロパティーが指定されているかどうかを確認します。設定したファイルが見つからない場合、プロバイダーは RuntimeException を出力します。以下のスニペットは、properties.file.configuration オプションを使用して、ファイルシステムの /opt/mappers/ ディレクトリーから roles.properties ファイルを読み込むプロバイダーの例を示しています。 

    <RoleMappingsProvider id="properties-based-role-mapper">
        <Property name="properties.file.location" value="/opt/mappers/roles.properties"/>
    </RoleMappingsProvider>
Copy to Clipboard Toggle word wrap

properties.file.location 設定が設定されていない場合、プロバイダーは properties.resource.location プロパティーをチェックし、設定した値を使用して WAR リソースから properties ファイルを読み込みます。この設定プロパティーがない場合、プロバイダーはデフォルトで /WEB-INF/role-mappings.properties からファイルを読み込もうとします。リソースからファイルを読み込めない場合、プロバイダーは RuntimeException を出力します。以下のスニペットは、properties.resource.location を使用してアプリケーションの /WEB-INF/conf/ ディレクトリーから roles.properties ファイルを読み込むプロバイダーの例を示しています。 

    <RoleMappingsProvider id="properties-based-role-mapper">
        <Property name="properties.resource.location" value="/WEB-INF/conf/roles.properties"/>
    </RoleMappingsProvider>
Copy to Clipboard Toggle word wrap

properties ファイルには、ロールとプリンシパルの両方をキーとして含めることができ、0 つ以上のロールを値としてコンマで区切ります。呼び出されると、実装はアサーションから抽出したロールのセットを繰り返し処理し、各ロールについて、マッピングが存在するかどうかを確認します。ロールが空ロールにマップする場合、これは破棄されます。1 つ以上の異なるロールのセットにマップすると、これらのロールは結果セットに設定されます。ロールのマッピングが見つからない場合は、結果セットに組み込まれます。

ロールの処理後、アサーションから抽出したプリンシパルにエントリーの properties ファイルが含まれるかどうかを確認します。プリンシパルのマッピングが存在する場合は、値としてリスト表示されるすべてのロールが結果セットに追加されます。これにより、追加のロールをプリンシパルに割り当てることができます。

たとえば、プロバイダーが以下のプロパティーファイルで設定されていると仮定します。 

roleA=roleX,roleY
roleB=

kc_user=roleZ
Copy to Clipboard Toggle word wrap

プリンシパル kc_user が、roleA、roleB、および roleC があるアサーションから抽出されると、プリンシパルに割り当てられたロールの最終セットは roleC、roleX、roleY、および roleZ になります。なぜなら roleA が roleX および roleY にマッピングされ、roleB が空のロールにマッピングされて破棄され、roleC がそのまま使用され、追加ロールが kc_user プリンシパル (roleZ) に追加されるためです。

注記: マッピングのロール名にスペースを使用するには、Unicode の空白文字を使用してください。たとえば、受信した 'ロール A' は以下のように表示されます。 

role\u0020A=roleX,roleY
Copy to Clipboard Toggle word wrap

7.6. IDP 要素
リンクのコピー

IDP 要素のすべては、SP が通信しているアイデンティティープロバイダー (認証トークン) の設定を記述します。 

<IDP entityID="idp"
     signaturesRequired="true"
     signatureAlgorithm="RSA_SHA1"
     signatureCanonicalizationMethod="http://www.w3.org/2001/10/xml-exc-c14n#">
...
</IDP>
Copy to Clipboard Toggle word wrap

以下は、IDP 要素宣言内で指定できる属性設定オプションです。

entityID
これは IDP の発行者 ID です。この設定は 必須 です。
signaturesRequired
true に設定すると、クライアントアダプターは IDP に送信するすべてのドキュメントに署名します。また、クライアントは IDP が送信されたドキュメントに署名されることを想定します。このスイッチは、すべての要求および応答タイプのデフォルトを設定しますが、後でこのタイプを詳細に制御できることがわかります。この設定は 任意 で、デフォルトは false に設定されます。
signatureAlgorithm
これは、IDP により署名されたドキュメントで使用することが必要な署名アルゴリズムです。使用できる値は、RSA_SHA1、RSA_SHA256、RSA_SHA512、および DSA_SHA1 です。この設定は 任意 で、デフォルト値は RSA_SHA256 です。SHA1 ベースのアルゴリズムは非推奨です。今後、削除される可能性があることに注意してください。*_SHA1 の代わりに、より安全なアルゴリズムを使用することを推奨します。また、*_SHA1 アルゴリズムでは、SAML サーバー (通常は Red Hat build of Keycloak) が Java 17 以降で実行されている場合、署名の検証は機能しません。
signatureCanonicalizationMethod
これは、IDP により署名されたドキュメントで使用することが必要な署名の正規化方法です。この設定は 任意 です。デフォルト値は http://www.w3.org/2001/10/xml-exc-c14n# で、大抵の IDP に適しています。
metadataUrl
IDP メタデータの取得に使用される URL。現在、これは署名キーと暗号化キーを定期的に取得するためにのみ使用され、SP 側で手動で変更することなく IDP でこれらのキーを循環させることができます。

7.7. IDP AllowedClockSkew サブ要素
リンクのコピー

AllowedClockSkew オプションの sub 要素は、IDP と SP の間で許可されるクロックの skew を定義します。デフォルト値は 0 です。 

<AllowedClockSkew unit="MILLISECONDS">3500</AllowedClockSkew>
Copy to Clipboard Toggle word wrap
unit
この要素の値に割り当てられた時間単位を定義することができます。使用できる値は MICROSECONDS、MILLISECONDS、MINUTES、NANOSECONDS、および SECONDS です。これは 任意 です。デフォルト値は SECONDS です。

7.8. IDP SingleSignOnService サブ要素
リンクのコピー

サブ要素 SingleSignOnService は、IDP のログイン SAML エンドポイントを定義します。クライアントアダプターは、ログイン時にこの要素内の設定を介してフォーマットされた IDP に要求を送信します。 

<SingleSignOnService signRequest="true"
                     validateResponseSignature="true"
                     requestBinding="post"
                     bindingUrl="url"/>
Copy to Clipboard Toggle word wrap

この要素で定義できる config 属性を以下に示します。

signRequest
クライアントは認証要求に署名する必要がありますか ?この設定は 任意 です。デフォルトは、任意の IDP の signaturesRequired 要素の値に設定されます。
validateResponseSignature
クライアントは、IDP が authn 要求から返送されたアサーション応答ドキュメントに署名することを期待する必要がありますか ?この設定は 任意 です。デフォルトは、任意の IDP の signaturesRequired 要素の値に設定されます。
requestBinding
これは IDP との通信に使用される SAML バインディングタイプです。この設定は 任意 です。デフォルト値は POST ですが、REDIRECT に設定することもできます。
responseBinding
SAML を使用すると、クライアントは、認証応答で使用するバインディングタイプを要求できます。値は POST または REDIRECT です。この設定は 任意 です。デフォルトでは、クライアントは応答用に特定のバインディングタイプを要求しません。
assertionConsumerServiceUrl
IDP ログインサービスが応答を送信する必要がある Assertion Consumer Service (ACS) の URL。この設定は 任意 です。デフォルトでは、IdP の設定に依存するため、これは未設定です。設定した場合は、/saml (例: http://sp.domain.com/my/endpoint/for/saml) で終了する必要があります。このプロパティーの値は SAML AuthnRequest メッセージの AssertionConsumerServiceURL 属性で送信されます。通常、このプロパティーには responseBinding 属性が伴います。
bindingUrl
これは、クライアントが要求を送信する IDP ログインサービスの URL です。この設定は 必須 です。

7.9. IDP SingleLogoutService サブ要素
リンクのコピー

サブ要素 SingleLogoutService は、IDP のログアウト SAML エンドポイントを定義します。クライアントアダプターは、ログアウト時にこの要素内の設定を介してフォーマットされた IDP に要求を送信します。 

<SingleLogoutService validateRequestSignature="true"
                     validateResponseSignature="true"
                     signRequest="true"
                     signResponse="true"
                     requestBinding="redirect"
                     responseBinding="post"
                     postBindingUrl="posturl"
                     redirectBindingUrl="redirecturl">
Copy to Clipboard Toggle word wrap
signRequest
クライアントは、IDP に対して行うログアウト要求に署名する必要がありますか ?この設定は 任意 です。デフォルトは、任意の IDP の signaturesRequired 要素の値に設定されます。
signResponse
クライアントが、IDP 要求に送信するログアウト応答に署名する必要があるかどうか。この設定は 任意 です。デフォルトは、任意の IDP の signaturesRequired 要素の値に設定されます。
validateRequestSignature
クライアントが、IDP からの署名済みログアウト要求ドキュメントを期待する必要があるかどうか。この設定は 任意 です。デフォルトは、任意の IDP の signaturesRequired 要素の値に設定されます。
validateResponseSignature
クライアントが、IDP からの署名済みログアウト応答ドキュメントを期待する必要があるか。この設定は 任意 です。デフォルトは、任意の IDP の signaturesRequired 要素の値に設定されます。
requestBinding
これは、IDP への SAML 要求の通信に使用される SAML バインディングタイプです。この設定は 任意 です。デフォルト値は POST ですが、REDIRECT に設定することもできます。
responseBinding
これは、IDP への SAML 応答の通信に使用される SAML バインディングタイプです。値は POST または REDIRECT です。この設定は 任意 です。デフォルト値は POST ですが、REDIRECT に設定することもできます。
postBindingUrl
これは、POST バインディングの使用時に IDP のログアウトサービスの URL です。この設定は、POST バインディングを使用する場合に 必須 になります。
redirectBindingUrl
これは、REDIRECT バインディングの使用時に IDP のログアウトサービスの URL です。この設定は、REDIRECT バインディングを使用する場合に 必須 になります。

7.10. IDP キーサブ要素
リンクのコピー

IDP のキーサブ要素は、IDP によって署名されたドキュメントの検証に使用する証明書またはパブリックキーの定義にのみ使用されます。これは、SP の Keys 要素 と同じ方法で定義されます。ただし、証明書または公開鍵参照を定義するだけで十分です。IDP と SP の両方が、それぞれ Red Hat build of Keycloak サーバーとアダプターによって実現されている場合は、署名検証用のキーを指定する必要がない点に注意してください (以下を参照)。

SP と IDP の両方が Red Hat build of Keycloak によって実装されている場合、公開された証明書から IDP 署名検証用の公開鍵を自動的に取得するように SP を設定することができます。これは、キーサブ要素の署名検証キーの宣言をすべて削除することによって行われます。キーサブ要素が空のままになる場合は、完全に省略できます。次に、キーは SP により SAML 記述子から自動的に取得されます。これは、IDP SingleSignOnService サブ要素 で指定された SAML エンドポイント URL から派生します。SAML 記述子取得に使用される HTTP クライアントの設定は、通常、追加設定は必要ありませんが、IDP HttpClient サブ要素 で設定することもできます。

署名の検証に複数のキーを指定することもできます。これは、signing 属性が true に設定されている Keys サブ要素内で複数の Key 要素を宣言することによって行われます。これは、IDP 署名鍵がローテートされる場合などに便利です。通常、新しい SAML プロトコルメッセージとアサーションが新しいキーで署名される際に移行期間がありますが、以前のキーで署名されたものは引き続き受け入れる必要があります。

署名検証用のキーの自動取得および追加の静的署名検証キーの定義の両方を行うように Red Hat build of Keycloak を設定することはできません。 

       <IDP entityID="idp">
            ...
            <Keys>
                <Key signing="true">
                    <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
                        <Certificate alias="demo"/>
                    </KeyStore>
                </Key>
            </Keys>
        </IDP>
Copy to Clipboard Toggle word wrap

7.11. IDP HttpClient サブ要素
リンクのコピー

HttpClient オプションのサブ要素は、enabled の場合に、IDP の SAML 記述子で IDP 署名検証用の公開鍵を含む証明書を自動的に取得するために使用される HTTP クライアントのプロパティーを定義します。 

<HttpClient connectionPoolSize="10"
            disableTrustManager="false"
            allowAnyHostname="false"
            clientKeystore="classpath:keystore.jks"
            clientKeystorePassword="pwd"
            truststore="classpath:truststore.jks"
            truststorePassword="pwd"
            proxyUrl="http://proxy/"
            socketTimeout="5000"
            connectionTimeout="6000"
            connectionTtl="500" />
Copy to Clipboard Toggle word wrap
connectionPoolSize
この設定オプションは、Red Hat build of Keycloak サーバーにプールする接続の数を定義します。これは 任意 です。デフォルト値は 10 です。
disableTrustManager
Red Hat build of Keycloak サーバーが HTTPS を必要とし、この設定オプションが true に設定されている場合、トラストストアを指定する必要はありません。この設定は開発時のみ使用してください。これは SSL 証明書の検証を無効にするため、実稼働環境では 使用しないで ください。これは 任意 です。デフォルト値は false です。
allowAnyHostname
Red Hat build of Keycloak サーバーが HTTPS を必要とし、この設定オプションが true に設定されている場合、Red Hat build of Keycloak サーバーの証明書はトラストストア経由で検証されますが、ホスト名の検証は行われません。この設定は開発時のみ使用してください。これは SSL 証明書の検証を一部無効にするため、実稼働環境では 使用しないで ください。この設定は、テスト環境で役に立ちます。これは 任意 です。デフォルト値は false です。
truststore
値は、トラストストアファイルへのファイルパスです。classpath: でパスを接頭辞にすると、代わりにデプロイメントのクラスパスからトラストストアが取得されます。Red Hat build of Keycloak サーバーへの送信 HTTPS 通信に使用されます。HTTPS 要求を実行するクライアントでは、通信先のサーバーのホストを確認する方法が必要です。これは、トラストストアが行なうことです。キーストアには、1 つ以上の信頼できるホスト証明書または認証局が含まれます。このトラストストアは、Red Hat build of Keycloak サーバーの SSL キーストアの公開証明書を抽出して作成できます。これは、disableTrustManager が true でない限り 必須 になります。
truststorePassword
トラストストアのパスワード。これは、トラストストア が設定され、トラストストアにパスワードが必要な場合は 必須 になります。
clientKeystore
これはキーストアファイルに対するファイルパスです。このキーストアには、アダプターが Red Hat build of Keycloak サーバーに HTTPS 要求を行う際の双方向 SSL 用のクライアント証明書が含まれています。これは 任意 です。
clientKeystorePassword
クライアントキーストアおよびクライアントの鍵のパスワード。これは、clientKeystore が設定されている場合は REQUIRED になります。
proxyUrl
HTTP 接続に使用する HTTP プロキシーの URL。これは 任意 です。
socketTimeout
接続の確立後にデータを待つソケットのタイムアウト (ミリ秒単位)。2 つのデータパケット間の最長の非アクティブ時間。タイムアウト値 0 は無限のタイムアウトとして解釈されます。負の値は未定義として解釈されます (該当する場合はシステムのデフォルト)。デフォルト値は -1 です。これは 任意 です。
connectionTimeout
リモートホストとの接続を確立するためのタイムアウト (ミリ秒単位)。タイムアウト値 0 は無限のタイムアウトとして解釈されます。負の値は未定義として解釈されます (該当する場合はシステムのデフォルト)。デフォルト値は -1 です。これは 任意 です。
connectionTtl
クライアント向けの接続 Time to Live (ミリ秒単位)。ゼロ以下の値は、無限の値として解釈されます。デフォルト値は -1 です。これは 任意 です。

第8章 mod_auth_mellon Apache モジュール
リンクのコピー

mod_auth_mellonは Apache の認証モジュールです。言語/環境が Apache HTTPD をプロキシーとして使用することをサポートしている場合は、mod_auth_mellon を使用して SAML で Web アプリケーションを保護できます。このモジュールの詳細は、GitHub リポジトリー mod_auth_mellon を参照してください。

警告

Red Hat build of Keycloak では、mod_auth_mellon に対する公式サポートは提供されません。以下の手順は最善を尽くしたものですが、最新の情報ではない可能性があります。この章では、サーバーが RHEL システムであると想定しています。ただし、他の Linux システムでも同様の手順が必要になります。詳細は、公式の mod_auth_mellon ドキュメントを参照することを推奨します。

mod_auth_mellon を設定するには、次のファイルが必要です。

  • アイデンティティープロバイダー (IdP) エンティティー記述子 XML ファイル。これは、Red Hat build of Keycloak または別の SAML IdP への接続を記述します。
  • セキュリティー保護するアプリケーションの SAML 接続および設定を記述する SP エンティティー記述子 XML ファイル。
  • 秘密鍵 PEM ファイル。これは、アプリケーションがドキュメントの署名に使用するプライベートキーを定義する PEM 形式のテキストファイルです。
  • アプリケーションの証明書を定義するテキストファイルである証明書 PEM ファイル。
  • mod_auth_mellon 固有の Apache HTTPD モジュール設定。

Red Hat build of Keycloak アプリケーションサーバーのレルム内にクライアントアプリケーションをすでに定義して登録している場合は、Red Hat build of Keycloak によって、Apache HTTPD モジュール設定を除く必要なファイルがすべて生成されます。

Apache HTTPD モジュール設定を生成するには、次の手順を実行します。

手順

  1. SAML クライアントのインストールページに移動します。

  2. Mod Auth Mellon ファイルオプションを選択します。

    図8.1 mod_auth_mellon 設定のダウンロード

    auth-melon 設定をダウンロードする
    View larger image
    auth-melon 設定をダウンロードする
  3. Download をクリックして、必要な XML 記述子と PEM ファイルを含む ZIP ファイルをダウンロードします。

8.1. Red Hat build of Keycloak を使用した mod_auth_mellon の設定
リンクのコピー

以下の 2 つのホストがあります。

  • Red Hat build of Keycloak が実行されているホスト。Red Hat build of Keycloak は SAML アイデンティティープロバイダー (IdP) であるため、これは $idp_host と呼ばれます。
  • Web アプリケーションが実行されているホスト。これは $sp_host と呼ばれます。SAML では、IdP を使用するアプリケーションはサービスプロバイダー (SP) と呼ばれます。

以下のすべての手順は、root 権限で $sp_host で実行する必要があります。

8.1.1. パッケージのインストール
リンクのコピー

必要なパッケージをインストールするには、以下が必要です。

  • Apache Web Server (httpd)
  • Apache の Mellon SAML SP アドオンモジュール
  • X509 証明書を作成するツール

必要なパッケージをインストールするには、以下のコマンドを実行します。 

yum install httpd mod_auth_mellon mod_ssl openssl
Copy to Clipboard Toggle word wrap

8.1.2. Apache SAML の設定ディレクトリーの作成
リンクのコピー

Apache の SAML の使用に関連する設定ファイルを 1 つの場所で維持することを推奨します。

Apache の設定ルート /etc/httpd の下に、saml2 という名前の新しいディレクトリーを作成します。 

mkdir /etc/httpd/saml2
Copy to Clipboard Toggle word wrap

8.1.3. Mellon サービスプロバイダーの設定
リンクのコピー

Apache アドオンモジュールの設定ファイルは /etc/httpd/conf.d ディレクトリーにあり、ファイル名の拡張子は .conf になります。/etc/httpd/conf.d/mellon.conf ファイルを作成し、Mellon の設定ディレクティブをこれに配置する必要があります。

Mellon の設定ディレクティブは、大まかに 2 つのクラスの情報に分類できます。

  • SAML 認証を保護する URL
  • 保護された URL が参照された場合に使用される SAML パラメーター。

Apache 設定ディレクティブは通常、場所と呼ばれる URL 領域内の階層ツリー構造に従います。Mellon が保護するには、URL の場所を 1 つ以上指定する必要があります。各場所に適用される設定パラメーターを追加する方法に柔軟性があります。必要なパラメーターをすべてロケーションブロックに追加するか、Mellon パラメーターを特定の保護された場所が継承する URL の場所階層にある共通の場所に追加するかのいずれかを実行できます (またはこの 2 つのなんらかの組み合わせを実行)。どの場所が SAML アクションをトリガーしても、SP は同じように動作するのが一般的であるため、ここで使用する設定例では、一般的な Mellon 設定ディレクティブを階層の root に配置してから、Mellon によって保護される特定の場所を最小限のディレクティブで定義できます。このストラテジーでは、保護されている場所ごとに同じパラメーターが重複しないようにします。

この例には保護された場所が 1 つ (https://$sp_host/private) しかありません。

Mellon サービスプロバイダーを設定するには、以下の手順を実行します。

手順

  1. 以下の内容で /etc/httpd/conf.d/mellon.conf ファイルを作成します。 
 <Location / >
    MellonEnable info
    MellonEndpointPath /mellon/
    MellonSPMetadataFile /etc/httpd/saml2/mellon_metadata.xml
    MellonSPPrivateKeyFile /etc/httpd/saml2/mellon.key
    MellonSPCertFile /etc/httpd/saml2/mellon.crt
    MellonIdPMetadataFile /etc/httpd/saml2/idp_metadata.xml
 </Location>
 <Location /private >
    AuthType Mellon
    MellonEnable auth
    Require valid-user
 </Location>
Copy to Clipboard Toggle word wrap
注記

上記のコードで参照されるファイルの一部は、後の手順で作成されます。

8.1.5. サービスプロバイダーメタデータの作成
リンクのコピー

SAML IdP および SP は、XML 形式の SAML メタデータを交換します。メタデータのスキーマは標準であるため、参加している SAML エンティティーが互いのメタデータを消費できるようにします。以下が必要です。

  • SP が使用する IdP のメタデータ
  • IdP に提供された SP を記述するメタデータ

SAML メタデータのコンポーネントの 1 つは X509 証明書です。これらの証明書は 2 つの目的で使用されます。

  • SAML メッセージを署名し、メッセージが予期されたパーティーから発信されたことを受信側が証明できるようにします。
  • トランスポート中にメッセージを暗号化します (SAML メッセージは通常 TLS で保護されているトランスポートで発生するため、ほとんど使用されません)。

すでに認証局 (CA) を持っている場合は、独自の証明書を使用できます。または、自己署名証明書を生成することもできます。この例では簡単にするために、自己署名証明書が使用されています。

Mellon の SP メタデータは mod_auth_mellon のインストール済みバージョンの機能を反映する必要があるため、有効な SP メタデータ XML である必要があり、X509 証明書 (X509 証明書の生成に精通していない場合は、証明書の作成はわかりにくい可能性がある) を含む必要があります。SP メタデータを生成する最も便利な方法は、mod_auth_mellon パッケージ (mellon_create_metadata.sh) に含まれるツールを使用することです。生成されたメタデータは、テキストファイルであるため、常に後で編集できます。このツールは、X509 キーおよび証明書も作成します。

SAML IdP および SP は、EntityID として知られる一意の名前を使用して識別します。Mellon メタデータ作成ツールを使用するには、以下が必要です。

  • EntityID。これは通常 SP の URL であり、多くの場合、SP メタデータを取得できる SP の URL です。
  • SP の SAML メッセージが使用される URL。Mellon は MellonEndPointPath を呼び出します。

SP メタデータを作成するには、以下の手順を行います。

手順

  1. ヘルパーシェル変数をいくつか作成します。 

    fqdn=`hostname`
mellon_endpoint_url="https://${fqdn}/mellon"
mellon_entity_id="${mellon_endpoint_url}/metadata"
file_prefix="$(echo "$mellon_entity_id" | sed 's/[^A-Za-z.]/_/g' | sed 's/__*/_/g')"
    Copy to Clipboard Toggle word wrap

  2. 以下のコマンドを実行して、Mellon メタデータ作成ツールを呼び出します。 

    /usr/libexec/mod_auth_mellon/mellon_create_metadata.sh $mellon_entity_id $mellon_endpoint_url
    Copy to Clipboard Toggle word wrap

  3. 生成されたファイルを (上記で作成した /etc/httpd/conf.d/mellon.conf ファイルで参照した) 宛先に移動します。 

    mv ${file_prefix}.cert /etc/httpd/saml2/mellon.crt
mv ${file_prefix}.key /etc/httpd/saml2/mellon.key
mv ${file_prefix}.xml /etc/httpd/saml2/mellon_metadata.xml
    Copy to Clipboard Toggle word wrap

前提: Red Hat build of Keycloak IdP が $idp_host にすでにインストールされている。

Red Hat build of Keycloak は、すべてのユーザー、クライアントなどがレルムと呼ばれるものにグループ化される複数のテナンシーをサポートします。各レルムは、他のレルムとは独立しています。Red Hat build of Keycloak で既存のレルムを使用することもできますが、この例では test_realm という新しいレルムを作成し、そのレルムを使用する方法を示します。

これらの操作はすべて、Red Hat build of Keycloak 管理コンソールを使用して実行されます。以下の手順を実行するには、$idp_host の管理者のユーザー名およびパスワードが必要です。

手順

  1. 管理コンソールを開き、管理者のユーザー名とパスワードを入力してログオンします。

    管理コンソールにログインすると、既存のレルムがあります。Red Hat build of Keycloak が最初にセットアップされると、デフォルトでルートレルム (master) が作成されます。以前に作成されたレルムは、管理コンソールの左上隅のドロップダウンリストにリスト表示されます。

  2. レルムドロップダウンリストから Add レルム を選択します。
  3. Name フィールドに test_realm と入力して、Create をクリックします。
8.1.6.1. レルムのクライアントとしての Mellon Service Provider の追加
リンクのコピー

Red Hat build of Keycloak では、SAML SP はクライアントとして知られています。SP を追加するには、レルムの Clients セクションにいる必要があります。

  1. 左側の Clients メニュー項目をクリックし、Import client ボタンをクリックします。

  2. Resource file フィールドに、上記で作成した Mellon SP メタデータファイル (/etc/httpd/saml2/mellon_metadata.xml) を指定します。

    ブラウザーが実行している場所に応じて、ブラウザーがファイルを見つけられるように、SP メタデータを $sp_host からブラウザーが実行されているマシンにコピーする必要があります。

  3. Save をクリックします。
8.1.6.2. Mellon SP クライアントの編集
リンクのコピー

以下の手順を使用して、重要なクライアント設定パラメーターを設定します。

手順

  1. Force POST Binding が On であることを確認します。
  2. paosResponse を 有効なリダイレクト URI リストに追加します。
  3. Valid Redirect URIs の postResponse URL をコピーし、"+" のすぐ下の空の add text フィールドに貼り付けます。
  4. postResponse を paosResponse` に変更します。(SAML ECP には paosResponse URL が必要です。)
  5. 下部の Save をクリックします。

多くの SAML SP は、グループのユーザーのメンバーシップに基づいて認可を決定します。Red Hat build of Keycloak IdP は、ユーザーグループ情報を管理できますが、IdP が SAML 属性としてユーザーグループを提供するように設定されていない限り、ユーザーのグループは提供されません。

ユーザーのグループを SAML 属性として提供するように IdP を設定するには、以下の手順を実行します。

手順

  1. クライアントの Client scopes タブをクリックします。
  2. 最初の行に配置された専用スコープをクリックします。
  3. Mappers ページで、Add mapper ボタンをクリックし、By configuration を選択します。
  4. Mapper Type リストから Group list を選択します。
  5. Name を group list に設定します。
  6. SAML 属性名を groups に設定します。
  7. Save をクリックします。

残りの手順は $sp_host で実行されます。

8.1.6.3. アイデンティティープロバイダーメタデータの取得
リンクのコピー

IdP でレルムを作成したので、それに関連付けられた IdP メタデータを取得して、Mellon SP がそれを認識するようにする必要があります。以前に作成した /etc/httpd/conf.d/mellon.conf ファイルでは、MellonIdPMetadataFile は /etc/httpd/saml2/idp_metadata.xml として指定されますが、これまでそのファイルは $sp_host に存在していませんでした。

この手順を使用して、IdP からそのファイルを取得します。

手順

  1. このコマンドを使用し、$idp_host の正しい値に置き換えてください。 

    curl -k -o /etc/httpd/saml2/idp_metadata.xml \
https://$idp_host/realms/test_realm/protocol/saml/descriptor
    Copy to Clipboard Toggle word wrap

    Mellon が完全に設定されるようになりました。

  2. Apache 設定ファイルの構文チェックを実行するには、以下のコマンドを使用します。 

    apachectl configtest
    Copy to Clipboard Toggle word wrap
    注記

    Configtest は apachectl の -t 引数と同じです。設定テストでエラーが表示される場合には、次に進む前に修正してください。

  3. Apache サーバーを再起動します。 

    systemctl restart httpd.service
    Copy to Clipboard Toggle word wrap

これで、Red Hat build of Keycloak を test_realm の SAML IdP として、mod_auth_mellon を SAML SP としてセットアップし、$idp_host IdP に対して認証することで URL $sp_host/protected (およびその下のすべてのもの) を保護することができました。

第9章 Docker レジストリー
リンクのコピー

注記

Docker 認証はデフォルトで無効になっています。有効化する場合は、機能の有効化と無効化 の章を参照してください。

このセクションでは、Red Hat build of Keycloak を認証サーバーとして使用するように Docker レジストリーを設定する方法を説明します。

Docker レジストリーのセットアップおよび設定方法の詳細は、Docker Registry Configuration Guide を参照してください。

9.1. Docker レジストリー設定ファイルのインストール
リンクのコピー

高度な Docker レジストリー設定を使用しているユーザーの場合は、通常、独自のレジストリー設定ファイルを提供することを推奨します。Red Hat build of Keycloak Docker プロバイダーは、Registry Config File フォーマットオプションを介してこのメカニズムをサポートします。このオプションを選択すると、以下のような出力が生成されます。 

auth:
  token:
    realm: http://localhost:8080/realms/master/protocol/docker-v2/auth
    service: docker-test
    issuer: http://localhost:8080/realms/master
Copy to Clipboard Toggle word wrap

この出力は、既存のレジストリー設定ファイルにコピーできます。ファイルの設定方法に関する詳細は、レジストリー設定ファイル仕様 を参照してください。または 基本的な例 から始めてください。

警告

rootcertbundle フィールドを、Red Hat build of Keycloak レルムの公開鍵の場所に設定することを忘れないでください。認証設定は、この引数なしでは機能しません。

9.2. Docker レジストリー環境変数オーバーライドインストール
リンクのコピー

多くの場合、開発または POC Docker レジストリーに単純な環境変数オーバーライドを使用することが適しています。通常、このアプローチは実稼働環境での使用は推奨されませんが、急場しのぎの方法でレジストリーを起動する必要がある場合には役立ちます。クライアントの詳細から Variable Override フォーマットオプションを使用するだけで、出力は以下のようになります。 

REGISTRY_AUTH_TOKEN_REALM: http://localhost:8080/realms/master/protocol/docker-v2/auth
REGISTRY_AUTH_TOKEN_SERVICE: docker-test
REGISTRY_AUTH_TOKEN_ISSUER: http://localhost:8080/realms/master
Copy to Clipboard Toggle word wrap
警告

REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE を、Red Hat build of Keycloak レルムの公開鍵の場所でオーバーライドする設定を忘れないでください。認証設定は、この引数なしでは機能しません。

9.3. Docker Compose YAML ファイル
リンクのコピー

警告

このインストール方法は、Red Hat build of Keycloak サーバーに対して Docker レジストリーを認証する簡単な方法になります。これは開発のみを目的としており、本番環境または本番環境のような環境で使用しないでください。

zip ファイルインストールメカニズムは、Red Hat build of Keycloak サーバーが Docker レジストリーとどのように対話するかを理解したい開発者向けのクイックスタートを提供します。設定するには、以下を実施します。

手順

  1. 必要なレルムから、クライアント設定を作成します。この時点で、Docker レジストリーはありません。クイックスタートがその部分を処理します。
  2. Action メニューから Docker Compose YAML オプションを選択し、Download adapter config オプションを選択して ZIP ファイルをダウンロードします。
  3. 目的の場所にアーカイブをデプロイメントして、ディレクトリーを開きます。
  4. docker-compose up で Docker レジストリーを起動します。
注記

HTTP Basic 認証フローはフォームを表示しないため、'master' 以外のレルムで Docker レジストリークライアントを設定することを推奨します。

上記の設定が行われ、keycloak サーバーおよび Docker レジストリーが実行されると、Docker 認証が正常に行われるはずです。 

[user ~]# docker login localhost:5000 -u $username
Password: *******
Login Succeeded
Copy to Clipboard Toggle word wrap

第10章 クライアント登録サービス
リンクのコピー

アプリケーションまたはサービスが Red Hat build of Keycloak を使用するには、Red Hat build of Keycloak でクライアントを登録する必要があります。管理者は管理コンソール (または管理 REST エンドポイント) でこれを実行できますが、クライアントは Red Hat build of Keycloak クライアント登録サービスを介して登録することもできます。

クライアント登録サービスは、Red Hat build of Keycloak Client Representations、OpenID Connect Client Meta Data および SAML Entity Descriptors のビルトインサポートを提供します。クライアント登録サービスのエンドポイントは /realms/<realm>/clients-registrations/<provider> です。

サポートされているビルトイン providers は以下のとおりです。

  • default - Red Hat build of Keycloak Client Representation (JSON)
  • install - Red Hat build of Keycloak Adapter Configuration (JSON)
  • openid-connect - OpenID Connect Client Metadata Description (JSON)
  • saml2-entity-descriptor - SAML Entity Descriptor (XML)

以下のセクションでは、異なるプロバイダーを使用する方法を説明します。

10.1. 認証
リンクのコピー

クライアント登録サービスを呼び出すには、通常トークンが必要です。トークンは、ベアラートークン、初期アクセストークン、または登録アクセストークンにすることができます。トークンなしで新しいクライアントを登録する別の方法もありますが、その場合はクライアント登録ポリシーを設定する必要があります (以下を参照)。

10.1.1. ベアラートークン
リンクのコピー

ベアラートークンは、ユーザーまたは Service Account の代わりに発行できます。エンドポイントを呼び出すには、以下のパーミッションが必要です (詳細は サーバー管理ガイド を参照)。

  • create-client または manage-client - クライアントを作成するため
  • view-client または manage-client - クライアントを表示するため
  • manage-client - クライアントを更新または削除する

ベアラートークンを使用してクライアントを作成する場合は、create-client ロールのみを持つサービスアカウントのトークンを使用することを推奨します (詳細は サーバー管理ガイド を参照)。

10.1.2. 初期アクセストークン
リンクのコピー

新しいクライアントを登録するための推奨されるアプローチは、初期アクセストークンを使用することです。初期アクセストークンは、クライアントの作成にのみ使用でき、有効期限を設定できるほか、作成できるクライアントの数に制限を設定できます。

初期アクセストークンは管理コンソールを使用して作成できます。新しい初期アクセストークンを作成するには、最初に管理コンソールでレルムを選択し、左側のメニューで Client をクリックし、ページに表示されるタブの Initial access token をクリックします。

これで、既存の初期アクセストークンを確認できるようになります。アクセスがあれば、不要になったトークンを削除できます。トークンの作成時にのみ、トークンの値を取得できます。新規トークンを作成するには、Create をクリックします。オプションで、トークンの有効期間を追加できるようになりました。また、トークンを使用して作成できるクライアントの数も追加できます。Save をクリックすると、トークンの値が表示されます。

このトークンは後で取得できないため、今すぐこのトークンをコピーして貼り付けることが重要です。コピー/貼り付けを忘れた場合は、このトークンを削除して別のトークンを作成してください。

トークン値は、クライアント登録サービスを呼び出すときに、リクエストの Authorization ヘッダーに追加することにより、標準のベアラートークンとして使用されます。以下に例を示します。 

Authorization: bearer eyJhbGciOiJSUz...
Copy to Clipboard Toggle word wrap

10.1.3. 登録アクセストークン
リンクのコピー

クライアント登録サービス経由でクライアントを作成する場合、応答には登録アクセストークンが含まれます。登録アクセストークンは、後でクライアント設定を取得するアクセスを提供しますが、クライアントを更新または削除するためのアクセスも提供します。登録アクセストークンは、ベアラートークンまたは初期アクセストークンと同じ方法でリクエストに含まれます。

デフォルトでは、登録アクセストークンのローテーションは有効になっています。これは、登録アクセストークンが 1 回だけ有効であることを意味します。トークンが使用されると、応答には新しいトークンが含まれます。登録アクセストークンのローテーションは、クライアントポリシー を使用して無効化できます。

クライアント登録サービスの外部でクライアントが作成された場合、それに関連付けられた登録アクセストークンはありません。管理コンソールから作成できます。これは、特定のクライアントのトークンを失った場合にも便利です。新しいトークンを作成するには、管理コンソールでクライアントを見つけ、Credentials をクリックします。次に、Generate registration access token をクリックします。

10.2. Red Hat build of Keycloak の表現
リンクのコピー

デフォルト のクライアント登録プロバイダーは、クライアントの作成、取得、更新、および削除に使用できます。Red Hat build of Keycloak Client Representation 形式を使用します。これは、たとえばプロトコルマッパーの設定など、管理コンソールから設定できるのとまったく同じように、クライアントを設定するためのサポートを提供します。

クライアントを作成するには、クライアント表現 (JSON) を作成し、/realms/<realm>/clients-registrations/default への HTTP POST 要求を実行します。

登録アクセストークンも含まれる Client Representation を返します。後で設定を取得したり、クライアントを更新または削除したりする場合は、登録アクセストークンをどこかに保存する必要があります。

クライアント表現を取得するには、/realms/<realm>/clients-registrations/default/<client id> に対して HTTP GET リクエストを実行します。

また、新しい登録アクセストークンも返します。

クライアント表示を更新するには、更新されたクライアント表示で HTTP PUT 要求を実行します。これは、/realms/<realm>/clients-registrations/default/<client id> です。

また、新しい登録アクセストークンも返します。

クライアント表現を削除するには、/realms/<realm>/clients-registrations/default/<client id> への HTTP DELETE 要求を実行します。

10.3. Red Hat build of Keycloak のアダプター設定
リンクのコピー

インストール クライアント登録プロバイダーを使用して、クライアントのアダプター設定を取得できます。トークン認証の他に、HTTP Basic 認証を使用してクライアント認証情報で認証することもできます。これには、リクエストに以下のヘッダーが含まれます。 

Authorization: basic BASE64(client-id + ':' + client-secret)
Copy to Clipboard Toggle word wrap

アダプター設定を取得するには、HTTP GET 要求を /realms/<realm>/clients-registrations/install/<client id> に実行します。

パブリッククライアントには認証は必要ありません。これは、JavaScript アダプターの場合、上記の URL を使用して、Red Hat build of Keycloak から直接クライアント設定をロードできることを意味します。

10.4. OpenID Connect 動的クライアント登録
リンクのコピー

Red Hat build of Keycloak は、OAuth 2.0 Dynamic Client Registration Protocol および OAuth 2.0 Dynamic Client Registration Management Protocol を拡張する OpenID Connect Dynamic Client Registration を実装します。

Red Hat build of Keycloak でクライアントを登録するために使用するエンドポイントは、/realms/<realm>/clients-registrations/openid-connect[/<client id>] です。

このエンドポイントは、レルムの OpenID Connect Discovery エンドポイントである /realms/<realm>/.well-known/openid-configuration にも含まれています。

10.5. SAML エンティティー記述子
リンクのコピー

SAML エンティティー記述子エンドポイントは、SAML v2 エンティティー記述子を使用したクライアントの作成のみをサポートします。クライアントの取得、更新、または削除はサポートされません。これらの操作では、Red Hat build of Keycloak 表現エンドポイントを使用する必要があります。クライアントを作成する場合、登録アクセストークンを含む作成されたクライアントに関する詳細が記載された Red Hat build of Keycloak Client Representation が返されます。

クライアントを作成するには、SAML エンティティー記述子を使用して HTTP POST 要求を /realms/<realm>/clients-registrations/saml2-entity-descriptor に実行します。

10.6. CURL の使用例
リンクのコピー

以下の例では、CURL を使用して clientId myclient でクライアントを作成します。eyJhbGciOiJSUz…​ を、適切な初期アクセストークンまたはベアラートークンに置き換える必要があります。 

curl -X POST \
    -d '{ "clientId": "myclient" }' \
    -H "Content-Type:application/json" \
    -H "Authorization: bearer eyJhbGciOiJSUz..." \
    http://localhost:8080/realms/master/clients-registrations/default
Copy to Clipboard Toggle word wrap

10.7. Java クライアント登録 API の使用例
リンクのコピー

クライアント登録 Java API により、Java を使用したクライアント登録サービスが容易になります。使用するには、Maven からの org.keycloak:keycloak-client-registration-api:>VERSION< の依存関係を追加します。

クライアント登録の使用に関する詳細な手順は、JavaDocs を参照してください。以下は、クライアントを作成する例です。eyJhbGciOiJSUz…​ を、適切な初期アクセストークンまたはベアラートークンに置き換える必要があります。 

String token = "eyJhbGciOiJSUz...";

ClientRepresentation client = new ClientRepresentation();
client.setClientId(CLIENT_ID);

ClientRegistration reg = ClientRegistration.create()
    .url("http://localhost:8080", "myrealm")
    .build();

reg.auth(Auth.token(token));

client = reg.create(client);

String registrationAccessToken = client.getRegistrationAccessToken();
Copy to Clipboard Toggle word wrap

10.8. クライアント登録ポリシー
リンクのコピー

注記

現在の計画では、クライアント登録ポリシーを削除し、代わりに サーバー管理ガイド に記載されているクライアントポリシーを採用する予定です。クライアントポリシーはより柔軟であり、より多くのユースケースに対応します。

現在、Red Hat build of Keycloak では、クライアント登録サービスを介して新しいクライアントを登録する 2 つの方法をサポートしています。

  • 認証された要求 - 新しいクライアントを登録する要求には、上記のように Initial Access Token または Bearer Token のいずれかが含まれている必要があります。
  • 特定の要求 - 新しいクライアントを登録する要求にトークンを含める必要はありません。

匿名のクライアント登録要求は非常に興味深く強力な機能ですが、誰もが制限なしに新しいクライアントを登録できることは、通常は望まれません。このため、クライアント登録ポリシー SPI があります。これは、新しいクライアントを登録できるユーザーとその条件を制限する方法を提供します。

Red Hat build of Keycloak 管理コンソールで、Client Registration タブをクリックして、Client Registration Policies サブタブをクリックします。ここでは、匿名要求に対して、デフォルトで設定されているポリシーと、認証された要求に対して設定されているポリシーを確認できます。

注記

匿名要求 (トークンなしの要求) は、新しいクライアントの作成 (登録) のためだけに許可されます。したがって、匿名要求を介して新しいクライアントを登録すると、応答には登録アクセストークンが含まれます。これは、特定のクライアントの読み取り、更新、または削除要求に使用する必要があります。ただし、匿名登録からこの登録アクセストークンを使用する場合も、匿名ポリシーが適用されます。そのため、たとえば、Trusted Hosts ポリシーがある場合は、更新クライアントのリクエストも Trusted Host から取得する必要があります。たとえば、クライアントの更新時や、Consent Required が存在する場合には、Consent Required を無効にすることはできません。

現在、以下のポリシー実装があります。

  • Trusted Hosts Policy: 信頼されたホストおよび信頼済みドメインのリストを設定できます。クライアント登録サービスへの要求は、それらのホストまたはドメインからのみ送信できます。信頼できない IP から送信されたリクエストは拒否されます。新たに登録したクライアントの URL も、信頼できるホストまたはドメインを使用する必要があります。たとえば、信頼されていないホストを参照するクライアントの Redirect URI を設定することはできません。デフォルトでは、ホワイトリストに登録されているホストがないため、匿名クライアントの登録は事実上無効になっています。
  • Consent Required Policy: 新しく登録されたクライアントでは、Consent Allowed スイッチが有効になります。したがって、認証が成功した後、ユーザーがパーミッション (クライアントスコープ) を承認する必要があるときに、常に同意画面が表示されます。これは、ユーザーが承認しない限り、クライアントが個人情報へのアクセスやユーザーのパーミッションを持たないことを意味します。
  • Protocol Mappers Policy: ホワイトリストに登録されたプロトコルマッパー実装のリストを設定できます。ホワイトリストに登録されていないプロトコルマッパーが含まれている場合、新しいクライアントを登録または更新することはできません。このポリシーは認証されたリクエストにも使用されるため、認証されたリクエストの場合でも、使用できるプロトコルマッパーにいくつかの制限があることに注意してください。
  • Client Scope Policy: 新しく登録または更新されたクライアントで使用できる Client Scopes をホワイトリスト化できます。デフォルトではホワイトリスト化されたスコープはありません。デフォルトでは、Realm Default Client Scopes として定義されるクライアントスコープのみがホワイトリスト化されます。
  • Full Scope Policy: 新しく登録されたクライアントでは、Full Scope Allowed が無効になります。つまり、指定されたレルムロールや、他のクライアントのクライアントロールはありません。
  • Max Clients Policy: レルム内の現在のクライアント数が指定の制限と同じかそれより多い場合、登録を拒否します。匿名登録では、デフォルトで 200 になります。
  • Client Disabled Policy: 新たに登録されたクライアントが無効になります。これは、管理者が新しく登録されたすべてのクライアントを手動で承認して有効にする必要があることを意味します。このポリシーは、匿名登録でもデフォルトで使用されません。

第11章 クライアント登録 CLI
リンクのコピー

クライアント登録 CLI は、アプリケーション開発者が、Red Hat build of Keycloak と統合する際に、セルフサービス方式で新しいクライアントを設定するためのコマンドラインインターフェイス (CLI) ツールです。これは、Red Hat build of Keycloak クライアント登録 REST エンドポイントと対話するように特別に設計されています。

Red Hat build of Keycloak を使用できるようにするには、すべてのアプリケーションでクライアント設定を作成または取得する必要があります。通常、一意のホスト名でホストされる新規アプリケーションごとに新規クライアントを設定します。アプリケーションが Red Hat build of Keycloak と対話する場合、Red Hat build of Keycloak がログインページ、シングルサインオン (SSO) セッション管理、およびその他のサービスを提供できるように、アプリケーションはクライアント ID で自身を識別します。

クライアント登録 CLI を使用してコマンドラインからアプリケーションクライアントを設定できます。また、これをシェルスクリプトで使用できます。

特定のユーザーが Client Registration CLI を使用できるようにするには、通常、Red Hat build of Keycloak 管理者は、管理コンソールを使用して、適切なロールを持つ新しいユーザーを設定するか、新しいクライアントとクライアントシークレットを設定して、Client Registration REST API へのアクセスを許可します。

11.1. クライアント登録 CLI で使用する新しい一般ユーザーの設定
リンクのコピー

手順

  1. 管理コンソール (例: http://localhost:8080) に admin としてログインします。
  2. 管理するレルムを選択します。
  3. 既存のユーザーを使用する場合は、そのユーザーを選択して編集します。それ以外の場合は、新しいユーザーを作成します。
  4. Role Mapping、Assign role を選択します。オプションリストから、Filter by clients をクリックします。検索バーに manage-clients と入力します。ロールを選択します。または、マスターレルムを使用している場合は、NAME-realm のロールを選択します。NAME はターゲットレルムの名前です。他のレルムへのアクセスをマスターレルムのユーザーに付与できます。
  5. Assign をクリックすると、フルセットのクライアント管理パーミッションが付与されます。別のオプションとして、読み取り専用 view-clients または create-client を選択して、新規クライアントを作成します。

  6. Available Roles、manage-client を選択して、フルセットのクライアント管理パーミッションを付与します。別のオプションとして、読み取り専用 view-clients または create-client を選択して、新規クライアントを作成します。

    注記

    これにより、ユーザーは初期アクセストークンまたは登録アクセストークンを使用せずに、操作を実行する権限がユーザーに付与されます (詳細は、クライアント登録サービス を参照)。

realm-management ロールをユーザーに割り当てることはできません。この場合、ユーザーは引き続きクライアント登録 CLI でログインできますが、初期アクセストークンなしでは使用することはできません。トークンなしで操作を実行しようとすると、403 Forbidden エラーが発生します。

管理者は、管理コンソールの Initial Access Token タブ Clients エリアから初期アクセストークンを発行できます。

11.2. クライアント登録 CLI で使用するクライアントの設定
リンクのコピー

デフォルトでは、サーバーはクライアント登録 CLI を admin-cli クライアントとして認識します。これは、新しいレルムごとに自動的に設定されます。ユーザー名を使用してログインする場合、追加のクライアント設定は必要ありません。

手順

  1. クライアント登録 CLI に別のクライアント設定を使用する場合は、クライアントを作成します (例: reg-cli)。
  2. Standard Flow Enabled チェックボックスをオフにします。
  3. Client authentication を On に切り替えてセキュリティーを強化します。

  4. 使用するアカウントの種類を選択します。

    1. クライアントに関連付けられたサービスアカウントを使用する場合は、Service accounts roles をオンにします。
    2. 通常のユーザーアカウントを使用する場合は、Direct access grants をオンにします。
  5. Next をクリックします。
  6. Save をクリックします。

  7. Credentials タブをクリックします。

    Client Id and Secret または Signed JWT のいずれかを設定します。

  8. サービスアカウントロールを使用している場合は、Service Account Roles タブをクリックします。

    サービスアカウントのアクセス権を設定するためのロールを選択します。選択するロールの詳細は、「クライアント登録 CLI で使用する新しい一般ユーザーの設定」 を参照してください。

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

kcreg config credentials を実行するときは、--secret オプションを使用して、設定したシークレットを指定します。

  • kcreg config credentials の実行時に使用する clientId (例: --client reg-cli) を指定します。
  • サービスアカウントを有効にすると、kcreg config credentials の実行時にユーザーの指定を省略し、クライアントシークレットまたはキーストア情報のみを提供します。

11.3. クライアント登録 CLI のインストール
リンクのコピー

クライアント登録 CLI は、Red Hat build of Keycloak サーバーディストリビューション内にパッケージ化されています。bin ディレクトリー内に実行スクリプトを見つけることができます。Linux スクリプトは kcreg.sh と呼ばれ、Windows スクリプトは kcreg.bat と呼ばれます。

ファイルシステム上の任意の場所からクライアントを使用できるようにクライアントを設定する際に、Red Hat build of Keycloak サーバーディレクトリーを PATH に追加します。

たとえば、以下のようになります。

  • Linux: 
$ export PATH=$PATH:$KEYCLOAK_HOME/bin
$ kcreg.sh
Copy to Clipboard Toggle word wrap
  • Windows: 
c:\> set PATH=%PATH%;%KEYCLOAK_HOME%\bin
c:\> kcreg
Copy to Clipboard Toggle word wrap

KEYCLOAK_HOME は、Red Hat build of Keycloak Server ディストリビューションが展開されたディレクトリーを指定します。

11.4. クライアント登録 CLI の使用
リンクのコピー

手順

  1. 認証情報を使用してログインし、認証されたセッションを開始します。

  2. Client Registration REST エンドポイントでコマンドを実行します。

    たとえば、以下のようになります。

    • Linux: 

      $ kcreg.sh config credentials --server http://localhost:8080 --realm demo --user user --client reg-cli
$ kcreg.sh create -s clientId=my_client -s 'redirectUris=["http://localhost:8980/myapp/*"]'
$ kcreg.sh get my_client
      Copy to Clipboard Toggle word wrap

    • Windows: 

      c:\> kcreg config credentials --server http://localhost:8080 --realm demo --user user --client reg-cli
c:\> kcreg create -s clientId=my_client -s "redirectUris=[\"http://localhost:8980/myapp/*\"]"
c:\> kcreg get my_client
      Copy to Clipboard Toggle word wrap
      注記

      実稼働環境では、https: で Red Hat build of Keycloak にアクセスする必要があります。そうすることで、トークンをネットワークスニファーに公開しないようにする必要があります。

  3. Java のデフォルト証明書トラストストアに含まれる信頼される認証局 (CA) のいずれかによってサーバーの証明書が発行されていない場合は、truststore.jks ファイルを準備し、クライアント登録 CLI にこれを使用するように指示します。

    たとえば、以下のようになります。

    • Linux: 

      $ kcreg.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks
      Copy to Clipboard Toggle word wrap

    • Windows: 

      c:\> kcreg config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\truststore.jks
      Copy to Clipboard Toggle word wrap

11.4.1. ログイン
リンクのコピー

手順

  1. クライアント登録 CLI でログインするときに、サーバーエンドポイント URL およびレルムを指定します。
  2. ユーザー名またはクライアント ID を指定します。これにより、特別なサービスアカウントが使用されます。ユーザー名を使用する場合は、指定したユーザーのパスワードを使用する必要があります。クライアント ID を使用する場合は、パスワードの代わりにクライアントシークレットまたは 署名済み JWT を使用します。

ログイン方法に関係なく、ログインするアカウントには、クライアント登録操作を実行するための適切な権限が必要です。マスター以外のレルムのアカウントには、同じレルム内のクライアントを管理するためのパーミッションのみを持つことができる点に注意してください。異なるレルムを管理する必要がある場合は、異なるレルムで複数のユーザーを設定するか、master レルムで 1 つのユーザーを作成し、異なるレルムでクライアントを管理するロールを追加できます。

クライアント登録 CLI を使用してユーザーを設定することはできません。管理コンソールの Web インターフェイスまたは Admin Client CLI を使用してユーザーを設定します。詳細は、サーバー管理ガイド を参照してください。

kcreg が正常にログインすると、認可トークンを受け取り、プライベート設定ファイルに保存します。これにより、後続の呼び出しにトークンを使用できます。設定ファイルの詳細は、「代替設定の使用」 を参照してください。

クライアント登録 CLI の使用方法の詳細は、組み込みヘルプを参照してください。

たとえば、以下のようになります。

  • Linux: 
$ kcreg.sh help
Copy to Clipboard Toggle word wrap
  • Windows: 
c:\> kcreg help
Copy to Clipboard Toggle word wrap

認証セッションの開始に関する詳細は、kcreg config credentials --help を参照してください。

11.4.2. 代替設定の使用
リンクのコピー

デフォルトでは、クライアント登録 CLI は、ユーザーのホームディレクトリーにあるデフォルトの場所 (./.keycloak/kcreg.config) で設定ファイルを自動的に維持します。--config オプションを使用して異なるファイルまたは場所を指定し、複数の認証セッションを並行して管理することができます。単一のスレッドから、単一の設定ファイルに関連付けられる操作を実行するための最も安全な方法です。

重要

システム上の他のユーザーには、設定ファイルを表示しないでください。設定ファイルには、非公開にしておく必要のあるアクセストークンとシークレットが含まれています。

すべてのコマンドで --no-config オプションを使用すると、シークレットを設定ファイル内に格納しないようにすることができます。各 kcreg 呼び出しですべての認証情報を指定します。

11.4.3. 初期アクセスおよび登録アクセストークン
リンクのコピー

使用する Red Hat build of Keycloak サーバーでアカウントを設定していない開発者は、クライアント登録 CLI を使用できます。これは、レルム管理者が開発者に初期アクセストークンを発行した場合にのみ可能です。これらのトークンを発行および配布する方法と時期を決定するのは、レルム管理者の責任になります。レルム管理者は、初期アクセストークンの最大有効期間と、それを使用して作成できるクライアントの総数を制限できます。

開発者に初期アクセストークンがある場合、開発者は kcreg config credentials で認証せずにこれを使用して新規クライアントを作成することができます。初期アクセストークンは、設定ファイルに保存するか、kcreg create コマンドの一部として指定できます。

たとえば、以下のようになります。

  • Linux: 
$ kcreg.sh config initial-token $TOKEN
$ kcreg.sh create -s clientId=myclient
Copy to Clipboard Toggle word wrap

あるいは、以下のような場合もあります。 

$ kcreg.sh create -s clientId=myclient -t $TOKEN
Copy to Clipboard Toggle word wrap
  • Windows: 
c:\> kcreg config initial-token %TOKEN%
c:\> kcreg create -s clientId=myclient
Copy to Clipboard Toggle word wrap

あるいは、以下のような場合もあります。 

c:\> kcreg create -s clientId=myclient -t %TOKEN%
Copy to Clipboard Toggle word wrap

初期アクセストークンを使用する場合、サーバーの応答には、新しく発行された登録アクセストークンが含まれます。そのクライアントの後続の操作は、そのトークンで認証することで実行する必要があります。これは、そのクライアントに対してのみ有効です。

クライアント登録 CLI は、プライベート設定ファイルを自動的に使用して、このトークンを保存し、関連付けられたクライアントで使用します。同じ設定ファイルがすべてのクライアント操作に使用される限り、開発者はこの方法で作成されたクライアントの読み取り、更新、または削除を行うために認証する必要はありません。

初期アクセスおよび登録アクセストークンの詳細は、クライアント登録サービス を参照してください。

クライアント登録 CLI でトークンを設定する方法の詳細は、kcreg config initial-token --help コマンドおよび kcreg config registration-token --help コマンドを実行してください。

11.4.4. クライアント設定の作成
リンクのコピー

通常、認証情報を使用して認証するか、初期アクセストークンを設定した後の最初のタスクは、新しいクライアントを作成することです。多くの場合、準備した JSON ファイルをテンプレートとして使用し、一部の属性を設定したり、上書きすることを推奨します。

以下の例は、JSON ファイルの読み取り、含まれる可能性のあるクライアント ID の上書き、その他の属性の設定、正常な作成後に設定を標準出力に出力する方法を示しています。

  • Linux: 
$ kcreg.sh create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s 'redirectUris=["/myclient/*"]' -o
Copy to Clipboard Toggle word wrap
  • Windows: 
C:\> kcreg create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s "redirectUris=[\"/myclient/*\"]" -o
Copy to Clipboard Toggle word wrap

kcreg create コマンドの詳細は、kcreg create --help を実行します。

kcreg attrs を使用して利用可能な属性をリスト表示できます。多くの設定属性は、有効性または一貫性についてチェックされないことに注意してください。適切な値を指定することが推奨されます。テンプレートに id フィールドを使用せず、kcreg create コマンドに引数として指定しないでください。

11.4.5. クライアント設定の取得
リンクのコピー

kcreg get コマンドを使用して、既存のクライアントを取得できます。

たとえば、以下のようになります。

  • Linux: 
$ kcreg.sh get myclient
Copy to Clipboard Toggle word wrap
  • Windows: 
C:\> kcreg get myclient
Copy to Clipboard Toggle word wrap

クライアント設定をアダプター設定ファイルとして取得することもできます。これは Web アプリケーションでパッケージ化できます。

たとえば、以下のようになります。

  • Linux: 
$ kcreg.sh get myclient -e install > keycloak.json
Copy to Clipboard Toggle word wrap
  • Windows: 
C:\> kcreg get myclient -e install > keycloak.json
Copy to Clipboard Toggle word wrap

kcreg get コマンドの詳細は、kcreg get --help コマンドを実行してください。

11.4.6. クライアント設定の変更
リンクのコピー

クライアント設定の更新方法は 2 つあります。

1 つの方法は、現在の設定を取得してファイルに保存し、編集してサーバーにポストバックした後に、完全に新しい状態をサーバーに送信することです。

たとえば、以下のようになります。

  • Linux: 
$ kcreg.sh get myclient > myclient.json
$ vi myclient.json
$ kcreg.sh update myclient -f myclient.json
Copy to Clipboard Toggle word wrap
  • Windows: 
C:\> kcreg get myclient > myclient.json
C:\> notepad myclient.json
C:\> kcreg update myclient -f myclient.json
Copy to Clipboard Toggle word wrap

2 つ目の方法は、現在のクライアントをフェッチし、そのクライアントのフィールドを設定または削除して、1 つのステップでポストバックします。

たとえば、以下のようになります。

  • Linux: 
$ kcreg.sh update myclient -s enabled=false -d redirectUris
Copy to Clipboard Toggle word wrap
  • Windows: 
C:\> kcreg update myclient -s enabled=false -d redirectUris
Copy to Clipboard Toggle word wrap

適用する変更のみを含むファイルを使用することもできるため、引数として値を多く指定する必要はありません。この場合は、--merge を指定して、JSON ファイルを完全かつ新規の設定として処理するのではなく、既存の設定に適用する属性セットとして処理する必要があることをクライアント登録 CLI に指示します。

たとえば、以下のようになります。

  • Linux: 
$ kcreg.sh update myclient --merge -d redirectUris -f mychanges.json
Copy to Clipboard Toggle word wrap
  • Windows: 
C:\> kcreg update myclient --merge -d redirectUris -f mychanges.json
Copy to Clipboard Toggle word wrap

kcreg update コマンドの詳細は、kcreg update --help コマンドを実行してください。

11.4.7. クライアント設定の削除
リンクのコピー

クライアントを削除するには、以下の例を使用します。

  • Linux: 
$ kcreg.sh delete myclient
Copy to Clipboard Toggle word wrap
  • Windows: 
C:\> kcreg delete myclient
Copy to Clipboard Toggle word wrap

kcreg delete コマンドの詳細は、kcreg delete --help コマンドを実行してください。

11.4.8. 無効な登録アクセストークンの更新
リンクのコピー

--no-config モードを使用して作成、読み取り、更新、および削除 (CRUD) 操作を実行すると、クライアント登録 CLI はユーザーの登録アクセストークンを処理できません。この場合、クライアントに対して最近発行した Registration Access Token の追跡できなくなる可能性があり、manage-clients パーミッションを持つアカウントで認証を行わずに、そのクライアントでの CRUD 操作を追加で実行できなくなります。

パーミッションがある場合は、クライアントの新しい登録アクセストークンを発行し、標準出力に出力したり、任意の設定ファイルに保存したりできます。それ以外の場合は、レルム管理者に、クライアント用の新しい登録アクセストークンを発行して送信するよう依頼する必要があります。--token オプションを使用して、これをすべての CRUD コマンドに渡すことができます。kcreg config registration-token コマンドを使用して新規トークンを設定ファイルに保存し、クライアント登録 CLI にこの時点から自動的に処理させることもできます。

kcreg update-token コマンドの詳細は、kcreg update-token --help コマンドを実行してください。

11.5. トラブルシューティング
リンクのコピー

  • Q: ログイン時にエラーが表示されます: Parameter client_assertion_type is missing [invalid_client]

    A: このエラーは、クライアントが Signed JWT トークン認証情報で設定されていることを意味します。つまり、ログイン時に --keystore パラメーターを使用する必要があります。

第12章 トークン交換の使用
リンクのコピー

注記

トークン交換は プレビュー であり、完全にはサポートされていません。この機能はデフォルトで無効化されています。

有効にするには、--features=preview または --features=token-exchange でサーバーを起動します。

トークンの交換は テクノロジープレビュー であるため、完全にサポートされていません。

注記

内部トークンから内部トークンへの交換 フロー以上のものを使用するには、admin-fine-grained-authz 機能も有効にします。詳細は、機能の有効化と無効化 の章を参照してください。

12.1. トークン交換の仕組み
リンクのコピー

Red Hat build of Keycloak では、トークン交換とは、一連の認証情報またはトークンを使用してまったく異なるトークンを取得するプロセスのことです。クライアントは、信頼性の低いアプリケーションで呼び出したい場合があるため、現在のトークンをダウングレードしたい場合があります。クライアントは、Red Hat build of Keycloak トークンを、リンクされたソーシャルプロバイダーアカウント用に保存されているトークンと交換することを推奨します。他の Red Hat build of Keycloak レルムまたは外部 IDP によって生成された外部トークンを信頼することを推奨します。クライアントでは、ユーザーの権限を借用しなければならない場合があります。以下は、トークン交換に関する Red Hat build of Keycloak の現行機能に関する概要です。

  • クライアントは、特定のクライアント用に作成された既存の Red Hat build of Keycloak トークンを、別のクライアントを対象とした新しいトークンと交換できます。
  • クライアントは、既存の Red Hat build of Keycloak トークンを外部トークン (リンクされた Facebook アカウントなど) と交換できます。
  • クライアントが外部トークンを Red Hat build of Keycloak トークンと交換できる。
  • クライアントはユーザーの権限を借用できます。

Red Hat build of Keycloak におけるトークン交換は、IETF の OAuth トークン交換 仕様の非常に緩い実装です。この仕様を少し拡張し、一部を無視して、他の部分は大まかに解釈しました。これは、レルムの OpenID Connect トークンエンドポイントにおける単純な付与タイプ呼び出しです。 

/realms/{realm}/protocol/openid-connect/token
Copy to Clipboard Toggle word wrap

これは、フォームパラメーター (application/x-www-form-urlencoded) を入力として受け付け、出力は交換を要求したトークンのタイプによって異なります。トークン交換はクライアントエンドポイントであるため、リクエストは呼び出し元のクライアントに対して認証情報を提供する必要があります。パブリッククライアントは、クライアント識別子を form パラメーターとして指定します。機密クライアントは、フォームパラメーターを使用して、クライアント ID とシークレット、Basic 認証、または管理者がレルムで設定したクライアント認証フローを渡すこともできます。

12.1.1. フォームパラメーター
リンクのコピー

client_id
必須の可能性あり。このパラメーターは、認証にフォームパラメーターを使用するクライアントに必要です。Basic 認証、クライアント JWT トークン、またはクライアント証明書認証を使用している場合は、このパラメーターを指定しないでください。
client_secret
必須の可能性あり。このパラメーターは、認証にフォームパラメーターを使用し、認証情報としてクライアントシークレットを使用するクライアントに必要です。レルムのクライアント呼び出しが別の手段で認証されている場合は、このパラメーターは指定しないでください。
grant_type
必須。パラメーターの値は urn:ietf:params:oauth:grant-type:token-exchange にする必要があります。
subject_token
任意。リクエストが行われている当事者の ID を表すセキュリティートークン。これは、既存のトークンを新しいトークンと交換する場合に必要です。
subject_issuer
任意。subject_token の発行者を特定します。トークンが現在のレルムから送信される場合や、発行者が subject_token_type から判断できる場合は空白のままにすることができます。それ以外の場合は指定する必要があります。有効な値は、レルムに設定された ID プロバイダー のエイリアスです。または、特定の ID プロバイダー によって設定された発行者要求 ID です。
subject_token_type
任意。このパラメーターは、subject_token パラメーターで渡されるトークンのタイプです。subject_token がレルムから取得され、アクセストークンである場合、デフォルトは urn:ietf:params:oauth:token-type:access_token に設定されます。外部トークンの場合には、subject_issuer の要件に応じてこのパラメーターを指定する必要がある場合とそうでない場合があります。
requested_token_type
任意。このパラメーターは、クライアントが交換するトークンのタイプを表します。現在、oauth および OpenID Connect トークンタイプのみがサポートされます。このデフォルト値は urn:ietf:params:oauth:token-type:refresh_token であるかどうかによって異なります。この場合、応答内でアクセストークンとリフレッシュトークンの両方が返されます。その他の適切な値は、urn:ietf:params:oauth:token-type:access_token および urn:ietf:params:oauth:token-type:id_token です。
audience
任意。このパラメーターは、新しいトークンを作成するターゲットクライアントを指定します。
requested_issuer
任意。このパラメーターは、クライアントが外部プロバイダーによって作成されたトークンを必要とすることを指定します。レルム内で設定された ID プロバイダー のエイリアスである必要があります。
requested_subject
任意。これは、クライアントが別のユーザーになりすます場合のユーザー名またはユーザー ID を指定します。
scope
任意。このパラメーターは、クライアントが要求する OAuth および OpenID Connect スコープのターゲットセットを表します。返されるスコープは、スコープパラメーターとアクセストークンスコープのカルテジアン積です。
注記

現在、OpenID Connect および OAuth の交換のみをサポートします。SAML ベースのクライアントおよびアイデンティティープロバイダーのサポートは、ユーザーの需要に応じて今後追加される可能性があります。

12.1.2. トークン交換要求からの応答
リンクのコピー

交換呼び出しからの正常な応答は、クライアントが要求する requested-token-type と requested_issuer に依存するコンテンツタイプを含む HTTP 200 応答コードを返します。OAuth が要求するトークンタイプは、OAuth Token Exchange 仕様で説明されているように、JSON ドキュメントを返します。 

{
   "access_token" : ".....",
   "refresh_token" : ".....",
   "expires_in" : "...."
 }
Copy to Clipboard Toggle word wrap

リフレッシュトークンを要求するクライアントは、応答でアクセストークンとリフレッシュトークンの両方を返します。アクセストークンタイプのみを要求するクライアントは、応答でアクセストークンのみを取得します。requested_issuer パラメーターを介して外部発行者を要求するクライアントの有効期限情報は、含まれる場合とそうでない場合があります。

通常、エラー応答は 400 HTTP 応答コードカテゴリーに分類されますが、エラーの重大度に応じて他のエラーステータスコードが返される場合があります。エラー応答には、requested_issuer に依存するコンテンツが含まれる場合があります。OAuth ベースの交換では、以下のように JSON ドキュメントが返される場合があります。 

{
   "error" : "...."
   "error_description" : "...."
}
Copy to Clipboard Toggle word wrap

交換タイプに応じて、追加のエラークレームを返すことができます。たとえば、ユーザーに ID プロバイダーへのリンクがない場合に、OAuth ID プロバイダーには追加の account-link-url 要求が含まれる場合があります。このリンクは、クライアントが開始したリンク要求に使用できます。

注記

トークンの交換のセットアップには、きめ細かな管理パーミッションに関する知識が必要です (詳細は、サーバー管理ガイド を参照)。交換にクライアントパーミッションを付与する必要があります。これは、この章で後ほど説明します。

この章の残りの部分では、セットアップ要件を説明し、さまざまな交換シナリオの例を示します。分かりやすくするために、現在のレルムで作成された最小のトークンを 内部 トークンとして呼び出し、外部レルムまたは ID プロバイダーによって作成されたトークンを 外部 トークンと呼ぶことにします。

12.2. 内部トークンから内部トークンへの交換
リンクのコピー

内部のトークンからトークンへの交換では、特定のクライアントに作成された既存のトークンがあり、このトークンを別のターゲットクライアントに作成された新しいトークンと交換する必要があります。これを実行する理由これは通常、クライアントが自身のために作成したトークンを持っており、アクセストークン内で異なるクレームとパーミッションを必要とする他のアプリケーションに追加の要求を行う必要がある場合に発生します。このタイプの交換が必要となるかもしれないその他の理由は、アプリが信頼性の低いアプリで呼び出す必要があり、現在のアクセストークンを伝播したくない場合の "パーミッションのダウングレード" を実行する必要がある場合です。

12.2.1. 交換のパーミッションの付与
リンクのコピー

別のクライアントのトークンを交換する必要のあるクライアントは、管理コンソールで認可される必要があります。交換するパーミッションを付与するクライアントに、token-exchange の細かいパーミッションを定義する必要があります。

図12.1 ターゲットクライアントパーミッション

ターゲットクライアントパーミッション
View larger image
ターゲットクライアントパーミッション

手順

  1. Permissions Enabled を On に切り替えます。

    図12.2 ターゲットクライアントパーミッション

    ターゲットクライアント交換のパーミッション設定
    View larger image
    ターゲットクライアント交換のパーミッション設定

    そのページには、token-exchange のリンクが表示されます。

  2. そのリンクをクリックして、パーミッションの定義を開始します。

    このセットアップページが表示されます。

    図12.3 ターゲットクライアント交換のパーミッション設定

    ターゲットクライアント交換のパーミッション設定
    View larger image
    ターゲットクライアント交換のパーミッション設定
  3. 画面上部のブレッドクラムで Client details をクリックします。
  4. このパーミッションのポリシーを定義します。
  5. 画面上部のブレッドクラムで Authorization をクリックします。
  6. このパーミッションのポリシーを定義します。
  7. Policies タブをクリックします。

  8. Create policy ボタンをクリックして Client を作成します。

    図12.4 クライアントポリシーの作成

    クライアントポリシーの作成
    View larger image
    クライアントポリシーの作成
  9. トークン交換を要求する認証されたクライアントである、開始クライアントを入力します。

  10. このポリシーを作成したら、ターゲットクライアントの token-exchange パーミッションに戻り、定義したクライアントポリシーを追加します。

    図12.5 クライアントポリシーの適用

    クライアントポリシーの適用
    View larger image
    クライアントポリシーの適用

これでクライアントを呼び出すパーミッションがある。これを正しく行わないと、エクスチェンジを作成しようとすると、403 Forbidden 応答が返されます。

12.2.2. リクエストの作成
リンクのコピー

クライアントが、既存のトークンを他のクライアントをターゲットにしたトークンと交換する場合は、audience パラメーターを使用します。このパラメーターは、管理コンソールで設定したターゲットクライアントのクライアント識別子である必要があります。 

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=...." \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:refresh_token" \
    -d "audience=target-client" \
    http://localhost:8080/realms/myrealm/protocol/openid-connect/token
Copy to Clipboard Toggle word wrap

subject_token パラメーターは、ターゲットレルムのアクセストークンである必要があります。requested_token_type パラメーターがリフレッシュトークンタイプである場合、応答にはアクセストークン、リフレッシュトークン、および有効期限が含まれます。以下は、この呼び出しから返される JSON 応答の例です。

audience パラメーターが設定されていない場合に、パラメーターの値はデフォルトでトークン交換要求を行うクライアントに設定されます。

機密クライアントとは異なり、パブリッククライアントは他のクライアントからのトークンを使用してトークン交換を実行することはできません。subject_token を指定する場合には、トークンを発行した (機密の) クライアントと、リクエストを行ったクライアントが同じである必要があります。別のクライアントに対して発行された場合には、リクエストを行ったクライアントは、トークンに設定されたオーディエンスに含まれている必要があります。

ターゲットの audience (要求を行うクライアントとは別のクライアント) を明示的に設定する場合に、token-exchange のスコープのパーミッションを audience パラメーターに指定されたクライアントに設定して、クライアントが要求を出して交換が正常に完了するようにしてください。 

{
   "access_token" : "....",
   "refresh_token" : "....",
   "expires_in" : 3600
}
Copy to Clipboard Toggle word wrap

12.3. 内部トークンから外部トークンへの交換
リンクのコピー

レルムトークンを、外部 ID プロバイダーによって作成された外部トークンと交換できます。この外部 ID プロバイダーは、管理コンソールの ID プロバイダー セクション内で設定する必要があります。現時点で、OAuth/OpenID Connect ベースの外部 ID プロバイダーのみがサポートされます。これには、すべてのソーシャルプロバイダーが含まれます。Red Hat build of Keycloak は外部プロバイダーへのバックチャネル交換を実行しません。そのため、アカウントがリンクされていない場合は、外部トークンを取得できなくなります。これらの条件の 1 つの外部トークンを取得できるようにするには、以下の条件を満たしている必要があります。

  • ユーザーは、少なくとも 1 回、外部 ID プロバイダーを使用してログインしている必要があります。
  • ユーザーは、ユーザーアカウントサービスを使用して、外部 ID プロバイダーとリンクされている必要があります。
  • このユーザーアカウントは、クライアント起点のアカウントリンク API を使用して、外部の ID プロバイダー経由でリンクされました。

最後に、外部 ID プロバイダーがトークンを保存するように設定されている必要があります。または、上記のアクションの 1 つが、交換する内部トークンと同じユーザーセッションで実行されている必要があります。

アカウントがリンクされていない場合、交換応答には、アカウントを確立するために使用できるリンクが含まれます。詳細は、リクエストの作成 セクションで説明されています。

12.3.1. 交換のパーミッションの付与
リンクのコピー

内部から外部へのトークン交換要求は、外部 ID プロバイダーとトークンを交換できるパーミッションを呼び出し元のクライアントに付与するまで、403、Forbidden 応答で拒否されます。クライアントにパーミッションを付与するには、ID プロバイダーの設定ページの Permissions タブに移動します。

図12.6 ID プロバイダーパーミッション

アイデンティティープロバイダー交換のパーミッション
View larger image
アイデンティティープロバイダー交換のパーミッション

手順

  1. Permissions Enabled を On に切り替えます。

    図12.7 ID プロバイダーパーミッション

    アイデンティティープロバイダー交換のパーミッションセット
    View larger image
    アイデンティティープロバイダー交換のパーミッションセット

    ページには、token-exchange のリンクが表示されます。

  2. リンクをクリックして、パーミッションの定義を開始します。

    このセットアップページが表示されます。

    図12.8 アイデンティティープロバイダー交換のパーミッション設定

    アイデンティティープロバイダー交換のパーミッション設定
    View larger image
    アイデンティティープロバイダー交換のパーミッション設定
  3. 画面上部のブレッドクラムで Client details をクリックします。

  4. Policies タブをクリックして、クライアントポリシーを作成します。

    図12.9 クライアントポリシーの作成

    クライアントポリシーの作成
    View larger image
    クライアントポリシーの作成
  5. トークン交換を要求する認証されたクライアントである、開始クライアントを入力します。

  6. ID プロバイダーの token-exchange パーミッションに戻り、定義したクライアントポリシーを追加します。

    図12.10 クライアントポリシーの適用

    クライアントポリシーの適用
    View larger image
    クライアントポリシーの適用

これでクライアントを呼び出すパーミッションがある。これを正しく行わないと、エクスチェンジを作成しようとすると、403 Forbidden 応答が返されます。

12.3.2. リクエストの作成
リンクのコピー

クライアントが既存の内部トークンを外部に交換する場合には、requested_issuer パラメーターを指定します。このパラメーターは、設定済みのアイデンティティープロバイダーのエイリアスである必要があります。 

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=...." \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    -d "requested_issuer=google" \
    http://localhost:8080/realms/myrealm/protocol/openid-connect/token
Copy to Clipboard Toggle word wrap

subject_token パラメーターは、ターゲットレルムのアクセストークンである必要があります。requested_token_type パラメーターは urn:ietf:params:oauth:token-type:access_token であるか、空欄のままにする必要があります。現時点では、他の要求されたトークンタイプはサポートされません。以下は、この呼び出しから返される正常な JSON 応答の例です。 

{
   "access_token" : "....",
   "expires_in" : 3600
   "account-link-url" : "https://...."
}
Copy to Clipboard Toggle word wrap

外部 ID プロバイダーが何らかの理由でリンクされていない場合、以下の JSON ドキュメントで HTTP 400 応答コードが表示されます。 

{
   "error" : "....",
   "error_description" : "..."
   "account-link-url" : "https://...."
}
Copy to Clipboard Toggle word wrap

error 要求は、token_expired または not_linked のいずれかになります。クライアントが クライアント起点のアカウントリンク を実行できるように、account-link-url 要求が提供されます。ほとんど (あるいはすべて) のプロバイダーでは、ブラウザー OAuth プロトコルを使用したリンクが必要です。account-link-url では、単に redirect_uri クエリーパラメーターを追加し、ブラウザーに転送してリンクを実行できます。

12.4. 外部トークンから内部トークンへの交換
リンクのコピー

内部トークンの外部 ID プロバイダーが作成した外部トークンを信頼し、交換できます。これはレルム間をブリッジしたり、ソーシャルプロバイダーからのトークンを信頼したりするために使用できます。新しいユーザーが存在しない場合はレルムにインポートされるという点で、ID プロバイダーのブラウザーログインと同様に機能します。

注記

外部トークン交換に関する現在の制限として、外部トークンが既存のユーザーにマップされている場合、既存のユーザーが外部 ID プロバイダーへのアカウントリンクをすでに持っていない限り、交換が許可されない点があります。

交換が完了すると、レルム内にユーザーセッションが作成され、requested_token_type パラメーターの値に応じてアクセストークンおよび更新トークンが送信されます。この新しいユーザーセッションは、タイムアウトするまで、またはこの新しいアクセストークンを渡すレルムのログアウトエンドポイントを呼び出すまで、アクティブなままである点に注意してください。

これらのタイプの変更には、管理コンソールで設定済みのアイデンティティープロバイダーが必要でした。

注記

SAML アイデンティティープロバイダーは現時点ではサポートされていません。Twitter トークンも交換できません。

12.4.1. 交換のパーミッションの付与
リンクのコピー

外部トークン交換を行う前に、呼び出し元のクライアントに交換を行うためのパーミッションを与えます。このパーミッションは、内部から外部へのパーミッションが付与される 方法と同じ方法で付与されます。

呼び出し以外のクライアントを参照する値を持つ audience パラメーターを指定する場合、audience パラメーターに固有のターゲットクライアントに交換するための呼び出しクライアントのパーミッションも付与する必要があります。これを行う方法は、このセクションで すでに説明 されています。

12.4.2. リクエストの作成
リンクのコピー

subject_token_type は、urn:ietf:params:oauth:token-type:access_token または urn:ietf:params:oauth:token-type:jwt のいずれかである必要があります。タイプが urn:ietf:params:oauth:token-type:access_token の場合は、subject_issuer パラメーターを指定する必要があります。これは設定された ID プロバイダーのエイリアスです。タイプが urn:ietf:params:oauth:token-type:jwt の場合、プロバイダーは、プロバイダーのエイリアスである JWT 内の iss (issuer) 要求を介して照合されます。これはプロバイダーのエイリアスであるか、プロバイダー設定内の登録済み issuer である必要があります。

検証のために、トークンがアクセストークンである場合、プロバイダーのユーザー情報サービスが呼び出されてトークンが検証されます。呼び出しに成功すると、アクセストークンが有効であることを意味します。サブジェクトトークンが JWT であり、プロバイダーで署名検証が有効になっている場合は、それが試行されます。それ以外の場合は、デフォルトでユーザー情報サービスも呼び出してトークンを検証します。

デフォルトでは、作成された内部トークンは、呼び出し元のクライアントを使用して、呼び出し元のクライアント用に定義されたプロトコルマッパーを使用してトークンの内容を判別します。または、audience パラメーターを使用して別のターゲットクライアントを指定することもできます。 

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=...." \
    -d "subject_issuer=myOidcProvider" \
    --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
    -d "audience=target-client" \
    http://localhost:8080/realms/myrealm/protocol/openid-connect/token
Copy to Clipboard Toggle word wrap

requested_token_type パラメーターがリフレッシュトークンタイプである場合、応答にはアクセストークン、リフレッシュトークン、および有効期限が含まれます。以下は、この呼び出しから返される JSON 応答の例です。 

{
   "access_token" : "....",
   "refresh_token" : "....",
   "expires_in" : 3600
}
Copy to Clipboard Toggle word wrap

12.5. 権限借用
リンクのコピー

内部トークンと外部トークン交換の場合、クライアントは、ユーザーに代わって別のユーザーになりすますように要求できます。たとえば、サポートエンジニアが問題をデバッグできるように、ユーザーになりすます必要のある管理アプリケーションがある場合などです。

12.5.1. 交換のパーミッションの付与
リンクのコピー

サブジェクトトークンが表すユーザーには、他のユーザーになりすますためのパーミッションが必要です。このパーミッションを有効にする方法は、サーバー管理ガイド を参照してください。これは、ロールまたは粒度の細かい管理者権限を介して実行できます。

12.5.2. リクエストの作成
リンクのコピー

requested_subject パラメーターを追加で指定しない限り、他の章の説明どおりに要求を行います。このパラメーターの値は、ユーザー名またはユーザー ID である必要があります。 

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=...." \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    -d "audience=target-client" \
    -d "requested_subject=wburke" \
    http://localhost:8080/realms/myrealm/protocol/openid-connect/token
Copy to Clipboard Toggle word wrap

12.6. ダイレクトの Naked Impersonation
リンクのコピー

subject_token を指定せずに内部トークン交換要求を行うことができます。これは、クライアントがレルム内の任意のユーザーになりすますことができるため、クライアントに多くの信頼を置くことから、ダイレクトの Naked Impersonation と呼ばれます。交換するサブジェクトトークンを取得できないアプリケーションをブリッジするために、これが必要になる場合があります。たとえば、LDAP と直接ログインを実行するレガシーアプリケーションを統合している場合があります。この場合、レガシーアプリケーションはユーザー自身を認証できますが、トークンを取得することはできません。

警告

クライアントにダイレクトの Naked Impersonation を有効にすることは非常に危険です。クライアントの認証情報が盗まれた場合、そのクライアントは、システム内の任意のユーザーになりすますことができます。

12.6.1. 交換のパーミッションの付与
リンクのコピー

audience パラメーターを指定すると、呼び出し元のクライアントにはクライアントへの交換パーミッションが必要です。これを設定する方法は、この章の前半で説明しています。

さらに、呼び出し元のクライアントには、ユーザーになりすますためのアクセス許可を付与する必要があります。

手順

  1. メニューの Users をクリックします。

  2. Permissions タブをクリックします。

    図12.11 ユーザー権限

    ユーザー権限
    View larger image
    ユーザー権限

  3. Permissions Enabled を On に切り替えます。

    図12.12 ID プロバイダーパーミッション

    ユーザーのなりすましパーミッションセット
    View larger image
    ユーザーのなりすましパーミッションセット

    ページには、impersonate リンクが表示されます。

  4. そのリンクをクリックして、パーミッションの定義を開始します。

    このセットアップページが表示されます。

    図12.13 ユーザーのなりすましパーミッションの設定

    ユーザーのなりすましパーミッションの設定
    View larger image
    ユーザーのなりすましパーミッションの設定
  5. 画面上部のブレッドクラムで Client details をクリックします。
  6. このパーミッションのポリシーを定義します。

  7. Policies タブに移動し、クライアントポリシーを作成します。

    図12.14 クライアントポリシーの作成

    クライアントポリシーの作成
    View larger image
    クライアントポリシーの作成
  8. トークン交換を要求する認証されたクライアントである、開始クライアントを入力します。

  9. ユーザーの impersonation パーミッションに戻り、定義したクライアントポリシーを追加します。

    図12.15 クライアントポリシーの適用

    クライアントポリシーの適用
    View larger image
    クライアントポリシーの適用

クライアントには、ユーザーの権限を借用できるパーミッションがあります。これを正しく行わないと、このタイプの交換を行おうとすると、403 Forbidden 応答が返されます。

注記

パブリッククライアントは、ダイレクトの Naked Impersonation を行うことはできません。

12.6.2. リクエストの作成
リンクのコピー

要求を行うには、requested_subject パラメーターを指定します。これは、有効なユーザーのユーザー名またはユーザー ID である必要があります。必要に応じて、audience パラメーターを指定することもできます。 

curl -X POST \
    -d "client_id=starting-client" \
    -d "client_secret=the client secret" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "requested_subject=wburke" \
    http://localhost:8080/realms/myrealm/protocol/openid-connect/token
Copy to Clipboard Toggle word wrap

12.7. サービスアカウントでアクセス許可モデルをデプロイメント
リンクのコピー

クライアントに交換のパーミッションを与える場合、必ずしもすべてのクライアントに対してそれらのパーミッションを手動で有効にしません。クライアントにサービスアカウントが関連付けられている場合、ロールを使用してパーミッションをグループ化し、クライアントのサービスアカウントにロールを割り当てることで交換パーミッションを割り当てることができます。たとえば、naked-exchange ロールと、そのロールを持つサービスアカウントが、そのままの交換を実行できるように定義することができます。

12.8. 交換の脆弱性
リンクのコピー

トークン交換を許可し始める際に、認識し、注意しなければならないさまざまなことがあります。

1 つ目はパブリッククライアントです。パブリッククライアントは、交換を実行するためのクライアント認証情報を持っていないか、これを必要としません。有効なトークンを持っていれば、誰でもパブリッククライアントに なりすまし て、そのパブリッククライアントが許可されている処理を実行できてしまいます。レルムが管理するクライントで信頼できないクライアントが存在する場合、パブリッククライアントはパーミッションモデルに脆弱性を開放する可能性があります。この理由により、ダイレクトの Naked 交換は、パブリッククライアントを許可せず、呼び出し元のクライアントがパブリックの場合にエラーを表示して中止します。

Facebook や Google などが提供するソーシャルトークンをレルムトークンと交換することができます。これらのソーシャル Web サイトで、偽のアカウントを作成することは難しくないため、交換トークンで許可されていることには注意し、慎重に対応してください。デフォルトの Role、Group、およびアイデンティティープロバイダーマッパーを使用して、外部のソーシャルユーザーに割り当てられた属性とロールを制御します。

ダイレクトの Naked の交換は非常に危険です。クライアントの認証情報をリークしない呼び出し元のクライアントに多大な信頼を置いています。これらの認証情報がリークされる場合、盗む側はシステム内の誰かになりすますことができます。これは、既存のトークンを持つ機密クライアントと直接対照的です。認証には、アクセストークンとクライアント認証情報の 2 つの要素があり、1 人のユーザーのみを処理します。したがって、ダイレクトの Naked の交換は控えめに使用してください。

第13章 Red Hat build of Keycloak 管理クライアント
リンクのコピー

Red Hat build of Keycloak 管理クライアントは、Red Hat build of Keycloak 管理 REST API へのアクセスと使用を容易にする Java ライブラリーです。このライブラリーは実行時に Java 11 以上を必要とします (この要件は RESTEasy 依存関係により強制されます)。アプリケーションからこれを使用するには、keycloak-admin-client ライブラリーへの依存関係を追加します。たとえば、Maven を使用する場合は以下を実行します。 

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client</artifactId>
    <version>999.0.0-SNAPSHOT</version>
</dependency>
Copy to Clipboard Toggle word wrap

次の例は、Java クライアントライブラリーを使用してマスターレルムの詳細を取得する方法を示しています。 

import org.keycloak.admin.client.Keycloak;
import org.keycloak.representations.idm.RealmRepresentation;
...

Keycloak keycloak = Keycloak.getInstance(
    "http://localhost:8080",
    "master",
    "admin",
    "password",
    "admin-cli");
RealmRepresentation realm = keycloak.realm("master").toRepresentation();
Copy to Clipboard Toggle word wrap

管理クライアントの完全な Javadoc は、API ドキュメント で入手できます。

13.1. Red Hat build of Keycloak サーバーとの互換性
リンクのコピー

Red Hat build of Keycloak の管理クライアントは、Red Hat build of Keycloak サーバーの複数のバージョンで動作することを目的としています。管理クライアントは、クライアントより後にリリースされた Red Hat build of Keycloak サーバーの新しいバージョンと、以前にリリースされた Red Hat build of Keycloak サーバーの古いバージョンでサポートされる場合があります。この変更の結果、要求/応答本体の JSON プロパティーを表す基礎となる「表現」クラス (前のセクションで示した RealmRepresentation クラスなど) の Java フィールドは、クライアントとサーバーでまったく同じにならない可能性があります。

互換性の問題を回避するには、管理クライアントによって内部的に使用される com.fasterxml.jackson.databind.ObjectMapper クラスが、次の 2 つのプロパティーで初期化されていることを確認します。 

objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
Copy to Clipboard Toggle word wrap

上記のように管理クライアント作成の基本的な方法を使用している場合、管理クライアントはデフォルトで org.keycloak.admin.client.JacksonProvider クラスを使用して ObjectMapper を作成し、これらのプロパティーが自動的に追加されるため、これらのプロパティーはデフォルトで追加されます。ただし、Keycloak オブジェクトを作成するときに独自の customJacksonProvider を注入する場合は、互換性の問題を回避するために、オブジェクトマッパーが上記のプロパティーで初期化されていることを確認してください。

たとえば、管理クライアントが独自の MyCustomJacksonProvider クラスを使用して以下のようにインスタンス化される状況を考えてみましょう。 

Keycloak.getInstance(
                "http://localhost:8080",
                "master",
                "admin",
                "admin",
                "admin-cli",
                null,
                null,
                new MyCustomJacksonProvider()
        );
Copy to Clipboard Toggle word wrap

この場合、クラス MyCustomJacksonProvider がクラス org.keycloak.admin.client.JacksonProvider から拡張されていることを確認するか、上記の方法で ObjectMapper を手動で設定してください。KeycloakBuilder を使用して管理クライアントを作成し、RestEasy クライアントを手動で注入して作成する場合も、同様の注意が必要です。

第14章 Red Hat build of Keycloak 認可クライアント
リンクのコピー

要件によっては、リソースサーバーはリソースをリモートで管理したり、パーミッションをプログラム的にチェックしたりできるはずです。Java を使用している場合は、認可クライアント API を使用して Red Hat build of Keycloak Authorization Services にアクセスできます。

トークンエンドポイント、リソース、パーミッション管理エンドポイントなど、サーバーが提供する異なるエンドポイントにアクセスするリソースサーバーを対象としています。

14.1. Maven 依存関係
リンクのコピー

<dependencies>
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-authz-client</artifactId>
        <version>999.0.0-SNAPSHOT</version>
    </dependency>
</dependencies>
Copy to Clipboard Toggle word wrap

14.2. 設定
リンクのコピー

クライアント設定は、以下のように keycloak.json ファイルで定義されます。 

{
  "realm": "hello-world-authz",
  "auth-server-url" : "http://localhost:8080",
  "resource" : "hello-world-authz-service",
  "credentials": {
    "secret": "secret"
  }
}
Copy to Clipboard Toggle word wrap

  • realm (必須)

    レルムの名前。

  • auth-server-url (必須)

    Red Hat build of Keycloak サーバーのベース URL。他のすべての Red Hat build of Keycloak ページと REST サービスエンドポイントは、ここから派生します。通常の形式は https://host:port です。

  • resource (必須)

    アプリケーションの client-id各アプリケーションには、アプリケーションを識別するために使用される client-id があります。

  • credentials (必須)

    アプリケーションの認証情報を指定します。これは、キーが認証情報タイプで、値は認証情報タイプの値です。詳細は、専用セクション を参照してください。

設定ファイルは通常、クライアントが keycloak.json ファイルを見つけようとするデフォルトの場所であるアプリケーションのクラスパスに置かれます。

14.3. 認可クライアントの作成
リンクのコピー

クラスパスに keycloak.json ファイルがあることを考慮すると、以下のように AuthzClient インスタンスを作成できます。 

// create a new instance based on the configuration defined in a keycloak.json located in your classpath
AuthzClient authzClient = AuthzClient.create();
Copy to Clipboard Toggle word wrap

14.4. ユーザーエンタイトルメントの取得
リンクのコピー

以下に、ユーザーエンタイトルメントの取得方法を示す例を示します。 

// create a new instance based on the configuration defined in keycloak.json
AuthzClient authzClient = AuthzClient.create();

// create an authorization request
AuthorizationRequest request = new AuthorizationRequest();

// send the entitlement request to the server in order to
// obtain an RPT with all permissions granted to the user
AuthorizationResponse response = authzClient.authorization("alice", "alice").authorize(request);
String rpt = response.getToken();

System.out.println("You got an RPT: " + rpt);

// now you can use the RPT to access protected resources on the resource server
Copy to Clipboard Toggle word wrap

1 つ以上のリソースのセットでユーザーエンタイトルメントを取得する方法を示す例を以下に示します。 

// create a new instance based on the configuration defined in keycloak.json
AuthzClient authzClient = AuthzClient.create();

// create an authorization request
AuthorizationRequest request = new AuthorizationRequest();

// add permissions to the request based on the resources and scopes you want to check access
request.addPermission("Default Resource");

// send the entitlement request to the server in order to
// obtain an RPT with permissions for a single resource
AuthorizationResponse response = authzClient.authorization("alice", "alice").authorize(request);
String rpt = response.getToken();

System.out.println("You got an RPT: " + rpt);

// now you can use the RPT to access protected resources on the resource server
Copy to Clipboard Toggle word wrap

14.5. 保護 API を使用したリソースの作成
リンクのコピー

// create a new instance based on the configuration defined in keycloak.json
AuthzClient authzClient = AuthzClient.create();

// create a new resource representation with the information we want
ResourceRepresentation newResource = new ResourceRepresentation();

newResource.setName("New Resource");
newResource.setType("urn:hello-world-authz:resources:example");

newResource.addScope(new ScopeRepresentation("urn:hello-world-authz:scopes:view"));

ProtectedResource resourceClient = authzClient.protection().resource();
ResourceRepresentation existingResource = resourceClient.findByName(newResource.getName());

if (existingResource != null) {
    resourceClient.delete(existingResource.getId());
}

// create the resource on the server
ResourceRepresentation response = resourceClient.create(newResource);
String resourceId = response.getId();

// query the resource using its newly generated id
ResourceRepresentation resource = resourceClient.findById(resourceId);

System.out.println(resource);
Copy to Clipboard Toggle word wrap

14.6. RPT のイントロスペクション
リンクのコピー

// create a new instance based on the configuration defined in keycloak.json
AuthzClient authzClient = AuthzClient.create();

// send the authorization request to the server in order to
// obtain an RPT with all permissions granted to the user
AuthorizationResponse response = authzClient.authorization("alice", "alice").authorize();
String rpt = response.getToken();

// introspect the token
TokenIntrospectionResponse requestingPartyToken = authzClient.protection().introspectRequestingPartyToken(rpt);

System.out.println("Token status is: " + requestingPartyToken.getActive());
System.out.println("Permissions granted by the server: ");

for (Permission granted : requestingPartyToken.getPermissions()) {
    System.out.println(granted);
}
Copy to Clipboard Toggle word wrap

14.7. クライアント認証
リンクのコピー

認可クライアントがバックチャネル要求を送信する必要がある場合、Red Hat build of Keycloak サーバーに対して認証する必要があります。デフォルトでは、クライアント ID およびクライアントシークレット、署名済み JWT によるクライアント認証、またはクライアントシークレットを使用した署名済み JWT によるクライアント認証の 3 つの方法があります。

14.7.1. クライアント ID およびクライアントシークレット
リンクのコピー

これは、OAuth2 仕様で説明されている従来の方法です。クライアントにはシークレットがあり、そのシークレットはクライアントと Red Hat build of Keycloak サーバーの両方に知られている必要があります。Red Hat build of Keycloak 管理コンソールで特定のクライアントのシークレットを生成し、このシークレットをアプリケーション側の keycloak.json ファイルに貼り付けることができます。 

"credentials": {
    "secret": "19666a4f-32dd-4049-b082-684c74115f28"
}
Copy to Clipboard Toggle word wrap

14.7.2. 署名済み JWT によるクライアント認証
リンクのコピー

これは RFC7523 の仕様に基づいています。これは、以下のように動作します。

  • クライアントには、秘密鍵と証明書が必要です。認可クライアントの場合、これは従来の keystore ファイルを通じて利用できます。このファイルは、クライアントアプリケーションのクラスパスまたはファイルシステム上からアクセスできます。
  • 認証中に、クライアントは JWT トークンを生成し、秘密鍵で署名して、client_assertion パラメーターの特定のリクエストで Red Hat build of Keycloak に送信します。

  • Red Hat build of Keycloak には、JWT の署名を検証できるように、クライアントの公開鍵または証明書が必要です。Red Hat build of Keycloak では、クライアントのクライアント認証情報を設定します。まず、管理コンソールの Credentials タブで、クライアントの認証方法として Signed JWT を選択します。次に、Keys タブで次のいずれかの方法を選択できます。

    • Red Hat build of Keycloak がクライアントの公開鍵をダウンロードできる JWKS URL を設定します。このオプションは、クライアントがいつでもキーをローテーションでき、Red Hat build of Keycloak が設定を変更せずに必要に応じて常に新しいキーをダウンロードするため、最も柔軟性があります。つまり、Red Hat build of Keycloak は、未知の kid (Key ID) によって署名されたトークンを検出すると、新しいキーをダウンロードします。ただし、公開鍵を JWKS 形式でどこかに公開し、サーバーで利用できるようにするには注意が必要です。
    • クライアントの公開鍵または証明書を、PEM 形式、JWK 形式、またはキーストアからアップロードします。このオプションを使用すると、公開鍵はハードコーディングされ、クライアントが新しいキーペアを生成する際に変更する必要があります。独自のキーストアが利用できない場合は、Red Hat build of Keycloak の管理コンソールから独自のキーストアを生成することもできます。このオプションは、認可クライアントを使用する場合に最も簡単です。

この方法をセットアップするには、keycloak.json ファイルに次のようなコードを記述する必要があります。 

"credentials": {
  "jwt": {
    "client-keystore-file": "classpath:keystore-client.jks",
    "client-keystore-type": "JKS",
    "client-keystore-password": "storepass",
    "client-key-password": "keypass",
    "client-key-alias": "clientkey",
    "token-expiration": 10
  }
}
Copy to Clipboard Toggle word wrap

この設定では、認可クライアントを使用するアプリケーションのクラスパスでキーストアファイル keystore-client.jks が使用可能である必要があります。接頭辞 classpath: を使用しない場合は、クライアントアプリケーションが実行しているファイルシステム上の任意のファイルを指定できます。

14.7.3. クライアントシークレットを使用した署名済み JWT によるクライアント認証
リンクのコピー

これは、秘密鍵と証明書の代わりにクライアントシークレットを使用することを除いて、署名された JWT を使用したクライアント認証と同じです。

クライアントにはシークレットがあり、これは認可クライアントを使用するアプリケーションと Red Hat build of Keycloak サーバーの両方に知られている必要があります。管理コンソールの Credentials タブでクライアントの認証方法として Signed JWT with Client Secret を選択し、このシークレットをアプリケーション側の keycloak.json ファイルに貼り付けます。 

"credentials": {
  "secret-jwt": {
    "secret": "19666a4f-32dd-4049-b082-684c74115f28",
    "algorithm": "HS512"
  }
}
Copy to Clipboard Toggle word wrap

"algorithm" フィールドは、クライアントシークレットを使用して署名済み JWT のアルゴリズムを指定します。次のいずれかの値である必要があります: HS256、HS384、および HS512。詳細は、JSON Web Algorithms (JWA) を参照してください。

この "algorithm" フィールドはオプションです。keycloak.json ファイルに "algorithm" フィールドが存在しない場合は、HS256 が自動的に適用されます。

14.7.4. 独自のクライアント認証方法を追加する
リンクのコピー

独自のクライアント認証方法を追加することもできます。クライアント側プロバイダーとサーバー側プロバイダーの両方を実装する必要があります。詳細は、サーバー開発者ガイド の 認証 SPI セクションを参照してください。

第15章 Red Hat build of Keycloak ポリシーエンフォーサー
リンクのコピー

Policy Enforcement Point (PEP: Policy Enforcement Point) は、異なる方法で実装できる設計パターンです。Red Hat build of Keycloak は、さまざまなプラットフォーム、環境、およびプログラミング言語に PEP を実装するのに必要な方法をすべて提供します。Red Hat build of Keycloak Authorization Services は RESTful API を提供し、一元化された認可サーバーを使用して詳細な認可に OAuth2 認可機能を活用します。

PEP の概要
View larger image
PEP の概要

PEP は、保護されているリソースに関連付けられたポリシーを評価して、Red Hat build of Keycloak サーバーからアクセス決定を強制します。これは、保護されたリソースへの特定の要求を満たすかどうかをチェックするためにアプリケーションのフィルターやインターセプターとして機能します。この決定によって付与されるパーミッションに基づいて、保護されるリソースへの特定のリクエストを満たすことができるかどうかを確認します。

Red Hat build of Keycloak は、JakartaEE 準拠のフレームワークと Web コンテナーを保護するために、Java アプリケーションに対する Red Hat build of Keycloak ポリシーエンフォーサー を有効にするビルトインサポートを提供します。Maven を使用している場合は、プロジェクトに次の依存関係を設定する必要があります。 

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-policy-enforcer</artifactId>
    <version>999.0.0-SNAPSHOT</version>
</dependency>
Copy to Clipboard Toggle word wrap

ポリシーエンフォーサーを有効にすると、アプリケーションに送信されたリクエストはすべてインターセプトされ、そのリクエストを送信しているアイデンティティーに対して Red Hat build of Keycloak が付与したパーミッションに応じて、保護されたリソースへのアクセスが付与されます。

ポリシーの適用は、アプリケーションのパスと、Red Hat build of Keycloak の管理コンソールを使用してリソースサーバー用に作成した リソース に密接にリンクされています。デフォルトではリソースサーバーを作成すると、ポリシーの適用をすぐに有効にできるように、Red Hat build of Keycloak はリソースサーバーの デフォルト設定 を作成します。

15.1. 設定
リンクのコピー

ポリシーエンフォーサの設定では JSON 形式が使用されます。リソースサーバーから利用可能なリソースに基づいて保護されたパスを自動的に解決する場合、ほとんどの場合は何も設定する必要はありません。

保護するリソースを手動で定義する場合は、もう少し詳細な形式を使用できます。 

{
  "enforcement-mode" : "ENFORCING",
  "paths": [
    {
      "path" : "/users/*",
      "methods" : [
        {
          "method": "GET",
          "scopes" : ["urn:app.com:scopes:view"]
        },
        {
          "method": "POST",
          "scopes" : ["urn:app.com:scopes:create"]
        }
      ]
    }
  ]
}
Copy to Clipboard Toggle word wrap

以下は、各設定オプションの説明です。

  • enforcement-mode

    ポリシーの適用方法を指定します。

    • ENFORCING

      (デフォルトモード) 指定のリソースにポリシーが関連付けられていない場合を含め、リクエストはデフォルトで拒否されます。

    • PERMISSIVE

      指定のリソースにポリシーが関連付けられていない場合を含め、リクエストは許可されます。

    • DISABLED

      ポリシーの評価を完全に無効にし、すべてのリソースにアクセスできるようにします。enforcement-mode が DISABLED の場合、アプリケーションは 認可コンテキスト を介して Red Hat build of Keycloak が付与したすべてのパーミッションを引き続き取得できます。

  • on-deny-redirect-to

    "access denied" メッセージがサーバーから取得される際に、クライアントリクエストがリダイレクトされる URL を定義します。デフォルトでは、アダプターは 403 HTTP ステータスコードで応答します。

  • path-cache

    ポリシーエンフォーサーが、Red Hat build of Keycloak で定義したアプリケーションとリソース間の関連付けを追跡する方法を定義します。このキャッシュは、パスと保護リソース間の関連付けをキャッシュすることで、Red Hat build of Keycloak サーバーへの不要なリクエストを回避するために必要です。

    • 有効期間

      エントリーの期限が切れる時間 (ミリ秒単位) を定義します。指定しないと、デフォルト値は 30000 になります。0 に等しい値を設定して、キャッシュを完全に無効にすることができます。-1 に等しい値を設定して、キャッシュの有効期限を無効にすることができます。

    • max-entries

      キャッシュに保持される必要があるエントリーの制限を定義します。指定しないと、デフォルト値は 1000 になります。

  • paths

    保護するパスを指定します。この設定はオプションです。定義されていない場合、ポリシーエンフォーサーは Red Hat build of Keycloak でアプリケーションに定義したリソースを取得してすべてのパスを検出します。これらのリソースは、アプリケーション内の一部のパスを表す URIS で定義されます。

    • name

      指定のパスに関連付けられるサーバー上のリソースの名前。path と併用される場合、ポリシーエンフォーサーはリソースの URIS プロパティーを無視し、代わりに指定したパスを使用します。

    • path

      (必須) アプリケーションのコンテキストパスに相対する URI。このオプションが指定されていると、ポリシーは、同じ値を持つ URI でリソースについて、サーバーに対してクエリーを実行します。現在、パス照合に非常に基本的なロジックがサポートされています。有効なパスの例は以下のとおりです。

      • ワイルドカード: /*
      • 接尾辞: /*.html
      • サブパス: /path/*
      • パスパラメーター: /resource/{id}
      • 完全一致: /resource
      • パターン: /{version}/resource, /api/{version}/resource, /api/{version}/resource/*

    • methods

      HTTP メソッド (GET、POST、PATCH など) は、サーバーの特定リソースのスコープとどのように関連付けされるかを指定します。

      • method

        HTTP メソッドの名前。

      • scopes

        メソッドに関連付けられたスコープを持つ文字列の配列。スコープを特定のメソッドに関連付ける際に、保護されたリソース (またはパス) へのアクセスを試みるクライアントが、リストで指定されたすべてのスコープにパーミッションを付与する RPT を提供する必要があります。たとえば、スコープ 作成 でメソッド POST を定義する場合、パスへの POST を実行する際に、RPT には create スコープへのアクセスを付与するパーミッションが含まれている必要があります。

      • scopes-enforcement-mode

        メソッドに関連付けられたスコープの強制モードを参照する文字列。値は、ALL または ANY にすることができます。ALL の場合は、このメソッドを使用してリソースにアクセスするために定義されたすべてのスコープが付与される必要があります。ANY の場合は、このメソッドを使用してリソースにアクセスするには、少なくとも 1 つのスコープを付与する必要があります。デフォルトでは、強制モードは ALL に設定されます。

    • enforcement-mode

      ポリシーの適用方法を指定します。

      • ENFORCING

        (デフォルトモード) 指定されたリソースに関連付けられたポリシーがない場合でも、要求はデフォルトで拒否されます。

      • DISABLED

    • claim-information-point

      これらの要求をポリシーで利用可能にするために解決し、Red Hat build of Keycloak サーバーにプッシュする必要のある 1 つ以上の要求のセットを定義します。詳細は、要求情報ポイント を参照してください。

  • lazy-load-paths

    アプリケーションがパスに関連付けられたリソースのサーバーを取得する方法を指定します。true の場合、ポリシーエンフォーサーは要求されるパスに応じてオンデマンドでリソースをフェッチします。この設定は、デプロイメント中にサーバーからすべてのリソースを取得する場合 (paths を指定しなかった場合) や、paths のサブセットのみが定義されていて、他をオンデマンドで取得する場合などに特に便利です。

  • http-method-as-scope

    スコープを HTTP メソッドにマッピングする方法を指定します。true に設定すると、ポリシーエンフォーサーは現在のリクエストから HTTP メソッドを使用して、アクセスを付与すべきかどうかを確認します。有効にした場合、Red Hat build of Keycloak のリソースが保護している各 HTTP メソッドを表すスコープに関連付けられていることを確認してください。

  • claim-information-point

    これらの要求をポリシーで利用可能にするために、解決して Red Hat build of Keycloak サーバーにプッシュする必要がある 1 つ以上の グローバル 要求のセットを定義します。詳細は、要求情報ポイント を参照してください。

15.2. 要求情報ポイント
リンクのコピー

Claim Information Point (CIP) は、ポリシーへのアクセスコンテキストに関する詳細情報を提供するために、要求を解決し、これらの要求を Red Hat build of Keycloak サーバーにプッシュします。policy-enforcer の設定オプションとして定義して、以下のような異なるソースから要求を解決できます。

  • HTTP リクエスト (パラメーター、ヘッダー、ボディーなど)
  • 外部 HTTP サービス
  • 設定で定義された静的値
  • Claim Information Provider SPI を実装するその他のソース

Red Hat build of Keycloak サーバーに要求をプッシュする場合、ポリシーは、ユーザーが誰であるかだけでなく、指定されたトランザクションの who、what、why、when、where、which に基づき、コンテキストとコンテンツを考慮して決定できます。コンテキストベースの認可や、粒度の細かい認可の決定をサポートするためにランタイム情報を使用する方法のみです。

15.2.1. HTTP リクエストからの情報の取得
リンクのコピー

HTTP 要求から要求を抽出する方法を示す例を以下に示します。

keycloak.json

{
  "paths": [
    {
      "path": "/protected/resource",
      "claim-information-point": {
        "claims": {
          "claim-from-request-parameter": "{request.parameter['a']}",
          "claim-from-header": "{request.header['b']}",
          "claim-from-cookie": "{request.cookie['c']}",
          "claim-from-remoteAddr": "{request.remoteAddr}",
          "claim-from-method": "{request.method}",
          "claim-from-uri": "{request.uri}",
          "claim-from-relativePath": "{request.relativePath}",
          "claim-from-secure": "{request.secure}",
          "claim-from-json-body-object": "{request.body['/a/b/c']}",
          "claim-from-json-body-array": "{request.body['/d/1']}",
          "claim-from-body": "{request.body}",
          "claim-from-static-value": "static value",
          "claim-from-multiple-static-value": ["static", "value"],
          "param-replace-multiple-placeholder": "Test {keycloak.access_token['/custom_claim/0']} and {request.parameter['a']}"
        }
      }
    }
  ]
}
Copy to Clipboard Toggle word wrap

15.2.2. 外部 HTTP サービスからの情報の取得
リンクのコピー

以下は、外部 HTTP サービスから要求を抽出する方法を示しています。

keycloak.json

{
  "paths": [
    {
      "path": "/protected/resource",
      "claim-information-point": {
        "http": {
          "claims": {
            "claim-a": "/a",
            "claim-d": "/d",
            "claim-d0": "/d/0",
            "claim-d-all": [
              "/d/0",
              "/d/1"
            ]
          },
          "url": "http://mycompany/claim-provider",
          "method": "POST",
          "headers": {
            "Content-Type": "application/x-www-form-urlencoded",
            "header-b": [
              "header-b-value1",
              "header-b-value2"
            ],
            "Authorization": "Bearer {keycloak.access_token}"
          },
          "parameters": {
            "param-a": [
              "param-a-value1",
              "param-a-value2"
            ],
            "param-subject": "{keycloak.access_token['/sub']}",
            "param-user-name": "{keycloak.access_token['/preferred_username']}",
            "param-other-claims": "{keycloak.access_token['/custom_claim']}"
          }
        }
      }
    }
  ]
}
Copy to Clipboard Toggle word wrap

15.2.3. 静的要求
リンクのコピー

keycloak.json

{
  "paths": [
    {
      "path": "/protected/resource",
      "claim-information-point": {
        "claims": {
          "claim-from-static-value": "static value",
          "claim-from-multiple-static-value": ["static", "value"]
        }
      }
    }
  ]
}
Copy to Clipboard Toggle word wrap

15.2.4. クレーム情報プロバイダー SPI
リンクのコピー

Claim Information Provider SPI は、組み込みプロバイダーが要件に対応するために十分ではない場合に開発者が異なる要求情報ポイントをサポートするために使用できます。

たとえば、新しい CIP プロバイダーを実装するには、org.keycloak.adapters.authorization.ClaimInformationPointProviderFactory および ClaimInformationPointProvider and also provide the file META-INF/services/org.keycloak.adapters.authorization.ClaimInformationPointProviderFactory をアプリケーションのクラスパスに指定する必要があります。

org.keycloak.adapters.authorization.ClaimInformationPointProviderFactory の例: 

public class MyClaimInformationPointProviderFactory implements ClaimInformationPointProviderFactory<MyClaimInformationPointProvider> {

    @Override
    public String getName() {
        return "my-claims";
    }

    @Override
    public void init(PolicyEnforcer policyEnforcer) {

    }

    @Override
    public MyClaimInformationPointProvider create(Map<String, Object> config) {
        return new MyClaimInformationPointProvider(config);
    }
}
Copy to Clipboard Toggle word wrap

すべての CIP プロバイダーは、MyClaimInformationPointProviderFactory.getName メソッドで上記で定義されている名前に関連付ける必要があります。この名前は、policy-enforcer 設定の claim-information-point セクションから実装に設定をマップするために使用されます。

リクエストの処理時に、ポリシーエンフォーサーは MyClaimInformationPointProviderFactory.create メソッドを呼び出して MyClaimInformationPointProvider のインスタンスを取得します。呼び出されると、この特定の CIP プロバイダーに定義されたすべての設定がマップとして渡されます (claim-information-point により)。

ClaimInformationPointProvider の例: 

public class MyClaimInformationPointProvider implements ClaimInformationPointProvider {

    private final Map<String, Object> config;

    public MyClaimInformationPointProvider(Map<String, Object> config) {
        this.config = config;
    }

    @Override
    public Map<String, List<String>> resolve(HttpFacade httpFacade) {
        Map<String, List<String>> claims = new HashMap<>();

        // put whatever claim you want into the map

        return claims;
    }
}
Copy to Clipboard Toggle word wrap

15.3. 認可コンテキストの取得
リンクのコピー

ポリシーの適用が有効になると、サーバーから取得したパーミッションは org.keycloak.AuthorizationContext で利用できます。このクラスは複数のメソッドを提供し、特定のリソースまたはスコープにパーミッションが付与されたかどうかにかかわらず、パーミッションの取得に使用できます。

サーブレットコンテナーでの認可コンテキストの取得 

HttpServletRequest request = // obtain javax.servlet.http.HttpServletRequest
AuthorizationContext authzContext = (AuthorizationContext) request.getAttribute(AuthorizationContext.class.getName());
Copy to Clipboard Toggle word wrap
注記

認可コンテキストを使用すると、サーバーによる決定と返される決定をより細かく制御できます。たとえば、これを使用して、リソースまたはスコープに関連付けられたパーミッションに応じて、項目の表示や表示が動的メニューをビルドできます。 

if (authzContext.hasResourcePermission("Project Resource")) {
    // user can access the Project Resource
}

if (authzContext.hasResourcePermission("Admin Resource")) {
    // user can access administration resources
}

if (authzContext.hasScopePermission("urn:project.com:project:create")) {
    // user can create new projects
}
Copy to Clipboard Toggle word wrap

AuthorizationContext は、Red Hat build of Keycloak Authorization Services の主要機能の 1 つを表します。上記の例では、保護されたリソースがそれらを管理するポリシーに直接関連付けられていないことを確認できます。

ロールベースアクセス制御 (RBAC) を使用する同様のコードについて考えてみましょう。 

if (User.hasRole('user')) {
    // user can access the Project Resource
}

if (User.hasRole('admin')) {
    // user can access administration resources
}

if (User.hasRole('project-manager')) {
    // user can create new projects
}
Copy to Clipboard Toggle word wrap

いずれの例も同じ要件に対応しますが、これらはさまざまな方法で対処します。RBAC では、ロールはリソースのアクセスを 暗黙的 に定義します。Red Hat build of Keycloak では、RBAC、属性ベースのアクセス制御 (ABAC)、またはその他の BAC バリアントを使用している場合でも、リソースに直接焦点をあてる管理可能なコードを作成できます。指定されたリソースまたはスコープのパーミッションの有無は関係ありません。

セキュリティー要件が変更され、プロジェクトマネージャーに加えて、PMO も新しいプロジェクトを作成できるようになりました。

セキュリティー要件が変更されても、Red Hat build of Keycloak を使用している場合は、新しい要件を指すためにアプリケーションコードを変更する必要はありません。アプリケーションがリソースとスコープ識別子に基づいていると、認可サーバーの特定のリソースに関連付けられたパーミッションまたはポリシーの設定のみを変更する必要があります。この場合、プロジェクトリソース やスコープ urn:project.com:project:create に関連付けられたパーミッションおよびポリシーが変更されます。

15.4. AuthorizationContext を使用した認可クライアントインスタンスの取得
リンクのコピー

AuthorizationContext は、アプリケーションに設定された Red Hat build of Keycloak 認可クライアント への参照を取得するためにも使用できます。 

ClientAuthorizationContext clientContext = ClientAuthorizationContext.class.cast(authzContext);
AuthzClient authzClient = clientContext.getClient();
Copy to Clipboard Toggle word wrap

ポリシーエンフォーバーで保護されているリソースサーバーは、認可サーバーによって提供される API にアクセスする必要があります。AuthzClient インスタンスを使用すると、リソースサーバーはサーバーと対話してリソースを作成したり、プログラムで特定のパーミッションを確認したりできます。

15.5. TLS/HTTPS の設定
リンクのコピー

サーバーが HTTPS を使用している場合は、ポリシーエンフォーサが次のように設定されていることを確認してください。 

{
  "truststore": "path_to_your_trust_store",
  "truststore-password": "trust_store_password"
}
Copy to Clipboard Toggle word wrap

上記の設定により、認可クライアントへの TLS/HTTPS が有効になり、HTTPS スキームを使用して Red Hat build of Keycloak サーバーにリモートでアクセスできるようになります。

注記

Red Hat build of Keycloak サーバーのエンドポイントにアクセスするときは、TLS/HTTPS を有効にすることが強く推奨されます。

第16章 Red Hat build of Keycloak クライアントライブラリーのアップグレード
リンクのコピー

クライアントライブラリーは次のアーティファクトです。

  • Java 管理クライアント - Maven アーティファクト org.keycloak:keycloak-admin-client
  • Java 認証クライアント - Maven アーティファクト org.keycloak:keycloak-authz-client
  • Java ポリシーエンフォーサー - Maven アーティファクト org.keycloak:keycloak-policy-enforcer
  • 上記の他のクライアントライブラリーで使用される Java 共通クラス - Maven アーティファクト org.keycloak:keycloak-client-common-synced

クライアントライブラリーは、サポート対象のすべての Red Hat build of Keycloak サーバーバージョンでサポートされています。クライアントライブラリーがより多くのサーバーバージョンでサポートされているため、更新が容易になり、アプリケーションのクライアントライブラリーを更新するときにサーバーを同時に更新する必要がなくなる場合があります。

クライアントライブラリーは、Red Hat build of Keycloak サーバーの古いリリースでも動作する可能性がありますが、保証されておらず、公式にはサポートされていません。

どのエンドポイントとパラメーターが Red Hat build of Keycloak サーバーバージョンでサポートされているかを確認するには、Java admin-client などのクライアントライブラリーの javadoc を参照する必要がある場合があります。管理クライアントについては、追加の注意事項として、Red Hat build of Keycloak 管理クライアント の章の「Red Hat build of Keycloak サーバーとの互換性」を参照してください。

法律上の通知
リンクのコピー

Copyright © 2025 Red Hat, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions and limitations under the License.
トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

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

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

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

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

会社概要

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

Theme

© 2025 Red Hat