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

2.9. Keycloak JS

このリリースには、考慮すべき Keycloak JS ライブラリーへのいくつかの変更が含まれています。これらの変更の主な誘因は、ライブラリーを Red Hat build of Keycloak サーバーから切り離し、独立してリファクタリングできるようにして、コードを簡素化し、今後のメンテナンスを容易にすることです。変更内容は以下のとおりです。

2.9.1. ライブラリーはサーバーから静的に提供されなくなる
リンクのコピー

Keycloak JS ライブラリーは、Red Hat build of Keycloak サーバーから静的に提供されなくなりました。つまり、次の URL は利用できなくなります。

  • /js/keycloak-authz.js
  • /js/keycloak-authz.min.js
  • /js/keycloak.js
  • /js/keycloak.min.js
  • /js/{version}/keycloak-authz.js
  • /js/{version}/keycloak-authz.min.js
  • /js/{version}/keycloak.js
  • /js/{version}/keycloak.min.js

さらに、これらの URL のライブラリーにリンクされていた keycloakJsUrl プロパティーは、管理コンソールのテーマから削除されました。カスタムテーマでこのプロパティーを使用してライブラリーを組み込んでいた場合は、別の方法を使用してライブラリーを組み込むようにテーマを更新する必要があります。

ここで、NPM などのパッケージマネージャーを使用して、ライブラリーをプロジェクトに含める必要があります。このライブラリーは、NPM レジストリーで keycloak-js として入手できます。これは、以下のコマンドを使用してインストールできます。 

npm install keycloak-js
Copy to Clipboard Toggle word wrap

または、サーバーのディストリビューションには、keycloak-js-26.0.0.tgz アーカイブ内のライブラリーのコピーが含まれています。そこからライブラリーをプロジェクトにコピーできます。ビルドせずにブラウザーで直接ライブラリーを使用している場合は、自分でライブラリーをホストする必要があります。将来的にライブラリーの更新が容易になるため、プロジェクトにライブラリーを含めるにはパッケージマネージャーを使用することを推奨します。

2.9.2. Keycloak インスタンスの設定が必要になる
リンクのコピー

以前は、設定を渡さずに Keycloak インスタンスを構築することができました。続いてその設定は、含まれている keycloak.js スクリプトのパスに基づき、サーバーから keycloak.json ファイルとして自動的にロードされます。ライブラリーがサーバーから静的に提供されなくなったため、この機能は削除されました。Keycloak インスタンスを構築するときに、設定を明示的に渡す必要があります。 

// Before
const keycloak = new Keycloak();

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

// Alternatively, you can pass a URL to a `keycloak.json` file.
// Note this is not reccomended as it creates additional network requests, and is prone to change in the future.
const keycloak = new Keycloak('http://keycloak-server/path/to/keycloak.json');
Copy to Clipboard Toggle word wrap

2.9.3. ログインメソッドが async となる
リンクのコピー

Keycloak JS は、Web Crypto API を使用して、PKCE をサポートするために必要な SHA-256 ダイジェストを計算するようになりました。この API の非同期性により、次のパブリックメソッドは常に Promise を返すようになりました。

  • login()
  • createLoginUrl()
  • createRegisterUrl()

これらのメソッドを await とするようにコードを更新してください。 

// Before
keycloak.login();
const loginUrl = keycloak.createLoginUrl();
const registerUrl = keycloak.createRegisterUrl();

// After
await keycloak.login();
const loginUrl = await keycloak.createLoginUrl();
const registerUrl = await keycloak.createRegisterUrl();
Copy to Clipboard Toggle word wrap

これらのメソッドを await とするようにコードを更新してください。

2.9.4. ビルド時におけるオプションの起動動作の厳密化
リンクのコピー

提供されたビルド時のオプションが、前回の最適化された Red Hat build of Keycloak のビルド時にサーバーイメージに保存された値と異なる場合、Red Hat build of Keycloak は起動に失敗するようになりました。以前は、このような場合には警告メッセージが表示されていました。

2.9.5. 新しいデフォルトのクライアントスコープ basic
リンクのコピー

basic という名前の新しいクライアントスコープが、レルムの "デフォルト" クライアントスコープとして追加され、新しく作成されたすべてのクライアントに追加されます。移行中に、クライアントスコープも既存のすべてのクライアントに自動的に追加されます。

このスコープには、次のクレームに対して事前設定されたプロトコルマッパーが含まれています。

  • sub (詳細は下記専用セクションを参照)
  • auth_time

これにより、軽量アクセストークン内のクレームの数を減らすための追加の支援が提供されるだけでなく、常に自動的に追加されるクレームを設定する機会も提供されます。

2.9.5.1. プロトコルマッパーを介して sub クレームがアクセストークンに追加される
リンクのコピー

アクセストークンに常に追加されていた sub クレームは、新しい Subject (sub) プロトコルマッパーを使用して、デフォルトで追加されるようになりました。

Subject (sub) マッパーは、basic クライアントスコープでデフォルトで設定されます。したがって、このバージョンにアップグレードした後は追加の設定は必要ありません。

Pairwise subject identifier マッパーを使用してアクセストークンの sub クレームをマップしている場合は、Subject (sub) マッパーを無効にするか削除することを検討できますが、Subject (sub) プロトコルマッパーは Pairwise subject identifier マッパーの前に実行され、pairwise 値が Subject (sub) マッパーによって追加された値をオーバーライドするため、厳密には必要ありません。これは、Subject (sub) マッパーが現在最初のプロトコルマッパーとして実行されているため、sub クレームをオーバーライドする他のカスタムプロトコルマッパー実装にも適用される場合があります。

Subject (sub) マッパーを使用して、アクセストークン、軽量アクセストークン、およびイントロスペクション応答に対してのみ サブ クレームを設定できます。IDToken と Userinfo には常に sub クレームが含まれます。

ユーザーセッションが存在せず、sub クレームが常にアクセストークンに追加されるため、マッパーはサービスアカウントには影響しません。

2.9.5.2. nonce クレームは ID トークンにのみ追加される
リンクのコピー

nonce クレームは、OpenID Connect Core 1.0 仕様に厳密に従って ID トークンにのみ追加されるようになりました。仕様に示されているように、同じパラメーターが認可リクエストで送信された場合、ID トークン 内でクレームが必須になります。仕様では、リフレッシュ要求 後に nonce を追加しないことも推奨されています。以前は、クレームはすべての応答 (更新を含む) のすべてのトークン (Access、Refresh、ID) に設定されていました。

ソフトウェアには、クライアントスコープに割り当てて古い動作に戻すことができる、新しい Nonce backwards compatible マッパーも含まれています。たとえば、JS アダプターは、バージョン 24.0.0 で問題 #26651 を修正する前に、すべてのトークンで返された nonce クレームをチェックしました。したがって、古いバージョンの JS アダプターを使用する場合は、クライアントスコープを使用して、必要なクライアントにマッパーを追加する必要があります。

2.9.5.3. 古い JavaScript アダプターの使用
リンクのコピー

アプリケーションで最新の Red Hat build of Keycloak サーバーを古いバージョンの JavaScript アダプターとともに使用する場合、以前のバージョンの JavaScript アダプターは、Red Hat build of Keycloak によって追加されたが OIDC 仕様ではサポートされていないクレームに依存しているため、上記のトークンの変更の影響を受ける可能性があります。ここでは、以下の点を説明します。

  • Red Hat build of Keycloak Javascript アダプター 24.0.3 以前を使用する場合に Session State (session_state) マッパーを追加する
  • Red Hat build of Keycloak 24 より古い Red Hat build of Keycloak Javascript アダプターを使用する場合に、Nonce backwards compatible マッパーを追加する

プロトコルマッパーを対応するクライアントまたは一部のクライアントスコープに直接追加できます。これは、Red Hat build of Keycloak Javascript アダプターの古いバージョンに依存するクライアントアプリケーションで使用できます。詳細は、session_state および nonce クレームに関する前のセクションを参照してください。

トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

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

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

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

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

会社概要

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

Theme

© 2025 Red Hat