この記事は、ギフティ Advent Calendar 2025 1日目の記事です！
それっぽいことを書こうとしたけど思いつかなかったのは内緒です。
Keycloak のバージョンアップ時に DB マイグレーションでハマり、最小権限にしすぎて ALTER まわりの権限が足りなかったのが原因だった、という話をします。
起きた事象と解決方法
- Keycloak のバージョンアップ作業を行なった
- バージョンアップ時の DB マイグレーションでエラーになってしまい、うまくいかなかった
- ログを見ると、どうやら権限でエラーになっていそうだった
- Keycloak 用の接続ユーザーへ、権限の強化を行うことで問題を解決できた
事象の背景
- AWS 環境上で、Keycloak を共通 ID 基盤として運用している
- データストアには Aurora MySQL を採用している
- Aurora への接続には、最初は SecretsManager で管理されるマスターユーザーを使用していた
- ある時、アプリケーションユーザーを作成し、マスターユーザーの代わりにそれを使うようにした
- その後、Keycloak のバージョンアップのタイミングで今回の事象が発生した
幸い、検証用の環境での作業であったため難を逃れましたが、肝が冷えました 
最小権限への勘違い
今回の事象は、直近で行っていた設定の変更、およびその時の判断における勘違いが原因でした。
以下詳細を書いてみます。
Aurora MySQL のマスターユーザーを使わないようにした
当初この機能をコンソールで見つけたときは、キーのローテーションまで任せられて便利じゃん！とか思っていました。
アプリケーションではマスターユーザーを直接使用しないことを強くお勧めします。代わりに、アプリケーションに必要な最小の特権で作成されたデータベースユーザーを使用するというベストプラクティスに従ってください。
ただ、当然ながら上記のように「アプリケーションでマスターユーザーを直接使うな」と戒められていることに後から気がつき、権限を絞ったアプリケーションユーザーで接続するように修正を行いました。
このとき、最小権限の原則を思い出したこともあり、以下の権限を設定していました。
対象：{keycloak 用の database}.*
SELECTINSERTUPDATEDELETE
Keycloak が通常どおり稼働するにはこのあたりの権限で十分だろうと考え、実際に動作確認でも問題がなさそうだったため、そのまま安心して移行してしまいました。
Keycloak のバージョンアップ時に発生する DB マイグレーション
自分の環境では、ECS 環境で Keycloak を稼働させています。
この場合、バージョンアップに必要なのは更新後のバージョンで作成した image で更新する作業です。
新しいバージョンのサーバーがデータベースに接続した際、DB のマイグレーションが自動的に発生するようになっています。
To perform an automatic migration, start the server connected to the desired database. If the database schema has changed for the new server version, the migration starts automatically unless the database has too many records.
このマイグレーションには、テーブルやカラムの追加・変更といった DDL 操作が含まれています。更新された機能によって、テーブルの追加、カラムの追加・変更などが発生するためです。
Keycloak のバージョンアップとデータストアのアップデートを分けて考える必要がないので、ありがたい仕組みだと思います。
最小権限への見落とし
テーブルの更新作業には ALTER を実行するための権限が必要になります。
したがって、先述したようなアプリケーションユーザーでは権限が足りていません。
結果、バージョンアップが中途半端な状態でエラーになってしまい、正常に移行することができませんでした。
下記のようなログも出力されていました。
Reason: liquibase.exception.DatabaseException: ALTER command denied to user '{アプリケーションユーザー}'@'192.0.2.0' for table 'ADMIN_EVENT_ENTITY' [Failed SQL: (1142) ALTER TABLE keycloak.ADMIN_EVENT_ENTITY ADD DETAILS_JSON LONGTEXT CHARACTER SET utf8 NULL]",
アプリケーションユーザーを作成する際に、「バージョンアップ時には DDL を伴う操作がアプリケーションから実行される」という前提自体を見落としてしまっていたのが、大きな反省点です。
権限を追加して対応する
原因は明確なので、あとは不足している権限を追加すれば OK です。
ALTERの操作には、複数の権限が必要になります。
ALTER
ALTER TABLE ステートメントを使用してテーブルの構造を変更できます。 ALTER TABLE には CREATE および INSERT 権限も必要です。 テーブルの名前を変更するには、古いテーブルで ALTER および DROP を、新しいテーブルで CREATE および INSERT を実行する必要があります。
したがって、以下のように変更を行いました。
対象：{keycloak 用の database}.*
■ 変更前（アプリケーションユーザー）
SELECTINSERTUPDATEDELETE
■ 変更後（バージョンアップに備えて追加）
SELECTINSERTUPDATEDELETEALTERCREATEDROP
一応各種ステートメントについての説明も読み、権限が足りていることを確認します。
CREATE
新しいデータベースおよびテーブルを作成するステートメントの使用を有効にします。
...
DROP
既存のデータベース、テーブルおよびビューを削除するステートメントを使用可能にします。 パーティションテーブルで ALTER TABLE ... DROP PARTITION ステートメントを使用するには、DROP 権限が必要です。 DROP 権限は TRUNCATE TABLE のためにも必要です。
追加で必要そうな権限はなさそうですね 
これらを反映し、無事に Keycloak のバージョンアップも完遂できました :happy:
学びとまとめ
途中かなり困惑しましたが、最終的にはできるだけ最小限の権限にしたまま解決でき、結果として筋の良い落としどころにできたんじゃないかな？と思っています。
決め打ちで作って運用し始めている、というところもあり、このような小規模な課題は徐々に改善していくポイントかな、というところです。
大事だったかなと思っているのは下記です：
- そもそも公式ドキュメントをちゃんと把握する
- 焦って判断せず、足を止めて必要そうな権限の洗い出しを行う
- 権限が決まっても即決せず、やはり公式ドキュメントを読んで判断する
とにかく正しい情報を読んで、正しい判断を積み重ねるという当たり前の話な気もします。
引き続きやっていこうと思います 🫡