Keycloakバージョン15.0〜19.0.2までの変更点一部紹介

概要

Keycloakは頻繁にバージョンアップされています。GitHubのリリースページを見ると、ほぼ毎月でしょうか。

この記事では、Keycloakを以前試したことのある方を主なターゲットとして、Keycloak15.0あたりから19.0.2までに変更された機能をピックアップして紹介します。

WildFlyからQuarkusへの変更

• Keycloakを実行するためのアプリケーションが、WildFly(アプリケーションサーバ)からQuarkusに移行しました。
• WildFlyを内蔵したKeycloakは非推奨ですが、19.0.2時点でもリリースされています。

Quarkusとは

従来、JavaはソースコードからJavaの実行ファイルにコンパイルされて、実行時にはJavaVMが必要に応じて必要な部分をネイティブバイナリにコンパイルしながら動作します。 Quarkusでは、「GraalVM」というコンパイラを使ってJavaコードからLinuxのネイティブバイナリを生成して、実行時にはネイティブバイナリを起動するようです。

WildFlyからQuarkusへの移行

• Quarkusはいつから？

  • Keycloak 17.0.0 からサポートされました。
  • https://www.keycloak.org/2022/02/keycloak-1700-released#_quarkus_distribution_is_now_fully_supported

• WildFlyはいつまで？

  • サポートは2022年6月までのようです。
  • すでに稼働しているKeycloakをWildFlyからQuarkusに移行するための公式ガイドがあります。
    • https://www.keycloak.org/migration/migrating-to-quarkus

Quarkusに移行したことによる変更点

起動コマンドが変わっています。

• WildFlyだった頃(一例)
  • ./bin/standalone.sh -c standalone.xml
  • →弊社内関連ブログ記事
• Quarkusになってから(一例)
  • ./bin/kc.sh start-dev
  • →弊社内関連ブログ記事

コマンドで初期管理者ユーザを作成する方法が変わっています。

WildFlyだった頃

• ./add-user-keycloak.shを実行して管理者ユーザを作成してKeycloakを再起動していました。

Quarkusになってから

• 環境変数KEYCLOAK_ADMINにユーザ名、KEYCLOAK_ADMIN_PASSWORDにパスワードを設定してからKeycloakを起動すると、環境変数の値を読み込み管理者ユーザが作成されます。

デフォルトのコンテキストパスがなくなっています。

• URLが変わりました。
  • 以前は、http://＜FQDN＞:8080/auth
  • 現在は、http://＜FQDN＞:8080/
• 注意点
  • 古い記事を参考にkcadm.shで接続するとき、サーバURLのプレフィックスの指定に注意してください。
  • コンテキストパスを独自に設定することもできます。
    • 環境変数としてexport KC_HTTP_RELATIVE_PATH=/authのように設定します。
    • 関連ドキュメント: http-relative-path

カスタムプロバイダ(SPI)のホットデプロイがサポートされなくなりました。

カスタムプロバイダ(Service Provider Interfaces)のデプロイ方法が変更になっています。

変更点

• 変更前 (サポートされなくなったこと)
  • カスタムプロバイダをstandalone/deploymentsディレクトリに配置すると実行中のKeycloakが自動的に読み込んでくれるホットデプロイはサポートされなくなりました。
  • EARパッケージ形式を作成してlib/ディレクトリに配置する方法や、jboss-deployment-structure.xmlファイルもサポートされなくなりました。
• 変更後
  • providersディレクトリに配置したあと、Keycloakを再起動する必要があります。

関連ドキュメント

• providersディレクトリ (Keycloak 19.0.2)
  • https://www.keycloak.org/docs/19.0.2/server_development/#packaging-and-deployment
• standalone/deploymentsディレクトリ (Keycloak 16.0)
  • https://www.keycloak.org/docs/16.0/server_development/index.html#registering-provider-implementations

その他のKeycloak 15.0以降の主な変更点

QuarkusかWildFlyかに関わらず、以前にKeycloakを利用した方にとって気になると思われる変更(筆者の主観)をピックアップします。

OIDC Logout に対応しました。

Keycloakバージョン15.0.0で、「Front channel logout」に対応しました。 その後、バージョン18、19で改善が行われています。

• 公式ドキュメント
  • https://www.keycloak.org/docs/19.0.2/server_admin/#_oidc-logout

管理画面のデザイン変更 (バージョン19.0.0)

管理画面のデザインが変わりました。

• レルム設定画面
  • 旧画面 (Keycloak 18.0.2)
    
  • 新画面 (Keycloak 19.0.2)
    
• 認証設定画面
  • 旧画面 (Keycloak 18.0.2)
    
  • 新画面 (Keycloak 19.0.2)
    
• ドキュメント
  • https://www.keycloak.org/docs/latest/release_notes/index.html#new-admin-console-graduation

User Storage SPIの仕様変更

「User Storage SPI」は、外部のLDAPやActive Directoryに登録されているユーザをKeycloakに取り込んで認証等に利用できるようにする機能ですが、この機能はkeycloak-model-legacyに変更されて、いずれ廃止となります。

後継として、「Map Storage SPI」となります。Keycloak 19.0.0時点ではまだ完全ではありません。

• ドキュメント
  • https://www.keycloak.org/2022/07/storage-map.html
  • https://www.keycloak.org/docs/19.0.2/server_development/#_user-storage-spi

そのほかの変更点

• Quarkusへの移行による変更点は、以下の公式ドキュメントにまとめられています。
  • Migrating to Quarkus distribution
• Release notes
  • Release note