はじめに

このガイドでは、Keycloakをアップグレードする方法について説明します。最初にKeycloakサーバーを、次にKeycloakアダプターをアップグレードすることが推奨されます。

アップグレードする前に、手順をよく読み移行に伴う変更に示された変更を十分に確認してください。

Keycloakサーバーのアップグレード

アップグレードする準備

アップグレードする前に、踏まなければならない手順がありますので、その順序に気をつけてください。また、アップグレードする過程で起こり得る問題についても注意してください。通常は、まずKeycloakサーバーをアップグレードしてから、アダプターをアップグレードする必要があります。

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

  1. アップグレードする前に、開いているトランザクションを処理し、data/tx-object-store/トランザクション・ディレクトリーを削除します。

  2. 古いインストール(設定、テーマなど)をバックアップします。

  3. データベースをバックアップします。データベースのバックアップの仕方についての詳細は、使用しているデータベースの関連ドキュメントを参照してください。

  4. Keycloakサーバーのアップグレード

    • プロダクション環境でインストールの問題に直面しないように、まずは非プロダクション環境でアップグレードのテストをすることがベスト・プラクティスです。

    • アップグレード後、データベースは古いKeycloakサーバーとの互換性がなくなることに注意してください。

    • プロダクション環境でアダプターをアップグレードする前に、アップグレードしたKeycloakサーバーが機能していることを確認してください。

  5. アップグレードを元に戻す必要がある場合は、まず古いインストールを復元してから、バックアップのコピーからデータベースを復元します。

  6. アダプターをアップグレードします。

Keycloakサーバーのアップグレード

このセクションで説明する手順は、デフォルトのアップグレード手順であり、コンフィギュレーションガイドで求められた手動変更によっては、常に可能とは限りません。

アップグレードするバージョンの詳細については、移行に伴う変更を参照してください。

アダプターをアップグレードする前に、Keycloakサーバーをアップグレードすることが重要です。

Keycloakサーバーをアップグレードするには、以下の手順に沿って行います。

  1. アップグレードする前に、開いているトランザクションを処理し、data/tx-object-store/トランザクション・ディレクトリーを削除します。

  2. 新しいサーバー・アーカイブをダウンロードします。

  3. ダウンロードしたアーカイブを移したい場所に移動させます。

  4. アーカイブを展開します。この手順により、最新のKeycloakのリリースのクリーンなインスタンスがインストールされます。

  5. スタンドアローン・モードの場合は、以前のインストール・ディレクトリーのKEYCLOAK_HOME/standalone/を新しいインストール・ディレクトリーにコピーします。

    ドメインモードの場合は、以前のインストール・ディレクトリーのKEYCLOAK_HOME/domain/を新しいインストール・ディレクトリーにコピーします。

    ドメインモードの場合は、空のKEYCLOAK_HOME/domain/deploymentsディレクトリーを作成します。

    注意:binディレクトリー内のファイルを、以前のバージョンのファイルで上書してはいけません。変更は手作業で行う必要があります。

  6. modulesディレクトリーに追加されたカスタム・モジュールをコピーします。

  7. 以下の該当するアップグレード・スクリプトを実行します。

スタンドアローン・モード・アップグレード・スクリプトの実行

スタンドアローン・モード用のアップグレード・スクリプトを実行するには、以下の手順に従います。

  1. デフォルトとは異なる設定ファイルを使用している場合は、移行スクリプトを編集してそのファイル名に変更します。

  2. サーバーを停止します。

  3. アップグレード・スクリプトを実行します。

    bin/jboss-cli.sh --file=bin/migrate-standalone.cli

スタンドアローン-高可用性モードのアップグレード・スクリプトの実行

スタンドアローン-高可用性(HA)モードでは、インスタンスはすべて同時にアップグレードされる必要があります。

スタンドアローン-HAモードのアップグレード・スクリプトを実行するには、以下の手順に沿って行います。

  1. デフォルトとは異なる設定ファイルを使用している場合は、移行スクリプトを編集してそのファイル名に変更します。

  2. サーバーを停止します。

  3. アップグレード・スクリプトを実行します。

    bin/jboss-cli.sh --file=bin/migrate-standalone-ha.cli

ドメインモードのアップグレード・スクリプトの実行

ドメインモードでは、インスタンスはすべて同時にアップグレードされる必要があります。

ドメインモードでアップグレード・スクリプトを実行するには、以下の手順に沿って行います。

  1. プロファイル名を変更した場合、アップグレード・スクリプトを編集し、スクリプトの先頭付近の変数を変更する必要があります。

  2. keycloak-server.jsonファイルの場所を含むようにドメイン・スクリプトを編集します。

  3. サーバーを停止します。

  4. アップグレード・スクリプトをドメイン・コントローラー上でのみ実行します。

    bin/jboss-cli.sh --file=bin/migrate-domain.cli

データベースの移行

Keycloakでは、データベース・スキーマの移行は自動的にできますが、手動でも行うことができます。デフォルトでは、新規インストールディレクトリーでの初回起動時に自動的にデータベースが移行されます。

自動リレーショナル・データベース移行

データベース・スキーマの自動アップグレードを有効にするには、デフォルトのconnectionsJpaプロバイダーのmigrationStrategyプロパティー値を"update"に設定します。

 <spi name="connectionsJpa">
    <provider name="default" enabled="true">
        <properties>
            ...
            <property name="migrationStrategy" value="update"/>
        </properties>
    </provider>
</spi>

または、このCLIコマンドを実行します。

/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=update)

データベース・スキーマが新バージョンに変更されていた場合、この設定でサーバーを起動すると、データベースは自動的に移行されます。

数百万のレコードを含む巨大なテーブルにインデックスを作成すると、簡単に膨大な時間がかかり、アップグレード時にサービスが大幅に中断する可能性があります。そのような場合のために、自動インデックス作成のしきい値(レコード数)を追加しました。デフォルトでは、このしきい値は 300000 レコードです。レコード数がしきい値を超えると、インデックスは自動的に作成されず、後で手動で適用できるSQLコマンドを含む警告メッセージがサーバーログに表示されます。

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

<spi name="connectionsLiquibase">
    <provider name="default" enabled="true">
        <properties>
            <property name="indexCreationThreshold" value="300000"/>
        </properties>
    </provider>
</spi>

または、このCLIコマンドを実行します。

/subsystem=keycloak-server/spi=connectionsLiquibase/:add(default-provider=default)
/subsystem=keycloak-server/spi=connectionsLiquibase/provider=default/:add(properties={indexCreationThreshold => "300000"},enabled=true)

手動リレーショナル・データベース移行

データベース・スキーマの手動アップグレードを有効にするには、デフォルトのconnectionsJpaプロバイダーのmigrationStrategyプロパティー値を"manual"に設定します。

 <spi name="connectionsJpa">
    <provider name="default" enabled="true">
        <properties>
            ...
            <property name="migrationStrategy" value="manual"/>
        </properties>
    </provider>
</spi>

または、このCLIコマンドを実行します。

/subsystem=keycloak-server/spi=connectionsJpa/provider=default/:map-put(name=properties,key=migrationStrategy,value=manual)

この設定でサーバーを起動すると、データベースを移行する必要があるかどうか確認されます。必要な変更はSQLファイルに書き込まれ、確認およびデータベースに対する手動実行が可能です。このファイルをデータベースに適用する方法についての詳細は、利用しているリレーショナル・データベース用のドキュメントを参照してください。ファイルに変更が書き込まれると、サーバーは終了します。

テーマの移行

カスタム・テーマを作成した場合、それらを新しいサーバーに移行する必要があります。組み込みのテーマの変更については、カスタマイズした項目に応じて、カスタム・テーマに反映させる必要があります。

古いサーバーの"themes"ディレクトリーから、新しいサーバーの"themes"ディレクトリーにカスタム・テーマをコピーする必要があります。その後、以下の変更を確認し、その変更をカスタム・テーマに適用させる必要があるかどうか検討しなければなりません。

要約すると、以下のとおりになります。

  • テンプレートをカスタマイズした場合、基本テーマのテンプレートと比較して、適用する必要のある変更があるかどうかを確認しなければなりません。

  • スタイルをカスタマイズし、Keycloakテーマを拡張している場合、そのスタイルへの変更を確認する必要があります。基本テーマを拡張している場合は、この手順をスキップすることができます。

  • メッセージをカスタマイズした場合、キーまたは値を変更するか、メッセージを追加する必要があります。

テンプレートの移行

テンプレートをカスタマイズした場合、テンプレートに加えられた変更をしっかり確認し、カスタマイズしたテンプレートにそれらの変更を適用する必要があるかどうか判断しなければなりません。ほとんどの場合、カスタマイズしたテンプレートに同じ変更を適用する必要があります。テンプレートをカスタマイズしていなかった場合は、このセクションをスキップすることができます。

diffツールを使用してテンプレートを比較し、カスタマイズしたテンプレートにどんな変更を加えるか確認することがベスト・プラクティスになります。マイナーチェンジしただけの場合、更新されたテンプレートとカスタマイズしたテンプレートを比較する方が簡単です。ただし、変更をたくさん加えた場合は、新しいテンプレートとカスタマイズした古いテンプレートを比較する方が、必要な変更が表示されるため簡単です。

下記のスクリーンショットは、ログイン・テーマのinfo.ftlテンプレートとサンプルのカスタム・テーマを比較しています。

更新版のログイン・テーマのテンプレートとサンプルのカスタム・ログイン・テーマのテンプレートの比較

theme migration meld info 1

この比較によって、1つ目の変更("Hello world!!")はカスタマイズで、2つ目の変更("if pageRedirectUri")は基本テーマの変更であるということが簡単に分かります。2つ目の変更をカスタム・テンプレートにコピーすると、カスタマイズしたテンプレートは正常に更新されます。

もう1つ代替の方法になりますが、下記のスクリーンショットは、古いインストールのinfo.ftlテンプレートと新しいインストールの更新版のinfo.ftlテンプレートを比較しています。

古いインストール・ディレクトリーのログイン・テーマ・テンプレートと更新されたバージョンのログイン・テーマ・テンプレートの比較

theme migration meld info 2

この比較によって、基本テンプレートにどんな変更が加えられたのか簡単に分かります。次に、変更したテンプレートに同じ変更を手動で加える必要があります。このアプローチは最初のほど簡単ではないため、最初のアプローチが実現不可能な場合にのみ、このアプローチを使用します。

メッセージの移行

別の言語のサポートを追加した場合、上記にリストした変更をすべて適用する必要があります。別の言語のサポートを追加していない場合は、何も変更する必要はありません。つまり、テーマが影響を受けるメッセージを変更した場合のみ、変更を加える必要があります。

追加した値については、基本テーマのメッセージの値を確認して、そのメッセージをカスタマイズする必要があるかどうかを判断します。

名前を変更したキーについては、カスタム・テーマのキーの名前も変更します。

変更した値については、基本テーマの値をチェックし、カスタム・テーマを変更する必要があるかどうか判断します。

スタイルの移行

keycloakまたはrh-ssoテーマからスタイルを引き継ぐ場合、カスタム・スタイルを更新し、組み込みテーマのスタイルに加えられた変更を反映させる必要があります。

diffツールを使用して、古いサーバー・インストールと新しいサーバー・インストールのスタイルシートの変更を比較することがベスト・プラクティスになります。

サンプルとして、下記のとおりdiffコマンドを使用します。

$ diff KEYCLOAK_HOME_OLD/themes/keycloak/login/resources/css/login.css \
KEYCLOAK_HOME_NEW/themes/keycloak/login/resources/css/login.css

変更を確認し、カスタム・スタイルに影響するかどうか判断します。

Keycloakアダプターのアップグレード

まずKeycloakサーバーをアップグレードし、次にアダプターをアップグレードすることが重要です。以前のバージョンのアダプターは、それ以降のバージョンのKeycloakサーバーで動作しますが、以前のバージョンのKeycloakサーバーは、それ以降のバージョンのアダプターでは動作しません。

古いアダプターとの互換性

前述したとおり、新しいリリース・バージョンのKeycloakサーバーは、古いバージョンのアダプターとともに動作するようにサポートしています。ただし、Keycloakサーバー側に修正を含める必要があり、古いバージョンのアダプターとの互換性が損なわれることがあります。たとえば、OpenID Connectの新しい仕様を実装しても、古いバージョンのクライアント・アダプターはそれを認識できません。

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

EAPアダプターのアップグレード

WildFlyアダプターをアップグレードするには、以下の手順に沿って行います。

  1. 新しいアダプター・アーカイブをダウンロードします。

  2. WILDFLY_HOME/modules/system/add-ons/keycloak/ ディレクトリーを削除することで、以前のアダプター・モジュールを削除します。

  3. ダウンロードしたアーカイブをWILDFLY_HOMEに解凍します。

JavaScriptアダプターのアップグレード

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

  1. 新しいアダプター・アーカイブをダウンロードします。

  2. ダウンロードしたアーカイブ内にあるkeycloak.jsファイルで、アプリケーションのkeycloak.jsファイルを上書きします。

Node.jsアダプターのアップグレード

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

  1. 新しいアダプター・アーカイブをダウンロードします。

  2. 既存のNode.jsアダプター・ディレクトリーを削除します。

  3. 更新されたファイルをその場所に解凍します。

  4. アプリケーションのpackage.json内のkeycloak-connectの依存関係を変更します。

Keycloak Admin Clientのアップグレード

まずKeycloakサーバーをアップグレードし、次にadmin-clientをアップグレードすることが重要です。以前のバージョンのadmin-clientは、それ以降のバージョンのKeycloakサーバーで動作しますが、以前のバージョンのKeycloakサーバーは、それ以降のバージョンのadmin-clientでは動作しません。使用されているKeycloakサーバーのバージョンと一致するバージョンのadmin-clientを使用することをお勧めします。

移行に伴う変更

16.0.0への移行

WildFly 25 アップグレード

WildFly 25では、TLSを設定するために使用されていたレガシー・セキュリティーサブシステムが非推奨となりました。変更点が多いため、これまでのような移行スクリプトを提供することはできません。

以前のバージョンのKeycloakから設定ファイルをコピーするのではなく、Keycloak 16で提供されるデフォルトの設定ファイルから始めて、関連する変更を適用することをお勧めします。

Keycloakサブシステムの設定は、直接コピーすることができます。

Elytronサブシステムの詳細については、https://docs.wildfly.org/25/WildFly_Elytron_Security.html[WildFly documentation] を参照してください。

このようなご不便をおかけして本当に申し訳なく思っています。また、皆様がKeycloak 16にアップグレードすることが著しく困難になることを理解していますが、代替手段を見つけることができませんでした。

特筆すべきは、Quarkusディストリビューションへの切り替えで、Keycloak 17で完全にサポートされる予定ですが、これによりKeycloakの設定とアップグレードが大幅に容易になる予定です。

WildFly 25の詳細については、 WildFly 25 リリースノート を参照してください。

プロキシー環境変数

Keycloakは、HTTPリクエストの送信時に標準の HTTP_PROXYHTTPS_PROXYNO_PROXY 環境変数を尊重するようになりました。この変更により、たとえば HTTP_PROXY 変数が定義されていて、SPIの設定に明示的なプロキシー・マッピングが指定されていない場合、予期せぬプロキシー・サーバーの使用が発生する可能性があります。Keycloak がこれらの環境変数を使用しないようにするには、すべてのリクエストに対して .*;NO_PROXY として明示的にノー・プロキシー・ルートを作成することができます。

詳しくは Server Installation and Configuration Guideの関連する章 を参照してください。

Keycloak Operatorで非推奨の機能

本リリースでは、Keycloak Operatorの機能の一部を非推奨とし、サポート対象外としました。これは、Backup CRDとオペレーター管理のPostgres Databaseに関するものです。詳細については、 Server Installation and Configuration Guideの関連する章を参照してください。

サポートされていないのMetrics Extensionを含むKeycloak Operatorの例

以前は、Keycloak OperatorによるKeycloak CRの作成例で、サポートされていないMetrics Extensionが追加されていました。これは削除されました。

14.0.0への移行

クライアント・ポリシーの移行

クライアント・ポリシー機能は、Keycloak 12以降のプレビュー機能であり、適切なサポートがありませんでした。この機能を試して、Keycloak 12やKeycloak 13でいくつかのクライアント・ポリシーやクライアント・プロファイルを設定した場合、新バージョンで再度クライアント・ポリシーやクライアント・プロファイルを設定する必要があります。あくまでもプレビューのため、設定の形式が大きく変わったため、Keycloak 12やKeycloak 13で作成したクライアント・ポリシーやクライアント・プロファイルの自動移行は行っておりません。

13.0.0への移行

必要な手動での移行の手順

standalone.xml にSmallRyeモジュールへの参照が含まれている場合は、手動で変更する必要があります。SmallRyeモジュールはベースであるWildFlyディストリビューションから削除されているため、設定がそれらを参照している場合、サーバーは起動しません。したがって、 standalone.xml の設定がこれらのモジュールを参照している場合、設定に変更が加えられる前に、 migrate-standalone.cli を介したサーバー設定の移行が失敗します。このような場合、サーバー設定の移行を実行するには、SmallRyeモジュールを参照するすべての行を手動で削除する必要があります。デフォルトの設定では、具体的に次の行を削除する必要があります。

<extension module="org.wildfly.extension.microprofile.config-smallrye"/>
<extension module="org.wildfly.extension.microprofile.health-smallrye"/>
<extension module="org.wildfly.extension.microprofile.metrics-smallrye"/>
<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0"/>
<subsystem xmlns="urn:wildfly:microprofile-health-smallrye:2.0" security-enabled="false" empty-liveness-checks-status="${env.MP_HEALTH_EMPTY_LIVENESS_CHECKS_STATUS:UP}" empty-readiness-checks-status="${env.MP_HEALTH_EMPTY_READINESS_CHECKS_STATUS:UP}"/>
<subsystem xmlns="urn:wildfly:microprofile-metrics-smallrye:2.0" security-enabled="false" exposed-subsystems="*" prefix="${wildfly.metrics.prefix:wildfly}"/>

WildFly 23へのアップグレード

Keycloakサーバーは、基盤となるコンテナーとしてWildfly23を使用するようにアップグレードされました。これには、特定のKeycloakサーバーの機能が直接関係するわけではありませんが、移行に関連する次の変更に注意してください。

依存関係の更新

依存関係が、WildFly 23サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在 11.0.9.Final です。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。ただし、独自の設定変更を行った場合に必要となる可能性がある最も重要な変更は次のとおりです。

  • Infinispanキャッシュコンテナーの module 属性は deprecated (未使用)となり、 modules 属性に 置き換わり 、このキャッシュ・コンテナーの設定に関連付けられたモジュールのセットを表します。さらに、ベースになるコンテナーとしてWildfly 23を使用したことにより、さまざまな要素の属性に追加の変更が加えられました。たとえば、 managed-executor-service 要素と managed-scheduled-executor-service 要素は、新しい hung-task-termination-period 属性を認識するようになりました。詳細については、 the Wildfly 23 full model reference を参照してください。

WildFly 22へのアップグレード

Keycloakサーバーは、基盤となるコンテナーとしてWildfly22を使用するようにアップグレードされました。これには、特定のKeycloakサーバーの機能が直接関係するわけではありませんが、移行に関連する次の変更に注意してください。

依存関係の更新

依存関係が、WildFly 22サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在 11.0.8.Final です。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。ただし、独自の設定変更を行った場合に必要となる可能性がある最も重要な変更は次のとおりです。

12.0.2への移行

読み取り専用属性

読み取り専用ユーザー属性のサポートが追加されました。これには、REST API またはKeycloakユーザー・インターフェイスを使用してユーザーを更新するときに、ユーザーまたは管理者が編集することを想定していないユーザー属性が含まれます。以下を使用する場合は特に重要です。

  • カスタム・ユーザー・ストレージ・プロバイダー

  • カスタム・オーセンティケーター

  • ユーザー属性に基づいて認可を確立するカスタムJavaScript認可ポリシー

  • X.509証明書をユーザーIDにマッピングするためのカスタム属性を持つX.509オーセンティケーター

  • その他のカスタム機能(単純なユーザー・プロファイル情報ではなく、認証/認可/アイデンティティーのコンテキストを保持するためのメタデータとして、一部のユーザー属性が使用される個所)。

See the details in the Threat model mitigation chapter

Valid Request URIs

OpenID Connectのパラメーター request_uri を使用する場合、クライアントに Valid Request URIs を設定する必要があるという要件が存在します。これは、クライアントの詳細ページの管理コンソール、または管理REST APIまたはクライアント登録APIを介して設定できます。Valid Request URIsには、特定のクライアントに許可されているリクエストURI値のリストが含まれている必要があります。これは、SSRF攻撃を回避するためです。 Valid Redirect URIs オプションと同様に、ワイルドカードまたは相対パスを使用する可能性がありますが、セキュリティー上の理由から、通常はできるだけ具体的な値を使用することをお勧めします。

13.0.0への移行

WildFly 22へのアップグレード

Keycloakサーバーは、基盤となるコンテナーとしてWildfly 22を使用するようにアップグレードされました。これは、特定のKeycloakサーバーの機能に直接関わるものではありませんが、移行に関連するいくつかの変更点があり、言及する価値があります。

依存関係の更新

依存関係はWildfly 22サーバーで使用されるバージョンに更新されました。たとえば、Infinispanは現在 11.0.8.Final です。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。たとえば、自分で設定を変更したため、より詳細な情報が必要な場合を考慮して、最も重要な変更の一覧を以下に示します。

12.0.0への移行

WildFly 21へのアップグレード

Keycloakサーバーは、基盤となるコンテナーとしてWildfly 21を使用するようにアップグレードされました。これには、特定のKeycloakサーバーの機能が直接関係するわけではありませんが、移行に関連する次の変更に注意してください。

依存関係の更新

依存関係が、WildFly 21サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在 11.0.4.Final です。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。ただし、独自の設定変更を行った場合に必要となる可能性がある最も重要な変更は次のとおりです。

  • Infinispanキャッシュの object-memory 要素は 非推奨 (未使用)になり、 heap-memory 要素に置き換えられました。

Dockerプロトコル認証用のユーザー・セッションの作成をスキップします

Dockerプロトコルによる認証が成功した後、ユーザー・セッションは作成されません。詳細については、 Server Administration Guide を参照してください。

PatternFly 4へのアップグレード

Keycloakログイン・テーマ・コンポーネントがPatternFly 4にアップグレードされました。古いPatternFly 3も新しいものと同時に実行されるため、PF3コンポーネントを保持することができます。ただし、ログインテーマのデザインにいくつかの変更が加えられました。カスタム・ログイン・テーマをアップグレードしてください。必要な変更を加えた例が keycloak/examples/themes/theme/sunrise ディレクトリーにあります。追加の設定は必要ありません。

デフォルトではクライアント・クレデンシャル・グラントでリフレッシュトークンを発行しない

このKeycloakバージョンから、OAuth2クライアント・クレデンシャル・グラント・エンドポイントはデフォルトでリフレッシュトークンを発行しません。この動作は、OAuth2仕様に準拠しています。この変更の副作用として、クライアント・クレデンシャルの認証が成功した後、Keycloakサーバー側でユーザー・セッションが作成されないため、パフォーマンスとメモリー消費が改善されます。クライアント・クレデンシャル・グラントを使用するクライアントは、リフレッシュトークンの使用を停止し、代わりに、グラントタイプとして refresh_token を使用する代わりに、常に grant_type=client_credentials ですべてのリクエストを認証することをお勧めします。これに関連して、KeycloakはOAuth2 Revocationエンドポイントでのアクセストークンの取り消しをサポートしているため、クライアントは必要に応じて個々のアクセストークンを取り消すことができます。

下位互換性のために、古いバージョンの動作のままにする可能性があります。これを使用すると、クライアント・クレデンシャル・グラントによる認証が成功した後もリフレッシュトークンが発行され、ユーザーセッションも作成されます。これは、Keycloak管理コンソールの特定のクライアントで有効にできます。クライアントの詳細の OpenID Connect Compatibility Modes のセクションにある Use Refresh Tokens For Client Credentials Grant のスイッチを使用します。

11.0.0への移行

WildFly 20へのアップグレード

Keycloakサーバーは、基盤となるコンテナーとしてWildfly 20を使用するようにアップグレードされました。これには、特定のKeycloakサーバーの機能が直接関係するわけではありませんが、移行に関連する次の変更に注意してください。

依存関係の更新

依存関係が、WildFly 20サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在 10.1.8.Final です。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

  • Infinispanのキャッシュを設定する際には、remote-store要素に追加された protocolVersion プロパティーを使用することをお勧めします。Infinispanサーバー 9.4.18に接続する場合、KeycloakサーバーとInfinispanサーバーではInfinispanライブラリーのバージョンが異なりますので、hotrodプロトコルの推奨バージョンは2.9となります。詳しくは、Cross-Datacenterのドキュメントを参照してください。

  • サブシステム connectionsInfinispan の下にある remoteStoreSecurityEnabled プロパティーを使用することをお勧めします。詳細については、Cross-Datacenterのドキュメントを参照してください。

LDAPインポートしないバグの修正

以前のバージョンのKeycloakでは、 Import Users がオフのLDAPプロバイダーが設定されている場合、非LDAPマップ属性の一部が変更されていてもユーザーを更新することが可能でした。この状況は、混乱を与える動作となっていました(属性が更新されているように見えても、更新されなかった)。現在のバージョンでは、LDAP以外のマップされた属性が変更された場合、更新はまったく実行できません。

これはほとんどのデプロイメントに影響を与えることはありませんが、まれな状況で影響を受ける可能性があります。たとえば、以前に管理REST APIを使用してユーザーを更新しようとしたときに、ユーザーが誤った属性を変更しても、更新が可能でした。現在のバージョンでは、更新は不可能であり、理由がすぐに通知されます。

UserModelの変更

UserModel のフィールドである usernameemailfirstName および lastName は、次のバージョンでより洗練されたユーザー・プロファイルをKeycloakに追加する準備として、カスタム属性に移行されます。データベースにその正確な名前のカスタム属性を持つユーザーが含まれている場合、アップグレードする前にカスタム属性を移行する必要があります。この移行は自動的には行われません。そうしないと、データベースから読み込まれなくなり、削除される可能性があります。この状況は、 usernameUserModel.getFirstAttribute(UserModel.USERNAME) を介してアクセスおよび設定できることを意味します。他の分野にも同様の影響があります。 UserModel を直接または間接的にサブクラス化するSPIの実装者は、 setUsernamesetSingleAttribute(UserModel.USERNAME, …​) (および他のフィールドについても同様)の間の動作が一貫していることを確認する必要があります。ポリシーの評価機能のユーザーは、評価で属性の数を使用する場合、すべてのユーザーがデフォルトで4つの新しい属性を持つようになるため、ポリシーを適合させる必要があります。

UserModel のパブリックAPIは変更されていません。ユーザーデータにアクセスするフロントエンド・リソースまたはSPIを変更する必要はありません。データベースもまだ変更されていません。

Instagram IdPが新しいAPIに移行

古いレガシーAPIが 廃止 されたため、Instagram IdPは新しいAPIを使用するようになりました。これには、新しいAPIクレデンシャルを取得する必要があります。詳しくは、 Server Administration Guide を参照してください。

Instagram IdPを使用する既存のユーザー、特にそれが唯一の認証オプションであるユーザーには、特別な注意が必要です。そのようなユーザーは、2020年9月30日までにInstagram IdPを使用してKeycloakにログインする必要があります。その日を過ぎると、ログインに別の認証方法(パスワードなど)を使用してInstagramソーシャルリンクを手動で更新するか、Keycloakに新しいアカウントを作成する必要があります 。これは、InstagramのユーザーIDが古いAPIと新しいAPIの間で互換性がないためですが、新しいAPIは移行を許可するために一時的に新しいユーザーIDと古いユーザーIDの両方を返します。Keycloakは、ユーザーがログインすると、IDを自動的に移行します。

非標準のトークン・イントロスペクション・エンドポイントが削除されました

以前のバージョンでは、Keycloakは2つのイントロスペクション・エンドポイント( token_introspection_endpointintrospection_endpoint )を公開していました。後者は、 RFC-8414 で定義されているものです。前者は非推奨でしたが、現在は削除されています。

9.0.1への移行

JavaScriptアダプターのレガシーPromise

JavaScriptアダプターでpromiseTypeを設定する必要がなくなり、両方を同時に使用できるようになりました。レガシーAPI( successerror )はいつか削除されるため、できるだけ早くネイティブPromise API( thencatch )を使用するようにアプリケーションを更新することをお勧めします。

重複する最上位グループ

バージョン9.0.1では、レルムに重複した最上位グループが作成される可能性がある問題が修正されています。それでも、以前に重複したグループが存在すると、アップグレード・プロセスが失敗します。KeycloakサーバーがH2、MariaDB、MySQLまたはPostgreSQL Databaseを使用している場合、この問題の影響を受ける可能性があります。アップグレードを開始する前に、サーバーに重複した最上位グループが含まれているかどうかを確認してください。たとえば、次のSQLクエリーをデータベース・レベルで実行して、それらを一覧表示できます。

SELECT REALM_ID, NAME, COUNT(*) FROM KEYCLOAK_GROUP WHERE PARENT_GROUP is NULL GROUP BY REALM_ID, NAME HAVING COUNT(*) > 1;

各レルムに同じ名前で存在できる最上位グループは1つだけです。アップグレードの前に、重複を確認して削除する必要があります。アップグレードのエラーには、 Change Set META-INF/jpa-changelog-9.0.1.xml::9.0.1- KEYCLOAK-12579-add-not-null-constraint::keycloak failed. というメッセージが含まれます。

9.0.0への移行

ユーザーロケールの処理の改善

ログインページのロケールが選択される方法、およびユーザーのロケールが更新されるタイミングに多くの改良が加えられました。

詳細については、 Server Administration Guide を参照してください。

トークン表現Javaクラスの非推奨メソッド

2038年には、 int は1970年以降の秒の値を保持できなくなります。そのため、これらを long 値に更新する作業を行っています。さらに、トークン表現には int 値の処理に関連する別の問題が存在します。 int はデフォルトのJSON表現で 0 になりますが、それを含めるべきではありません。

非推奨となった正確なメソッドと置換メソッドの詳細については、JavaDocを参照してください。

8.0.2への移行

より多くの認証フローの変更

REQUIREDとALTERNATIVEの実行は同じフローではサポートされません

以前のバージョンでは、同じレベルの同じ認証フロー内にREQUIREDとALTERNATIVEのエグゼキューションを設定することが可能でした。このアプローチにはいくつかの問題があり、認証SPIでリファクタリングを行いました。つまり、これはもはや有効とは見なされません。ALTERNATIVEとREQUIREDのエグゼキューションが同じレベルで設定されている場合、ALTERNATIVEのエグゼキューションは無効と見なされます。そのため、最新バージョンに移行すると、既存の認証フローは自動的に移行され、前のバージョンと同じ動作が維持されます。一部のREQUIREDのエグゼキューションと同じレベルのALTERNATIVEのエグゼキューションが含まれている場合、ALTERNATIVEのエグゼキューションは別のREQUIREDサブフローに追加されます。これにより、前のバージョンと同様に、特定の認証フローの動作が同じまたは同様になります。認証フローの設定を再確認してテストし、すべてが期待どおりに機能することを再確認することを常にお勧めします。この推奨事項は、カスタム・オーセンティケーターの実装を使用してさらにカスタマイズされた認証フローがある場合に特に当てはまります。

8.0.0への移行

新しいデフォルト・ホスト名プロバイダー

古いリクエストと固定ホスト名プロバイダーは、新しいデフォルトのホスト名プロバイダーに置き換えられました。リクエストおよび固定ホスト名プロバイダーは廃止されました。できるだけ早くデフォルトのホスト名プロバイダーに切り替えることをお勧めします。

WildFly 18へのアップグレード

Keycloakサーバーは、基盤となるコンテナーとしてWildfly 18を使用するようにアップグレードされました。これには、特定のKeycloakサーバーの機能が直接関係するわけではありませんが、移行に関連する次の変更に注意してください。

依存関係の更新

依存関係が、WildFly 18サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在9.4.16.Finalです。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

サーバーへのスクリプトのデプロイ

これまで、管理者はKeycloak管理コンソールとRESTful Admin APIを使用して、サーバーにスクリプトをアップロードできました。

現時点では、この機能はデフォルトで 無効 であり、ユーザーはスクリプトをサーバーに直接デプロイすることを選択する必要があります。詳細については、JavaScript Providersを参照してください。

JavaScriptアダプターのクライアント・クレデンシャル

以前のリリースでは、開発者はクライアントのクレデンシャルをJavaScriptアダプターに提供できました。現時点では、この機能は 削除 されました。これは、クライアントサイドのアプリがシークレットを保持する上で安全ではないためです。

認証フローの変更

認証フローに関連するリファクタリングと改善をいくつか行いました。これにより、移行の際に注意が必要です。

OPTIONALのエグゼキューションのRequirementが削除されました

移行に関して最も重要な変更は、認証のエグゼキューションからOPTIONALの要件のサポートを削除し、それをCONDITIONALの要件に置き換えることです。これにより、柔軟性が高まります。前のバージョンで構成された既存のOPTIONALのオーセンティケーターは、CONDITIONALのサブフローに置き換えられます。これらのサブフローには、最初のエグゼキューションとして設定された Condition - User Configured 条件があり、2回目のエグゼキューションとして以前のOPTIONALオーセンティケーター(たとえば、 OTP Form )が設定されます。ユーザーの観点からは、認証中の動作は以前のバージョンと同じです。

Java SPIの変更

Java Authentication SPIおよびCredential Provider SPIにはいくつかの変更があります。インターフェース Authenticator は変更されませんが、新しいクレデンシャル・タイプ( CredentialModel のサブクラス)を導入するより高度なオーセンティケーターを開発している場合は影響を受ける可能性があります。 CredentialProvider インターフェイスに変更があり、 CredentialValidator のようないくつかの新しいインターフェイスが導入されています。また、オーセンティケーターがOPTIONALのエグゼキューションのRequirementをサポートしている場合、影響を受ける可能性があります。詳細については、サーバー開発ガイドの最新の認証の例を再確認することをお勧めします。

Freemarkerテンプレートの変更

Freemarkerテンプレートにもいくつかの変更があります。ログインフォームまたは一部のアカウント・フォーム、特にOTPに関連するフォームのカスタムFreemarkerテンプレートを使用した独自のテーマがある場合、影響を受ける可能性があります。最新のKeycloakのFreemarkerテンプレートの変更を再確認し、それに応じてテンプレートを調整することをお勧めします。

ユーザー・クレデンシャルの変更

ユーザー・クレデンシャルの保存に関する柔軟性を追加しました。とりわけ、すべてのユーザーは同じタイプの複数のクレデンシャル、たとえば複数のOTPクレデンシャルを持つことができます。その結果、データベーススキーマにいくつかの変更が加えられました。ただし、以前のバージョンのクレデンシャルは新しい形式に自動的に更新され、ユーザーは以前のバージョンで設定されたパスワードまたはOTPクレデンシャルを使用してログインできます。

7.0.0への移行

WildFly 17へのアップグレード

Keycloakサーバーは、基盤となるコンテナーとしてWildfly 17を使用するようにアップグレードされました。これには、特定のKeycloakサーバーの機能が直接関係するわけではありませんが、移行に関連する次の変更に注意してください。

依存関係の更新

依存関係が、WildFly 17サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在9.4.14.Finalです。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

6.0.0への移行

WildFly 16へのアップグレード

Keycloakサーバーは、基盤となるコンテナーとしてWildfly 16を使用するようにアップグレードされました。これには、特定のKeycloakサーバーの機能が直接関係するわけではありませんが、移行に関連する次の変更に注意してください。

依存関係の更新

依存関係が、WildFly 16サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在9.4.8.Finalです。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

新しいオプションのクライアント・スコープ

MicroProfile/JWT Auth Specification で定義されているリクエストを処理するために、新しいオプションの microprofile-jwt クライアント・スコープを追加しました。この新しいクライアント・スコープは、認証されたユーザーのユーザー名を upn クレームに、レルムロールを groups クレームに設定するためのプロトコル・マッパーを定義します。

prompt=noneをデフォルトのIDPに伝播する機能

転送されてきた prompt=none クエリー・パラメーターを含むリクエストを処理できるIDPを識別するために、 Accepts prompt=none forward from client という名前の新しいスイッチをOIDCアイデンティティー・プロバイダーの設定に追加しました。

これまでは、ユーザーがレルムで認証されていない場合、 prompt=none で認証リクエストを受け取ると、レルムはユーザーがIDPによって認証されているかどうかを確認せずに login_required エラーを返していました。これからは、( kc_idp_hint クエリー・パラメーターを使用するか、レルムのデフォルトIDPを設定することにより、)認証リクエストに対してデフォルトのIDPが決定できる場合と、IDPに対して Accepts prompt=none forward from client スイッチが有効になっている場合、認証リクエストはIDPに転送され、ユーザーがそこで認証されているかどうかを確認します。

このスイッチは、デフォルトのIDPが指定されている場合にのみ考慮されることに注意することが重要です。この場合、ユーザーにIDPの選択を求めることなく、どこに認証リクエストを転送するかがわかります。デフォルトのIDPを決定できない場合、認証リクエストを実行するためにどのIDPが使用されるかを推測できないため、リクエストの転送は実行されません。

5.0.0への移行

WildFly 15へのアップグレード

Keycloakサーバーは、基盤となるコンテナーとしてWildfly 15を使用するようにアップグレードされました。これには、特定のKeycloakサーバーの機能が直接関係するわけではありませんが、移行に関連する次の変更に注意してください。

依存関係の更新

依存関係が、WildFly 15サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在9.4.3.Finalです。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

4.8.2への移行

Google Identity ProviderはGoogle Sign-in認証システムを使用するように更新されました

バージョン4.8.1までのKeycloakでのGoogle Identity Providerの実装では、認可とユーザー・プロファイルの取得がGoogle+ APIエンドポイントに依存しています。2019年3月以降、Googleは新しいGoogle Sign-in認証システムを支持してGoogle+ APIのサポートを削除します。Keycloakアイデンティティー・プロバイダーは新しいエンドポイントを使用するように更新されたため、この統合を使用している場合は、必ずKeycloakバージョン4.8.2以降にアップグレードしてください。

アプリケーション識別子がディレクトリーに見つからないというエラーが発生した場合は、新しいアプリケーションIDとシークレットを取得するために、 Google API Console ポータルにクライアン・トアプリケーションを再度登録する必要があります。

Google+ユーザー情報エンドポイントによって提供され、Google Sign-in APIによって別の名前で提供されている非標準のクレームについては、カスタムマッパーを調整する必要があるかもしれません。利用可能なクレームに関する最新情報については、Googleのドキュメントを参照してください。

LinkedIn Social BrokerがLinkedIn APIのバージョン2に更新されました

したがってLinkedInでは、すべての開発者が自分のAPIのバージョン2.0とOAuth 2.0に移行する必要があります。そのため、LinkedIn Social Brokerを更新しました。

このブローカーを使用している既存のデプロイメントでは、LinkedIn APIのバージョン2を使用してユーザーのプロファイルを取得する際にエラーが発生する可能性があります。このエラーは、ブローカの設定に使用されるクライアント・アプリケーションに付与されたアクセス権が不足しており、認証プロセス中にProfile APIへのアクセスや特定のOAuth2スコープの要求を許可されていない可能性があります。

新しく作成されたLinkedInクライアント・アプリケーションの場合でも、少なくともクライアント・アプリケーションが https://api.linkedin.com/v2/me エンドポイントから現在のメンバーのプロファイルを取得できるように、クライアントが r_liteprofiler_emailaddress のOAuth2スコープを要求できることを確認する必要があります。

メンバーの情報へのアクセスと現在のメンバーのProfile APIによって返される限定されたクレーム・セットに関して、LinkedInによって課されたプライバシー制限のために、LinkedIn Social Brokerは現在デフォルトのユーザー名としてメンバーのメールアドレスを使用しています。つまり、認証中に認可リクエストを送信する際には常に r_emailaddress が設定されます。

4.6.0への移行

新しいデフォルト・クライアント・スコープ

新しいレルムのデフォルトのクライアント・スコープ roleweb-origins を追加しました。これらのクライアント・スコープには、ユーザーのロールを追加するプロトコル・マッパーとトークンに許可されたWeb起点が含まれています。移行中に、これらのクライアント・スコープはデフォルトのクライアント・スコープとしてすべてのOpenID Connectクライアントに自動的に追加されます。したがって、データベースの移行が完了した後でセットアップを行う必要はありません。

Protocol Mapper SPIの追加

これに関連して、(サポートされていない)Protocol Mappers SPIにはわずかな追加があります。カスタムのProtocolMapperを実装した場合にのみ影響を受ける可能性があります。ProtocolMapperインターフェイスに新しい getPriority() メソッドが導入されました。このメソッドは、デフォルトの実装が0を返すように設定しています。プロトコル・マッパーの実装がアクセストークンの realmAccess または resourceAccess プロパティーにあるロールに依存している場合は、マッパーの優先度を高くする必要があります。

オーディエンスの解決

認証されたユーザーが少なくとも一つのクライアントロールを持つすべてのクライアントのオーディエンスは、現在アクセストークンの aud クレームに自動的に追加されます。一方、アクセストークンは、それが発行されたフロントエンド・クライアントのAudienceを自動的に含まない場合があります。詳しくは Server Administration Guide を参照してください。

JavaScriptアダプターのPromise

JavaScriptアダプターでネイティブのJavaScriptのPromiseを使用するには、initオプションで promiseTypenative に設定する必要があります。

以前は、ネイティブのPromiseが利用可能であった場合、レガシーのKeycloakのPromiseとネイティブのPromiseの両方を提供するラッパーが返されました。これにより、ネイティブのエラーイベントの前にエラーハンドラーが常に設定されていないために問題が発生していました。

Microsoft Identity ProviderはMicrosoft Graph APIを使用するように更新されました

バージョン4.5.0までのKeycloakでのMicrosoft Identity Providerの実装では、認可とユーザー・プロファイルの取得がLive SDKエンドポイントに依存しています。2018年11月以降、Microsoftは新しいMicrosoft Graph APIを支持してLive SDK APIのサポートを削除します。Keycloakアイデンティティー・プロバイダーは新しいエンドポイントを使用するように更新されたため、この統合を使用している場合は、必ずKeycloakバージョン4.6.0以降にアップグレードしてください。

"Live SDK applications"で登録された従来のクライアント・アプリケーションは、アプリケーションのID形式が変更されたため、Microsoft Graphエンドポイントでは機能しません。アプリケーション識別子がディレクトリーに見つからないというエラーが発生した場合は、新しいアプリケーションIDを取得するために Microsoft Application Registration ポータルにクライアント・アプリケーションを再度登録する必要があります。

WildFly 14へのアップグレード

Keycloakサーバーは、基盤となるコンテナーとしてWildfly 14を使用するようにアップグレードされました。これには、特定のKeycloakサーバーの機能が直接関係するわけではありませんが、移行に関連する次の変更に注意してください。

依存関係の更新

依存関係が、WildFly 14サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在9.3.1.Finalです。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

4.4.0への移行

WildFly 13へのアップグレード

Keycloakサーバーは、基盤となるコンテナーとしてWildfly 13を使用するようにアップグレードされました。これには、特定のKeycloakサーバーの機能が直接関係するわけではありませんが、移行に関連する次の変更に注意してください。

依存関係の更新

依存関係が、WildFly 13サーバーによって使用されるバージョンに更新されました。たとえば、Infinispanは現在9.2.4.Finalで、Undertowは2.0.9.Finalです。

設定の変更

standalone(-ha).xmldomain.xml にはいくつかの設定変更があります。設定ファイルの自動移行を処理するには、Keycloakサーバーのアップグレードセクションに従ってください。ただし、独自の設定変更を行った場合に必要となる可能性がある最も重要な変更は次のとおりです。

  • infinispanキャッシュ上の eviction 要素は 廃止 され(未使用)、 object-memory 要素に置き換えられました。

  • Infinispanサブシステムの cache-container 要素は jndi-attribute認識しなくなりました

クロス・データセンター・レプリケーションの変更
  • Infinispanサーバーをバージョン9.4.19にアップグレードする必要があります。旧バージョンでも動作する可能性はありますが、テストがされていないため、保証はできません。

  • Infinispanサーバー設定ファイルでセキュリティーを設定する必要はありません。

  • transaction 要素は、Infinispanサーバーのレプリケーションされたキャッシュの設定から削除する必要があります。これは、infinispanバグ https://issues.redhat.com/browse/ISPN-9323 の対策のために必要です。

4.3.0への移行

ホスト名の設定

以前のバージョンでは、フィルターを使用して許可されたホスト名を指定することが推奨されていました。有効なホスト名が使用されていることを確認しやすくするため、固定ホスト名を設定することができ、内部アプリケーションが内部IPアドレスなどの代替URLを通じてKeycloakを呼び出すことも可能になりました。本番環境では、このアプローチに切り替えることをお勧めします。

4.0.0への移行

クライアント・テンプレートがクライアント・スコープに変更されました

クライアント・スコープのサポートを追加しました。これは移行の際に注意が必要です。

クライアント・テンプレートがクライアント・スコープに変更されました

クライアント・テンプレートがクライアント・スコープに変更されました。クライアント・テンプレートがあれば、そのプロトコル・マッパーとロールスコープのマッピングは保持されます。

名前の中の空白文字の置き換え

名前に空白文字を含むクライアント・テンプレートの名前は、スペースをアンダースコアに置き換えた名前に変更されました。これは、クライアント・スコープの名前に空白文字が使用できないためです。たとえば、クライアント・テンプレート my template はクライアントスコープ my_template に変更されます。

クライアントへのクライアント・スコープのリンク

クライアント・テンプレートを持つクライアントの場合、対応するクライアント・スコープがクライアントに Default Client Scope として追加されます。したがって、プロトコル・マッパーとロール・スコープ・マッピングはクライアント上に保持されます。

既存のクライアントにリンクされていないレルム・デフォルト・クライアント・スコープ

移行中に、ビルトインのクライアント・スコープのリストが各レルムに追加されます。また、 Realm Default Client Scopes のリストも追加されます。ただし、既存のクライアントはアップグレードされず、新しいクライアント・スコープは自動的に追加されません。また、すべてのプロトコル・マッパーとロール・スコープ・マッピングは、既存のクライアントに保持されます。新しいバージョンでは、新しいクライアントを作成すると、Realm Default Client Scopesが自動的に付属され、プロトコル・マッパーは付属されません。移行中に既存のクライアントを変更することはありません。たとえば、クライアントのプロトコル・マッパーなどのカスタマイズを適切に検出することが不可能なためです。既存のクライアントを更新する場合(それらからプロトコル・マッパーを削除してクライアント・スコープとリンクする場合)、手動で行う必要があります。

同意を再度確認する必要があります

クライアント・スコープの変更は、同意のリファクタリングを必要としました。同意はクライアント・スコープを指し、ロールやプロトコル・マッパーは指しません。この変更により、ユーザーが以前に確認した永続的な同意はもはや有効ではなく、ユーザーは移行後に同意ページを再度確認する必要があります。

一部の設定スイッチが削除されました

Scope Param Required がRole Detailから削除されました。 Consent RequiredConsent Text のスイッチがプロトコル・マッパーの詳細から削除されました。これらのスイッチはクライアント・スコープ機能に置き換えられました。

認可サービスの変更

UMA 2.0のサポートを追加しました。このバージョンのUMA仕様では、サーバーからのパーミッションの取得方法に関する重要な変更が導入されました。

ここでは、UMA 2.0サポートによって導入された主な変更点を示します。詳細は、 Authorization Services Guide を参照してください。

Authorization APIが削除されました

UMA 2.0以前(UMA 1.0)では、クライアント・アプリケーションがAuthorization APIを使用して、RPTの形式でサーバーからパーミッションを取得していました。新しいバージョンのUMA仕様では、Authorization APIが削除され、Keycloakからも削除されました。UMA 2.0では、特定の認可タイプを使用してトークン・エンドポイントからRPTを取得できるようになりました。詳細は、 Authorization Services Guide を参照してください。

Entitlement APIが削除されました

UMA 2.0の導入により、KeycloakからRPTを取得し、異なるAPIを使用することを避けるように、トークン・エンドポイントとUMAグラントタイプを活用することにしました。Entitlement APIによって提供される機能はこれまでどおり、リソースまたはスコープが提供されていない場合でも、1つ以上のリソースとスコープのセット、またはサーバーからのすべてのパーミッションを取得できます。詳細は、 Authorization Services Guide を参照してください。

UMA Discoveryエンドポイントの変更

UMA Discoveryドキュメントが変更されました。詳細は Authorization Services Guide を参照してください。

Keycloak認可JavaScriptアダプターの変更

以前と同じ動作を維持しながら、UMA 2.0によって導入された変更に準拠するように、Keycloak認可JavaScriptアダプター(keycloak-authz.js)が変更されました。主な変更点は、認可リクエストを表す特定のオブジェクト・タイプを想定する authorization メソッドと entitlement メソッドの両方を呼び出す方法です。この新しいオブジェクト・タイプは、UMAグラントタイプでサポートされているさまざまなパラメーターをサポートすることにより、サーバからパーミッションを取得するより柔軟な方法を提供します。詳細は、 Authorization Services Guide を参照してください。

このリリースで導入された主な変更の1つは、(UMAを使用しない場合)リソースサーバーによって保護されたリソースにアクセスするために、アクセストークンをRPTと交換する必要がなくなったことです。ポリシー・エンフォーサーがリソースサーバー側でどのように設定されているかに応じて、通常のアクセストークンをベアラートークンとして送信するだけで、パーミッションは引き続き適用されます。
Keycloak認可クライアントJava APIの変更

新しいバージョンのKeycloak認可クライアントJava APIにアップグレードすると、いくつかのRepresentationクラスが org.keycloak:keycloak-core の別のパッケージに移動されたことに気付くでしょう。

3.4.2への移行

OpenID Connect認証レスポンスにsession_stateパラメーターを追加

OpenID Connectセッション管理仕様では、パラメーター session_state がOpenID Connect認証レスポンスに存在する必要があります。

過去のリリースでは、このパラメーターはありませんでしたが、Keycloakには、仕様で要求されているように、デフォルトでこのパラメーターを追加しました。

ただし、一部のOpenID Connect / OAuth2アダプター(特に以前のKeycloakアダプター)では、この新しいパラメーターに問題がある可能性があります。

たとえば、クライアント・アプリケーションへの認証が成功すると、ブラウザーのURLには常にパラメーターが表示されます。このような場合、認証レスポンスに session_state パラメーターを追加することを無効にすると便利です。これは、Keycloak管理コンソールの特定のクライアントで行うことができます(クライアントの詳細については、 古いアダプターとの互換性OpenID Connect Compatibility Modes のセクションで説明しています)。 session_state パラメーターを認証レスポンスに追加しないようにすることができる専用の Exclude Session State From Authentication Response スイッチがあります。

パラメーター session_state が3.4.2で追加されましたが、 Exclude Session State From Authentication Response スイッチは4.0.0.Beta1に追加されました。Keycloakサーバーが3.4.2または3.4.3で、 session_state パラメーターに問題がある場合は、サーバーを4.0.0.Beta1以上にアップグレードする必要があります。

3.2.0への移行

新しいパスワード・ハッシュ・アルゴリズム

2つの新しいパスワード・ハッシュ・アルゴリズム(pbkdf2-sha256とpbkdf2-sha512)を追加しました。新しいレルムでは、27500ハッシュ・イテレーションでpbkdf2-sha256ハッシュ・アルゴリズムが使用されます。pbkdf2-sha256はpbkdf2よりは多少速いため、そのイテレーションは20000から27500に増加されました。

既存のレルムは、パスワードポリシーにハッシュ・アルゴリズム(未指定)とイテレーション(20000)のデフォルト値が含まれている場合、アップグレードされます。ハッシュ・イテレーションを変更しており、セキュリティー上より安全なハッシュ・アルゴリズムを使用したい場合は、手動でpbkdf2-sha256に変更する必要があります。

IDトークンにはscope=openidが必要

OpenID Connectの仕様では、初回の認可リクエストにおいて、 openid の値を持つパラメーターである scope を使用する必要があります。そのため、Keycloak 2.1.0では、KeycloakへのURIへリダイレクトする際に scope=openid を使用するように、アダプターを変更しました。また、サーバー部分も変更され、 scope=openid が実際に使用される場合にのみ、IDトークンがアプリケーションに送信されます。 scope=openid が使用されない場合は、IDトークンはスキップされ、アクセストークンとリフレッシュトークンだけがアプリケーションに送信されます。これにより、目的に応じて(たとえば、容量やパフォーマンスなどの目的で)、IDトークンの生成を省略することもできます。

ダイレクト・グラント(OAuth2リソース・オーナー・パスワード・クレデンシャル・グラント)とサービス・アカウント・ログイン(OAuth2クライアント・クレデンシャル・グラント)でも、IDトークンはデフォルトで使用されません。IDトークンを含めるには、敢えて scope=openid パラメーターを追加する必要があります。

認証セッションとアクション・トークン

現在、Keycloakに対してマルチ・データセンターのサポートが実装されています。最初のステップとして、認証セッションとアクション・トークンを導入しました。認証セッションは、以前のバージョンで使用されていたクライアント・セッションを入れ替えたものになります。アクション・トークンは、現在、特殊なシナリオで使用されていますが、このシナリオにおいてはauthenticatorまたはrequiredActionProviderによってユーザーにEメールが送られ、ユーザーがEメールに記載されているリンクをクリックする必要があります。

これに関する具体的な変更は下記のとおりで、移行に影響を与えることになります。

これに関する1つ目の変更は、 standalone.xml または standalone-ha.xml 内の新しいInfinispanのキャッシュ authenticationSessionsactionTokens を導入したことです。移行CLIを使用している場合は、 standalone(-ha).xml ファイルは自動的に移行されるため、ほとんど気にする必要はありません。

2つ目の変更は、認証SPIのメソッドで複数の署名を変更したことです。この変更により、カスタム Authenticator または RequiredActionProvider を使用すると影響を受けることになります。クラス AuthenticationFlowContextRequiredActionContext によって、クライアント・セッションの代わりに認証セッションを取得することができます。

また、スティッキー・セッションの初回サポートも追加しました。パフォーマンスを上げたい場合は、ロードバランサーまたはプロキシー・サーバーを変更し、それを設定できます。ルートには新しい AUTH_SESSION_ID Cookieに追加されます。詳しくは、クラスター構成についてのドキュメントを参照してください。

別の変更点として、 token.getClientSession() が削除されたことがあります。これは、たとえば、クライアントの初回アイデンティティー・ブローカー・リンキング機能を使用している場合などに、影響を受ける可能性があります。

ScriptBasedAuthenticator のバインディング名が、 clientSession から authenticationSession に変更されました。そのため、このオーセンティケーターを使用している場合、スクリプトを更新する必要があります。

最後に、新しいタイムアウトを管理コンソールに追加しました。この追加によって、たとえば、管理者およびユーザー自身によってトリガーされた電子メール・アクションに異なるタイムアウトを指定することができます。

2.5.1への移行

古いオフライン・トークンの移行

2.2.0以前から移行してオフライン・トークンを使用した場合、オフライン・トークンは トークンのヘッダーにKIDを含んでいません。2.3.0では、複数のレルム鍵を持つ機能に加えて、KIDをトークン・ヘッダーに追加しました。そのため、KeycloakはトークンのKIDに基づく正しい鍵を見つけることができます。

KIDを含まないオフライン・トークンの場合、Keycloak 2.5.1はトークンの検証に適した鍵を見つけるため、常にアクティブなレルム鍵を使用します。言い換えると、古いオフライン・トークンが移行されることになります。そのため、たとえば、ユーザーが1.9.8でオフライン・トークンを要求すると、1.9.8から2.5.1に移行されたとき、ユーザーは2.5.1であっても古いオフライン・トークンをリフレッシュできることになります。

しかし、これには制限があります。アクティブなレルム鍵をいったん変更すると、ユーザーは古いオフライン・トークンを更新することができなくなります。したがって、オフライン・トークンを使用している全ユーザーが自身のトークンを更新するまで、アクティブ・レルム鍵を変更すべきではありません。新しく更新されたトークンには、確実にヘッダーにKIDが付与されます。そのため、全ユーザーが自身の古いオフライン・トークンを更新した後は、アクティブなレルム鍵を自由に変更することができます。

2.5.0への移行

Infinispanキャッシュへの変更

standalone.xml または standalone-ha.xml 設定ファイル内のInfinispanサブシステムで定義された realms キャッシュには、現在、デフォルトで10000レコードのエビクションが用意されています。 users キャッシュにも、同じようにデフォルト値が設定されています。

また、 authorization キャッシュにはデフォルトではエビクションは用意されていません。

2.4.0への移行

Server SPIをServer SPIとSever SPI Privateへ分割

keycloak-server-spiモジュールは、keycloak-server-spiとkeycloak-server-spi-privateに分割されています。今後のマイナーリリースにおいて、keycloak-server-spi内のAPIは変更しませんが、keycloak-server-spi-private内のAPIは変更する可能性が十分にあります。

SAMLアサーションのキーの暗号化アルゴリズム

現在、SAMLアサーション内のキーとドキュメントは、RSA-OAEP暗号化方式を使用して暗号化されています。暗号化されたアサーションを使用する場合、サービスプロバイダーがこの暗号化方式を理解していることを確認してください。稀なケースながら、SPがこの新しい方式を処理できない場合は、システム・プロパティー keycloak.saml.key_trans.rsa_v1.5true に設定して起動すると、KeycloakはレガシーなRSA-v1.5暗号化方式を使用することができます。

realmsとusersのInfinispanキャッシュは常にロ-カル

クラスター内でKeycloakを使用する場合でも、 standalone-ha.xml 内のinfinispanサブシステム内で定義されたキャッシュ realmsusers は、現在常にローカル・キャッシュです。これらとは別に、クラスターノード間で無効化メッセージの送信し、クラスター全体に、 realmsusers キャッシュの前提となるレコードの内どれが無効となるのかを知らせるキャッシュ work というものがあります。

2.3.0への移行

ページネーションされたエンドポイントのデフォルト最大値

現在、ページネーションをサポートするすべての管理REST APIエンドポイントで、最大結果件数のデフォルトは100に設定されています。100を超えるエントリーを返す場合は、敢えて ?max=<RESULTS> を使用して、それを指定する必要があります。

2.3.0リリースには、公開鍵ローテーションへのサポートを追加しました。管理者がKeycloak管理コンソールでレルム鍵のローテーションを行うと、クライアント・アダプターはそれを認識し、自動的に新しい公開鍵をKeycloakからダウンロードすることができます。ただし、ハードコーディングされた公開鍵を持つアダプターに realm-public-key オプションが指定されていない場合にのみ、この新しい鍵の自動ダウンロードは実行されます。このため、アダプター設定では realm-public-key オプションの使用は推奨されません。

このオプションは引き続きサポートはされていますが、アダプター設定でハードコーディングされた公開鍵を使用し、Keycloakから公開鍵をダウンロードしない場合にのみ便利です。この方法を使用する理論上の理由としては、アダプターとKeycloakの間に信頼できないネットワークがある場合に中間者攻撃を避けることができるという理由になりますが、実際はその場合、HTTPSを使用する方がはるかに良いです。HTTPSを使用すれば、アダプターとKeycloakの間のすべてのリクエストはセキュリティー上安全です。

Infinispanキャッシュ keys の追加

このリリースでは、 standalone.xml または standalone-ha.xml 設定ファイルで定義されたInfinispanサブシステムに、新しいキャッシュ keys を追加しました。これには、エビクションと期限があります。このキャッシュは、サーバー(署名されたJWTでの認証を使用するアイデンティティー・プロバイダーまたはクライアント)によって信頼されるエンティティーの外部公開鍵をキャッシュするために内部的に使用されます。

2.2.0への移行

databaseSchema プロパティーの 廃止

現在、JPAとMongoの両方の databaseSchema プロパティーは 廃止 され、 initializeEmptymigrationStrategy によって置き換えられています。 initializeEmptytrue または false に設定することができ、空のデータベースを初期化すべきかどうかを制御します。 migrationStrategyupdatevalidate および manual に設定することができます。 manual はリレーショナル・データベースでのみサポートされており、SQLファイルを作成してデータベース・スキーマに必要な変更を加えます。Oracle Databaseの場合は、作成されたSQLファイルには、OracleのSQLクライアントが理解できる SET DEFINE OFF コマンドが含まれています。他のクライアントがこのスクリプトを使用する場合は、変数の展開を無効にするためのツールの同等のコマンドで行を置換するか、そのような機能が適用されない場合は完全に削除してください。

クライアントの有効なリダイレクトURIの変更

以下のシナリオは、影響を受けることになります。

  • クエリー・コンポーネントを持つ有効なリダイレクトURIがクライアント(サンプルとしては http://localhost/auth?foo=bar )で保存された場合、認証要求の redirect_uri はこのURI(または、このクライアントで登録された他のURI)と完全に一致する必要があります。

  • クエリー・コンポーネントを持たない有効なリダイレクトURIがクライアントに保存された場合も、 redirect_uri はこのURIと完全に一致する必要があります。

  • クエリー・コンポーネントを持たない、登録済みの有効なリダイレクトURIのワイルドカードは、サポートされなくなりました。そのため、 redirect_uri はこの登録済みのURIとも同様に一致する必要があります。

  • 登録済みの有効なリダイレクトURI( http://localhost/auth#fragment など)内のフラグメントはもはや許可されません。

アイデンティティー・プロバイダーからデフォルトで削除された認証

アイデンティティー・プロバイダーには、デフォルトの認証プロバイダーとして設定されるオプションはもはやありません。その代わり、認証に移動して Browser フローを選択し、 Identity Provider Redirector を設定します。デフォルトのアイデンティティー・プロバイダーを設定するオプションがあります。

2.0.0への移行

1.0.0.Finalからのアップグレードはサポートされなくなりました

1.0.0.Finalからのアップグレードはサポートされなくなりました。2.0.0へアップグレードするには、その前に1.9.8.Finalへアップグレードしてください。

1.9.5への移行

デフォルトのパスワード・ハッシュ間隔は20Kに増加

新しいレルムのためにデフォルトでパスワードをハッシングする間隔は、(以前の1から) 20Kに増加されました。この変更により、ユーザー認証時のパフォーマンスが影響を受けることになります。たとえば、以前のデフォルト(1)ではパスワードをハッシングするのに1ミリ秒もかかりませんでしたが、新しいデフォルト(20K)では50から100ミリ秒かかります。

1.9.3への移行

ユーザー追加スクリプトの名前の変更

Keycloakの管理者ユーザーを追加するスクリプトの名前を、 add-user-keycloak へ変更しました。

1.9.2への移行

アダプター・オプションauth-server-url-for-backend-requestsを削除

オプションauth-server-url-for-backend-requestsは削除しました。このオプションが使用されると、いくつかのシナリオに問題が生じたためです。具体的には、2つの異なるコンテキスト(内部および外部)からKeycloakサーバーへのアクセスが可能だったのですが、このことがトークンを検証する際などに問題を起こしていました。

それでも、このオプションが提供する(アプリケーションがバックチャネル・リクエストをロードバランサーを通じて送るのではなく、ローカルのKeycloakサーバーに直接送るという)ネットワークの最適化を使用したい場合は、ホスト設定(DNS)レベルで処理する必要があります。

1.9.0への移行

テーマとプロバイダーのディレクトリーを移動

テーマとプロバイダーのディレクトリーを standalone/configuration/themesstandalone/configuration/providers から themesproviders へそれぞれ移動させました。カスタマイズしたテーマとプロバイダーを追加している場合は、それらを新しい場所に移動させる必要があります。また、このことによって変更されたとおりに、 keycloak-server.json を更新する必要もあります。

アダプター・サブシステムはKeycloakが有効な場合にのみ依存関係となる

以前は、SAMLまたはOIDCのKeycloakサブシステム・アダプターを、WildFlyまたはJBoss EAPにすでにインストールしていた場合に、Keycloakを使用していたか否かに関わらず、全てのアプリケーションにKeycloakクライアントのjarを自動的に含めていました。現在は、そのアダプターのためにKeycloak認証を(サブシステムまたはweb.xml内のauth-methodを通じて)有効にしている場合にのみ、これらのライブラリーはデプロイメントに追加されることになります。

クライアント登録サービスのエンドポイントを移動

クライアント登録サービスのエンドポイントは、 {realm-name}/clients から {realm-name}/clients-registrations へ移動しました。

認証レスポンスのセッション・ステートのパラメーター名を変更

OpenID Connectの認証レスポンスにおけるセッション状態を session-state というキー名にしていましたが、これは仕様上間違っていたため、 session_state に変更しました。

いくつかのOpenID Connectエンドポイントを廃止

1.2では、OpenID Connectの仕様と合わないエンドポイントを大量に廃止し、現在は削除されています。これは、1.8で新しいイントロスペクト・エンドポイントに置き換えられた、トークン検証エンドポイントにも適用されます。

テーマのテンプレートを更新

template.ftlのフィードバックを移動し、フォーマットをわずかに変更しました。

モジュールとソースコードを再編

モジュールとソースコードのほとんどは、keycloak-server-spiおよびkeycloak-servicesという、2つのmavenモジュールに統合されました。 SPIのインターフェイスはserver-spiに、実装はkeycloak-servicesに統合されています。すべてのJPA依存のモジュールはkeycloak-model-jpaに統合されました。mongoとInfinispanも同様で、keycloak-model-mongoとkeycloak-model-infinispanのモジュールに統合されています。

アダプターによりログイン後のセッションIDを変更

セッションIDをサポートするプラットフォーム(Tomcat 8、Undertow/WildFly、Jetty9)では、セキュリティー攻撃口をふさぐために、ログイン後にKeycloakのOIDCとSAMLアダプターによってセッションIDが変更されます。この動作をアダプターの設定スイッチをチェックすることでオフにすることができます。

SAML SPクライアント・アダプターの変更

現在、KeycloakのSAML SPクライアント・アダプターは、IDPで登録されるために、特定のエンドポイント /saml を要求します。

1.8.0への移行

管理者アカウント

以前のリリースでは、デフォルトのパスワードでデフォルトの管理者ユーザーを設定していましたが、現在はこれを削除しています。1.8の新規のインストールでは、最初の手順として管理者ユーザーを作成する必要があります。

OAuth2トークン・イントロスペクション

OAuth2の仕様により合わせるために、トークン・イントロスペクション用の新しいエンドポイントを追加しました。新しいエンドポイントは /realms/{realm-name}/protocols/openid-connect/token/introspect で取得することができ、 RFC-7662 にのみ基づいています。

/realms/{realm-name}/protocols/openid-connect/validate エンドポイントは現在廃止されています。新しいイントロスペクション・エンドポイントにできるだけ早く移動することを強くお勧めします。この変更の理由は、RFC-7662が、より標準的でセキュリティー上安全なイントロスペクション・エンドポイントが提供していることです。

新しいトークン・イントロスペクションURLは、現在 /realms/{realm-name}/.well-known/openid-configuration 上のOpenID Connectプロバイダーの設定から取得することができます。このレスポンス内に、 token_introspection_endpoint という名前のクレームがあります。 confidential clients だけがこの新しいエンドポイントを呼び出すことが許可されており、そこでは、これらのクライアントは通常、リソースサーバーとして機能し、ローカルの認可チェックを実施するために、トークンのメタデータを検索します。

1.7.0.CR1への移行

クライアントのダイレクト・アクセス・グラントをデフォルトで無効化

OpenID Connectの仕様により合わせるために、管理コンソールのClient Settingsのページにフラグを追加しました。そのページでは、さまざまな種類のOpenID ConnectまたはOAuth2のフロー(Standard flow、Implicit flow、Direct Access Grants、Service Accounts)を有効または無効にすることができます。この一環として、新規クライアント用にはデフォルトで無効となっている Direct Access Grants (OAuth2の Resource Owner Password Credentials Grant に対応)があります。

以前のバージョンから移行されたクライアントは、 Direct Grants Only フラグがオンである場合のみ、 Direct Access Grants が有効になります。ダイレクト・アクセス・グラントを有効にし、スタンダード + インプリシットの両方のフローを無効にした場合と同等の、 Direct Grants Only フラグは削除されました(同じ効果となるため)。

また、組み込みのクライアント admin-cli を各レルムに追加しました。このクライアントは Direct Access Grants が有効になっています。そのため、管理REST APIまたはKeycloakの管理クライアントを使用している場合は、 security-admin-console の代わりに admin-cli を使用するように設定を更新する必要があります。現在、後者はデフォルトでダイレクト・アクセス・グラントが有効になっていないためです。

オプション’Update Profile On First Login’をアイデンティティー・プロバイダーからレビュー・プロファイル・オーセンティケーターへ移動

このバージョンで、 First Broker Login を追加しました。この追加により、新規ユーザーがアイデンティティー・プロバイダー(またはソーシャル・プロバイダー)を介してログインした際、ソーシャルアカウントにリンクされたKeycloakユーザーがまだ存在しない場合に何を実行するかを正確に指定できます。この一環として、 First Login Flow オプションをアイデンティティー・プロバイダーに追加しました。これにより、フローを特定し、管理コンソール内の Authentication タブでこのフローを設定することができるようになりました。

また、 Update Profile On First Login オプションをアイデンティティー・プロバイダー設定から削除し、 Review Profile オーセンティケーターの設定に移動させました。そのため、アイデンティティー・プロバイダー用にはどのフローを使う必要があるのかを指定すれば(デフォルトでは First Broker Login フローとなっていますが)、 Authentication タブに移動してフローを選択し、 Review Profile オーセンティケーターの下にあるオプションで設定することができます。

web.xml内の 'form-error-page' 要素のサポートを終了

web.xml内のform-error-pageは、クライアント・アダプター認証エラーにより動作しなくなりました。さまざまなHTTPエラーコード用にerror-pageを定義する必要があります。アダプターのエラー条件を確認および処理したい場合、詳細はドキュメントを参照してください。

IdentityProviderMapperの変更

インターフェイス自体またはメソッドのシグネチャーに、変更はありません。しかし、動作には変更がいくつかあります。このリリースでは First Broker Login フローを追加し、 メソッド IdentityProviderMapper.importNewUserFirst Broker Login フローが完了した後に呼び出されるようになりました。そのため、Review Profile ページ任意の属性を利用できるようにするには、 importNewUser の代わりに preprocessFederatedIdentity メソッドを使用する必要があります。 BrokeredIdentityContext.setUserAttribute を呼び出して属性を設定することができ、それを Review profile ページで利用できます。

1.6.0.Finalへの移行

リフレッシュ・トークンを再利用しないオプション

Keycloakの古いバージョンでは、リフレッシュ・トークンを何回でも再利用することができました。Keycloakではこの再利用はいまだに許可されていますが、 Revoke refresh token オプションでこれを許可しないこともできます。このオプションは管理コンソールのトークン設定配下にあります。新しいアクセス・トークンが取得するためにリフレッシュ・トークンが使用された場合、新しいリフレッシュ・トークンもそこに含まれることになります。オプションが有効である場合は、次にアクセス・トークンがリフレッシュされた際に、この新しいリフレッシュ・トークンを使用する必要があります。古いリフレッシュ・トークンを何回も再利用することはできません。

パッケージの名前がいくつか変更されました

いくつかのパッケージの構成と名前を少し変更しました。主にutilクラスの内部パッケージ名の変更です。アプリケーション(たとえば、AccessTokenまたはKeycloakSecurityContext)で使用される最も重要なクラスとSPIは変更されていません。ただし、影響を受けたりクラスのインポートを更新する必要がでてきたりする可能性がわずかながらあります。たとえば、multitenancyとKeycloakConfigResolverを使用している場合は、HttpFacadeクラスが別のパッケージ(これは現時点では org.keycloak.adapters.spi.HttpFacade です。)に移動されたのと同じように、影響を受けます。

ユーザー・セッションの永続化

このリリースにはオフライン・トークンのサポートを追加しました。つまり、 "offline" ユーザー・セッションは現在データベース内で永続化されているということです。オフライン・トークンを使用していない場合は、何も永続化されていませんので、 DBに追加で書き込むとパフォーマンスが低下するのではないかと心配する必要はありません。しかし、いかなる場合でも、 standalone/configuration/keycloak-server.json を更新し、以下のように userSessionPersister を追加する必要があります。

"userSessionPersister": {
    "provider": "jpa"
},

昔のRDBMSの代わりに、Mongo内でセッションを永続化させたい場合は、 mongo プロバイダーを代用してください。

1.5.0.Finalへの移行

レルムとユーザーのキャッシュ・プロバイダー

Infinispanは現在デフォルトでレルムとユーザーのキャッシュ・プロバイダーのみとなっています。非クラスターモードでは、ローカルのInfinispanキャッシュが使用されます。また、カスタムのイン・メモリー・キャッシュと非キャッシュ・プロバイダーは削除しました。realmCacheまたはuserCacheがkeycloak-server.jsonでmemまたはnoneに設定されている場合は、それらを削除してください。Infinispanは、realmCacheとuserCacheのオブジェクトを必要としなくなった唯一のプロバイダーなので、それらを削除することができます。

ユーザー・セッション・プロバイダー

Infinispanは現在デフォルトで唯一のユーザー・セッション・プロバイダーです。非クラスター・モードでは、ローカルのInfinispanキャッシュが使用されます。また、JPAとMongoユーザー・セッション・プロバイダーを削除しました。ユーザー・セッションをkeycloak-server.jsonでmem、jpaまたはmongoに設定している場合、それを削除してください。Infinispanは、ユーザー・セッションのオブジェクトを必要としなくなった唯一のプロバイダーなので、それを削除することができます。

ユーザー・セッションの耐久性を上げたい場合、ユーザー・セッション・キャッシュを一人以上の所有者で設定するか、または複製したキャッシュを使用します。また、Infinispanを設定してキャッシュを保持させる方法でも可能です。ただし、パフォーマンスに影響を与える可能性があります。

コンタクト詳細を登録とアカウント管理から削除

デフォルトのテーマでは、登録ページとアカウント管理からコンタクト詳細を現在削除してあります。管理コンソールには、特定のコンタクト属性だけでなく、現在すべてのユーザー属性がリスト表示されます。また、管理コンソールには、ユーザーに属性を追加したり削除したりする機能があります。コンタクト詳細を追加する場合は、サンプルに含まれているアドレス・テーマを参照してください。

1.3.0.Finalへの移行

ダイレクト・グラントAPIは常に有効

以前は、ダイレクト・グラントAPI(またはリソース・オーナー・パスワード・クレデンシャル)はデフォルトで無効となっており、レルムのオプションによってそれを有効にすることができました。現在は、ダイレクト・グラントAPIは常に有効で、レルムで有効または無効にできるオプションは削除されています。

データベースの変更

データベースの変更はほとんどありません。アップグレードする前にデータベースを忘れずバックアップしてください。

UserFederationProviderの変更

UserFederationProviderインターフェイスの変更はわずかなマイナーチェンジのみです。新しいバージョンにアップグレードする際に実装を同期させ、シグネチャーを変更したいくつかのメソッドをアップグレードする必要があるかもしれません。変更は本当にわずかですが、フェデレーションのパフォーマンスを上げるために必要でした。

WildFly 9.0.0.Final

最新リリースで実行された配布物の変更に伴って、現在Keycloakのスタンドアローン・ダウンロードはWildFly 9.0.0.Finalに基づいています。また、これはオーバーレイにも影響を及ぼし、WildFly 9.0.0.FinalまたはJBoss EAP6.4.0.GAにのみこのオーバーレイをデプロイすることができるようになりました。WildFly 8.2.0.Finalはサーバー用にサポートされなくなりました。

WildFly、JBoss EAPおよびJBoss AS7アダプター

下記のとおり、WildFly、JBoss EAPおよびJBoss AS7用の3つの別のアダプター・ダウンロードがあります。

  • eap6

  • wf9

  • wf8

  • as7

適切なものを選ぶよう注意してください。

また、拡張モジュールとサブシステム定義が変更されたので、standalone.xmlを更新する必要があります。詳しくは、Securing Applications and Services Guideを参照してください。

1.2.0.Beta1から1.2.0.RC1への移行

配布物の変更

現在、Keycloakは3つのダウンロードで使用することができます。スタンドアローン、オーバーレイおよびデモ・バンドルの3つになります。スタンドアローンはプロダクションと非JEE開発者用に作られたものです。オーバーレイは既存のWildFly 8.2またはEAP 6.4環境へのKeycloakの追加を目的としており、主に開発用に作られたものです。最後にデモ(または開発)バンドルについてですが、これは開発者がKeycloakをはじめられるように作られたものです。このバンドルには、Keycloakサーバーとアダプターだけでなく、WildFlyサーバーも含まれます。また、すべてのドキュメントとサンプルも含まれています。

データベースの変更

このリリースには、データベース上の変更点がいくつかあります。最も大きな変更は、アプリケーションとOAuthのクライアントのマージです。アップグレードする前に、データベースを忘れずにバックアップしてください。

アプリケーションとOAuthクライアントのマージ

現在、アプリケーションとOAuthクライアントは Clients にマージされています。管理コンソールのUIは更新されており、データベースも同様です。データベースのデータは自動的に更新されます。以前に設定されたアプリケーションは Consent required スイッチがオフのクライアントに変換され、OAuthクライアントはこのスイッチがオンのクライアントに変換されます。

1.1.0.Finalから1.2.0.Beta1への移行

データベースの変更

このリリースには、データベース上の変更点がいくつかあります。アップグレードする前に、データベースを忘れずにバックアップしてください。

アクセス・トークンとIDトークン内の iss

アクセス・トークンとIDトークン内の iss クレームの値は、 realm name から realm url へ変更されました。これはOpenID Connectの仕様の要求によるものです。アダプターを使用している場合は変更の必要はありませんが、 auth-server-url を指定せずにbearer-onlyだけを使用していた場合は変更する必要があります。別のライブラリ(またはRSATokenVerifier)を使用している場合は、 iss の検証時に対応できるよう変更を加える必要があります。

OpenID Connectエンドポイント

OpenID Connect仕様に合わせるために、認証とトークンのエンドポイントは、単一の認証エンドポイントと単一のトークン・エンドポイントを持つように変更されました。仕様どおりに response_typegrant_type パラメーターが使用され、必要なフローを選択できるようになります。古いエンドポイント( /realms/{realm-name}/protocols/openid-connect/login , /realms/{realm-name}/protocols/openid-connect/grants/access , /realms/{realm-name}/protocols/openid-connect/refresh , /realms/{realm-name}/protocols/openid-connect/access/codes )は現在廃止されており、今後の新しいバージョンでは削除されます。

テーマの変更

テーマのレイアウトを変更しました。以前はディレクトリーの階層は type/name でしたが、現在は name/type に変更されています。たとえば、 sunrise という名前のログイン・テーマは、以前は standalone/configuration/themes/login/sunrise にデプロイされていましたが、現在は standalone/configuration/themes/sunrise/login に移されています。この変更は、同じテーマの異なるタイプのグループを1つのフォルダに保存するのを簡単にするために実施しました。

以前は、テーマをJARとしてデプロイした場合、Javaコードが必要なカスタム・テーマ・ローダーを作成する必要がありました。現在は、これが簡略化され、簡単なテキストファイル( META-INF/keycloak-themes.json )だけで、JARに含まれるテーマを記述できるようになりました。

クレームの変更

以前は、アプリケーションとOAuthクライアント用に、管理コンソール内に Claims タブがありました。これは、特定のアプリケーションまたはクライアント用に、どの属性をアクセストークンに入れるのかを設定するために使用していました。このタブは削除され、より柔軟性が高いプロトコル・マッパーに置き換えました。

以前のバージョンからのデータベースの移動については気にする必要はありません。RDBMSとMongoの両方用の移行スクリプトの実行により、特定のアプリケーションまたはクライアント用に設定されたクレームは、対応するプロトコル・マッパーに変更されるようになりました(そうは言っても、新しいバージョンに移行する前にDBをバックアップしておいた方が安全です)。以前のバージョンからエクスポートされたJSONの記述についても、同様になります。

ソーシャルをアイデンティティー・ブローカリングへ移行

ソーシャル・プロバイダーSPIを、リファクタリングしてアイデンティティー・ブローカリングSPIに置き換えました。この方が柔軟性が高いです。管理コンソール内の Social タブは Identity Provider タブに名前が変更されました。

また、クレーム/プロトコル・マッパーと同様に、以前のバージョンからのデータベース移行について気にする必要はありません。ソーシャル・プロバイダーの設定とユーザーへの "social links" の両方は、対応するアイデンティティー・プロバイダーに変換されます。

実施すべきことは、特定のサード・パーティーのソーシャル・プロバイダーの管理コンソール内にある許可済みの Redirect URI に変更することのみです。まず、Keycloak管理コンソールに移動し、アイデンティティー・プロバイダーを設定したページからRedirect URIをコピーします。次に、サード・パーティーのプロバイダーの管理コンソール(たとえばFacebookの管理コンソール)に、許可されたRedirect URIとしてこれをペーストするだけです。

1.1.0.Beta1から1.1.0.Beta2への移行

  • 現在、アダプターは別途ダウンロードすることになっています。これはアプライアンスやwar配布物には含まれていません。現在配布物にはあまりに多くのものが含まれていて、肥大化している状態です。

  • org.keycloak.adapters.tomcat7.KeycloakAuthenticatorValve +org.keycloak.adapters.tomcat.KeycloakAuthenticatorValve

  • 現在、JavaScriptアダプターには、idTokenとidTokenParsedプロパティーがあります。idTokenを使用してファーストネームやEメールなどを取得する場合、これをidTokenParsedに変更する必要があります。

  • as7-eap-subsystemとkeycloak-wildfly-subsystemは、1つのkeycloak-subsystemに統合されました。既存のstandalone.xmlまたはdomain.xmlを持っている場合は、ファイルの先頭あたりを編集し、拡張モジュール名をorg.keycloak.keycloak-subsystemに変更する必要があります。AS7だけは、拡張モジュール名がorg.keycloak.keycloak-as7-subsystemになります。

  • サーバーのインストールはAS7ではサポートされなくなりました。それでも、AS7はアプリケーション・クライアントとして使用することができます。

1.0.x.Finalから1.1.0.Beta1への移行

  • RealmModelのJPAとMongoストレージ・スキーマが変更されました

  • UserSessionModelのJPAとMongoストレージ・スキーマは、これらのインターフェイスがリファクタリングされたので、変更されました

  • アダプターをアップグレードしてください。古いアダプターはKeycloak 1.1と互換性がありません。JSON Web TokenとOIDC ID Tokenの仕様は間違って解釈されていました。 'aud' クレームはクライアントIDでなければなりませんが、そこにレルム名が格納されて検証されていました。

1.0 RC-1からRC-2への移行

  • 情報レベルのロギングの多くがデバッグレベルに変更されました。また、デフォルトではレルムにjboss-logging監査リスナーが無くなりました。ユーザーがログイン、ログアウト、パスワードの変更などをする際にログの出力が必要な場合は、管理コンソールでjboss-logging監査リスナーを有効にしてください。

1.0 Beta 4からRC-1への移行

  • ログアウトREST APIはリファクタリングされました。ログアウトURIのGETリクエストはsession_stateパラメーターを取得しなくなりました。セッションをログアウトするには、ログインする必要があります。また、ログアウトREST URIにPOSTすることもできます。このアクションでは、ログアウトするために有効なリフレッシュ・トークンが必要です。シグネチャーは、パラメーターからグラント・タイプを差し引いたリフレッシュ・トークンと同じものです。詳しくは、ドキュメントを参照してください。

1.0 Beta 1からBeta 4への移行

  • LDAP/AD設定は変更されました。これは "Settings" ページには存在しなくなりました。現在はUsers→Federationにあります。プロバイダーの追加には、 "ldap" オプションが表示されます。

  • 認証SPIは削除されて書き換えられました。新しいSPIはUserFederationProviderで、より柔軟性が高くなっています。

  • ssl-not-required +ssl-required +all +external +none

  • DBスキーマは再度変更されました。

  • 新規作成されたアプリケーションは、デフォルトでフルスコープを持つようになりました。つまり、必要ない場合は、アプリケーションのスコープを設定する必要はありません。

  • レルムデータをインポートするためのJSONファイルのフォーマットが変更されました。現在は特定のユーザーのJSONレコードでロール・マッピングを使用することができます。

1.0 Alpha 4からBeta 1への移行

  • DBスキーマが変更されました。Beta 1へデータベースのエクスポートを追加しましたが、古いバージョンからデータベースをインポートすることはできませんでした。これについては、今後のリリースでサポートされることになります。

  • ベアラー専用のアプリケーションを除いてクライアントはすべて、少なくとも1つのリダイレクトURIを指定する必要があります。そのアプリケーション用の有効なリダイレクトURIを指定しないと、Keycloakへのログインは許可されません。

  • Direct Grant API +ON

  • standalone/configuration/keycloak-server.json

  • JavaScriptアダプター

  • セッション・タイムアウト

1.0 Alpha 2からAlpha 3への移行

  • SkeletonKeyToken、SkeletonKeyScope、SkeletonKeyPrincipal、およびSkeletonKeySessionは、それぞれAccessToken、AccessScope、KeycloakPrincipal、およびKeycloakAuthenticatedSessionに名前が変更されました。

  • ServletOAuthClient.getBearerToken()メソッドのシグネチャーが変更されました。現在は、AccessTokenResponseが返されて、リフレッシュ・トークンも取得できるようになりました。

  • 現在、アダプターはリクエストの度にアクセス・トークンの期限を確認します。トークンが期限切れになっていると、アダプターは保存されたリフレッシュ・トークンを使用して、認証サーバー上でリフレッシュを実行しようとします。

  • AccessTokenのサブジェクトがUser IDに変更されました。

1.0 Alpha 1からAlpha 2への移行

  • DBスキーマが変更されました。Alpha 2の時点では、データ移行ユーティリティーはまだありません。

  • 現在、JBossアダプターとWildFlyアダプターはWildFlyサブシステムでインストールされています。アダプターのインストールのドキュメントを参照ください。現在、standalone.xmlへの編集が必要です。

  • 新しいクレデンシャル・タイプ "secret" が導入されました。他のクレデンシャル・タイプと異なり、データベース内のプレーンテキストに保存されていて、管理コンソールで確認することができます。

  • アプリケーションとOAuthクライアントのクレデンシャルは不要になりました。これらのクライアント・タイプは、 "secret" クレデンシャル・タイプを使用するようにハードコードされています。

  • アプリケーションとOAuthクライアントに対する "secret" クレデンシャルの変更により、管理コンソールのアプリケーションまたはOAuthクライアント・クレデンシャルのタブで、keycloak.json設定ファイルを更新してシークレットを再生成する必要があります。