Upgrade Keycloak (WildFly) to Keycloak.X (Quarkus)

Tagbangers ではマイクロサービスとして認証サービスとアプリサービスを分離および認証を統合して再利用しているプロジェクトがあります

認証サービスは Keycloak を用いており EKS 上に Helm を利用して展開しています

A curated set of Helm charts brought to you by codecentric

アプリサービスは Spring Boot を用いて Keycloak と認証の連携を行なっています
連携に関する下記の記事もご参照ください

Keycloak と Spring Boot アプリケーションで OpenID Connect の Authorization Code Flow を確認する

Keycloak はアップデートが活発でメジャーバージョンが上がることが多いです
一方で古いバージョンのパッチは消極的に見えるため、保守プロジェクトでは随時アップデートを行なう必要があります

Release Notes - Keycloak

現在私が携わっているプロジェクトでは今年の春に Keycloak 9.x から 16.x にバージョンアップしたばかりですが、既に最新バージョンは 19.x となっています

そして Keycloak 17.x からは内部フレームワークが WildFly から Quarkus に変更され、構成が大きく変わりました

Migrating to Quarkus distribution

パフォーマンスの改善が期待されており、調査も兼ねてローカルでバージョンアップと関連プロジェクトの動作確認をおこないました

Quarkus 移行に伴う変更点

Docker イメージの変更

従来は jboss/keycloak を使用していましたが、Keycloak 17 以降はサポートしておらず下記のイメージを利用する必要があります

quay.io/keycloak/keycloak

また、ARM64 イメージのサポートは Keycloak 17 以降となります

従来の WildFly イメージは -legacy タグより引き続き利用できますが将来のバージョンからは廃止されます

ディレクトリの変更

元の構成では下記をカスタマイズしています

ログイン画面のカスタムテーマ (theme)
カスタムパスワードエンコーダによるパスワードの管理 (provider)
- .jar 形式でアーカイブしています

それぞれ特定の場所に格納する必要がありますが、下記のように変更されています

	WildFly	Quarkus
Theme	`/opt/jboss/keycloak/themes/`	`/opt/keycloak/themes/`
Provider	`/opt/jboss/keycloak/standalone/deployments/`	`/opt/keycloak/providers/`

Keycloak のホームディレクトリが /opt/jboss/keycloak から /opt/keycloak に変更されている他、 Provider は格納場所も変更されているため要注意です

Provider の変更

カスタムプロバイダーに関しては依存ライブラリの管理方法が変更されています

従来は META-INF/jboss-deployment-structure.xml に依存関係の定義が行えましたが、Quarkus では利用できません

Migrating custom providers

With the new distribution there is no longer a separate classpath for custom providers, so you may need to be more careful with what additional dependencies you include. In addition, the EAR packaging format, and jboss-deployment-structure.xml files, is no longer supported.

弊社のプロジェクトでは必要な依存関係を成果物に追加するため Maven Plugin を用いています

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <executions>
    <execution>
      <phase>prepare-package</phase>
      <goals>
        <goal>copy-dependencies</goal>
      </goals>
      <configuration>
        <!-- Define required plugins -->
        <includeArtifactIds>spring-security-crypto</includeArtifactIds>
      </configuration>
    </execution>
  </executions>
</plugin>

COPY ./target/*.jar ./target/dependency/*.jar /opt/keycloak/providers/

環境変数の変更

多くの環境変数が変更されています

WildFly	Quarkus
`KEYCLOAK_USER`	`KEYCLOAK_ADMIN`
`KEYCLOAK_PASSWORD`	`KEYCLOAK_PASSWORD`
`DB_VENDOR`	`KC_DB`
`DB_ADDR`	`DB_URL_HOST`
`DB_USER`	`KC_DB_USERNAME`
`DB_PASSWORD`	`KC_DB_PASSWORD`
`KEYCLOAK_IMPORT`	後述

KC_ から始まる環境変数は起動オプションのおよび .properties による設定に対応しています

URL パスの変更

デフォルトのベースパスが /auth から / に変更されています
KC_HTTP_RELATIVE_PATH=/auth と設定することで従来の仕様に戻せます

起動の変更

Quarkus から起動時に明示的に起動コマンドの指定が必要です

起動コマンドは start start-dev の2つで、それぞれ本番用・テスト用と分けられています

Realm インポートの変更

従来は KEYCLOAK_IMPORT=/xxx.json と指定することでインポートができましたが、Quarkus には該当する環境変数はありません

変わりにインポートする json ファイルを /opt/keycloak/data/import/ に配置して、起動オプションに --import-realm をつける必要があります

services:
  keycloak:
    volumes:
      # ./data に json を配置している場合
      - ./data:/opt/keycloak/data/import/
    command: start-dev --import-realm

テーマキャッシュの変更

従来は standalone-ha.xml 設定を変更することでキャッシュの設定を変更できましたが、該当ファイルが廃止されました

設定は環境変数でも行えるためキャッシュを無効化するために下記の環境変数を設定するようにしました

services:
  keycloak:
    environment:
      - KC_SPI_THEME_CACHE-THEMES=false
      - KC_SPI_THEME_CACHE-TEMPLATES=false
      - KC_SPI_THEME_STATIC-MAX-AGE=-1

その他 Keycloak アップグレードに関係する変更点

管理コンソールの UI の変更 (Keycloak 19.x)

従来と UI が大きく変わっていますができることは従来と同じです

動作確認

軽い動作確認をした範囲では認証・SDK を使ったアプリケーションからのユーザ操作等問題ありませんでした（既存ユーザ・新規ユーザ含め）

今後 Helm を用いた EKS でのアップグレードおよび動作確認を行う予定です