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

アップグレードガイド

Red Hat build of Keycloak 22.0

Red Hat Customer Content Services

概要

これは、以前のバージョンの Red Hat build of Keycloak 22.0 からアプリケーションをアップグレードするためのガイドです。

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

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、用語の置き換えは、今後の複数のリリースにわたって段階的に実施されます。詳細は、Red Hat CTO である Chris Wright のメッセージ をご覧ください。

第1章 Red Hat build of Keycloak のアップグレード
リンクのコピー

Red Hat build of Keycloak は Keycloak プロジェクトをベースとしており、OpenID Connect、OAuth 2.0、SAML 2.0 などの一般的な標準仕様に基づいて Web SSO 機能を提供することで、Web アプリケーションのセキュリティーを保護します。Red Hat build of Keycloak サーバーは OpenID Connect または SAML ベースの ID プロバイダー (IdP) として機能し、エンタープライズユーザーディレクトリーまたはサードパーティー IdP が標準仕様ベースのセキュリティートークンを使用してアプリケーションを保護できるようにします。

このガイドは、Red Hat ビルドの Keycloak のマイナーバージョンであるバージョン 22.0.13 に適用されます。Red Hat build of Keycloak をバージョン 22.0.13 にアップグレードするには、以下の手順を以下の順序で使用します。

  1. Red Hat build of Keycloak サーバーをアップグレードします。
  2. Red Hat build of Keycloak アダプターをアップグレードします。

第2章 Red Hat build of Keycloak サーバーのアップグレード
リンクのコピー

2.1. アップグレードの準備
リンクのコピー

手順

  1. 設定やテーマなどの古いインストールをバックアップします。

  2. お使いのリレーショナルデータベースのドキュメントの説明に従い、データベースをバックアップします。

    アップグレード後は、データベースは古いサーバーと互換性がありません。アップグレードを元に戻す必要がある場合は、まず古いインストールを復元してから、バックアップコピーからデータベースを復元します。

  3. 開かれたトランザクションをすべて処理し、data/tx-object-store/ トランザクションディレクトリーを削除します。
注記

Red Hat build of Keycloak のマイナーアップグレードでは、すべてのユーザーセッションが失われます。アップグレード後に、すべてのユーザーは再度ログインする必要があります。

2.2. サーバー ZIP ファイルのダウンロード
リンクのコピー

手順

  1. Red Hat build of Keycloak を Red Hat の Web サイト からダウンロードして展開します。
  2. ZIP ファイルを目的の場所に移動します。

  3. アーカイブを展開します。

    このファイルを解凍すると、rhbk-22.0.13 という名前のディレクトリーがなければなりません。

  4. conf/、providers/、themes/ を以前のインストールから新規インストールにコピーします。

2.3. データベースの移行
リンクのコピー

Red Hat build of Keycloak では、データベーススキーマを自動的に移行することも、手動で移行することもできます。デフォルトでは、新規インストールを初めて起動すると、データベースが自動的に移行されます。

2.3.1. リレーショナルデータベースの自動移行
リンクのコピー

自動移行を実行するには、目的のデータベースに接続されているサーバーを起動します。新しいバージョンのサーバーのデータベーススキーマが変更された場合は、データベースが移行されます。

数百万ものレコードを含むサイズの大きなテーブルにインデックスを作成する場合、非常に時間がかかり、大幅なサービスの中断を引き起こす可能性があります。したがって、インデックスに許可されるレコード数を制限するためのしきい値が存在します。警告メッセージは、後で手動で適用できる SQL コマンドとともにサーバーログに表示されます。

しきい値を変更するには、デフォルトの connections-liquibase プロバイダーの値である index-creation-threshold プロパティーを設定します。 

kc.[sh|bat] start --spi-connections-liquibase-default-index-creation-threshold=300000
Copy to Clipboard Toggle word wrap

2.3.2. 手動によるリレーショナルデータベース移行
リンクのコピー

データベーススキーマを手動でアップグレードするには、デフォルトの connections-jpa プロバイダーの migration-strategy プロパティー値を "manual" に設定します。 

kc.[sh|bat] start --spi-connections-jpa-legacy-migration-strategy=manual
Copy to Clipboard Toggle word wrap

この設定でサーバーを起動すると、サーバーはデータベースを移行する必要があるか確認します。必要な変更は bin/keycloak-database-update.sql SQL ファイルに書き込まれます。このファイルを確認してデータベースに対して手動で実行できます。

エクスポートされた SQL ファイルのパスと名前を変更する場合は、デフォルトの connections-jpa プロバイダーの migration-export プロパティーを設定します。 

kc.[sh|bat] start --spi-connections-jpa-legacy-migration-export=<path>/<file.sql>
Copy to Clipboard Toggle word wrap

このファイルをデータベースに適用する方法の詳細は、リレーショナルデータベースのドキュメントを参照してください。変更がファイルに書き込まれると、サーバーは終了します。

第3章 Red Hat build of Keycloak アダプターのアップグレード
リンクのコピー

まず Red Hat build of Keycloak サーバーをアップグレードしてから、アダプターをアップグレードすることが重要です。以前のバージョンのアダプターは新しいバージョンの Red Hat build of Keycloak サーバーで動作する可能性がありますが、以前のバージョンの Red Hat build of Keycloak サーバーは新しいバージョンのアダプターでは動作しない可能性があります。

3.1. 古いアダプターとの互換性
リンクのコピー

前述したとおり、Red Hat は、前のリリースバージョンのアダプターで動作する新しいリリースバージョンの Red Hat build of Keycloak をサポートするよう努めています。ただし、場合によっては、古いバージョンのアダプターとの互換性が損なわれる可能性のある修正を Red Hat build of Keycloak サーバー側に追加で加える必要があります。たとえば、OpenID Connect 仕様の新しいアスペクトを実装する場合に、古いクライアントアダプターバージョンは認識されませんでした。

このような場合は、互換性モードが追加されました。OpenId Connect クライアントでは、クライアント詳細が含まれるページに、Red Hat build of Keycloak 管理コンソールの OpenID Connect Compatibility Modes という名前のセクションがあります。このセクションで、古いクライアントアダプターとの互換性を維持するために、Red Hat build of Keycloak サーバーの新しい機能を無効にすることができます。詳細については、個々のスイッチのツールチップを参照してください。

3.2. EAP アダプターのアップグレード
リンクのコピー

Web アプリケーションにコピーされた EAP アダプターをアップグレードするには、次の手順を実行します。

手順

  1. 新しいアダプターアーカイブをダウンロードします。
  2. EAP_HOME/modules/system/add-ons/keycloak/ ディレクトリーを削除して、以前のアダプターモジュールを削除します。
  3. ダウンロードしたアーカイブを EAP_HOME に展開します。

3.3. JavaScript アダプターのアップグレード
リンクのコピー

Web アプリケーションにコピーされた JavaScript アダプターをアップグレードするには、以下の手順を実行します。

手順

  1. 新しいアダプターアーカイブをダウンロードします。
  2. アプリケーションの keycloak.js ファイルは、ダウンロードしたアーカイブの keycloak.js ファイルを上書きします。

3.4. Node.js アダプターのアップグレード
リンクのコピー

Web アプリケーションにコピーされた Node.js アダプターをアップグレードするには、以下の手順を実行します。

手順

  1. 新しいアダプターアーカイブをダウンロードします。
  2. 既存の Node.js アダプターディレクトリーを削除します。
  3. 更新されたファイルをその場所に展開します。
  4. アプリケーションの package.json で keycloak-connect の依存関係を変更します。

法律上の通知
リンクのコピー

Copyright © 2024 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