Keycloak の利用者に関するイベントを email で通知する

この記事はギフティ Advent Calendar 2025の 6 日目の記事です。（ｲｪｲｲｪｲ）

この記事では Keycloak Version 26.1.5を前提としています

メールでイベントを通知する機能があるらしい

巷の ID 管理基盤を利用していると、久しぶりにログインしたタイミングなどで通知のメールが送られてくることがあります。

この通知は利用者にとって、そのアカウントのいわば"健康状態"を確認する手段になります。
ゆくゆくは自分の管理している Keycloak でもできたほうがいいんだろうな、とふと思い立ったのがこの記事の出発点です。

調べてみて初めて知ったのですが、どうやら Keycloak には Email Event Listener という機能があるようです。

この機能を使うと、利用者についてのイベントが発生したタイミングで通知を行えるのでは？と思ったので早速機能を確認してみます。

設定してみる

どうやって設定するのか

設定方法はシンプルで、realm の設定のうち、Events で Event listeners として email を追加するだけです。

ドキュメントを踏まえると、下記の条件を満たしていれば User について、特定のイベントが発生するたびに email で通知が送られるようになるようです

• realm の設定として、email の設定が完了している
• User には email が登録済みである
• User の email は verify 済みである

イベントの通知を見てみる

ローカル環境の Keycloak にて、Mailhog を用いて送信されるメールを確認してみます。

パスワードの更新時のメールが下記のように届きました。

デフォルトだと、時刻と IP アドレスを文面に入れて、注意を促してくれるようです。
これはこれであると嬉しい機能な印象です。いいですね。

なんかパスワード更新の通知が2個飛んでくるんだけど・・・w

改めてドキュメントを見直すと、原因がわかりました。

パスワードも、User に紐づく credential です。
したがって、通知対象の二つのイベントが発生し、それぞれでメールが送られてしまっているようです。

• Update Password.
• Update Credential.

Update Credential の方のメールが日本語になっていないのは、テーマで上書きしている messages_ja.properties にプロパティが存在しないためだと思われます。
色々と合点がいきました。

特定のイベントについて通知対象から外すこともできるようなので、Update Credential. に揃えてしまっていい気もしますね

通知されるイベントの種類はカスタマイズできなさそう？

• ドキュメント上にカスタマイズできるような文面がなかった
• イベントリスナー固有の設定を行う UI が管理画面上に存在しない

これらのことから、不可能っぽい雰囲気があります。
やるなら実際の実装を参照して、独自に拡張機能を実装するイメージになるでしょうか。

email の文面を切り替えるには？

送信される email のテンプレートはこのあたりに参考になりそうなデフォルトのテーマがありそうです。

• text : https://github.com/keycloak/keycloak/tree/985777ebcc26f0c2e27a9ae3b6cf19a9fe398abc/themes/src/main/resources/theme/base/email/text
• html : https://github.com/keycloak/keycloak/tree/985777ebcc26f0c2e27a9ae3b6cf19a9fe398abc/themes/src/main/resources/theme/base/email/html

例えばパスワード更新の text のメールについては https://github.com/keycloak/keycloak/blob/985777ebcc26f0c2e27a9ae3b6cf19a9fe398abc/themes/src/main/resources/theme/base/email/text/event-update_password.ftl を上書きすれば自由な文面に変更できそう。

したがって、おそらく event-{イベント名 lowercase}.ftl を読み込んで動いているようですね。

メール通知が発生するイベントは、ドキュメントによると下記の通りです。

• Login Error.
• Update Password.
• Update Time-based One-time Password (TOTP).
• Remove One-time Password (OTP).
• Update Credential.
• Remove Credential.

それぞれに合わせたファイルを上書きしてあげれば、狙った文面で通知を送ることはできそうですね。

Email Event Listener 機能のまとめ

以上のことを踏まえると、こんな感じのまとめになりそうです。

• 特定のイベントに対して、自動的に email が送信される機構が Keycloak には組み込まれている
• 特定のイベント以外について通知を送ることはできない
• 通知の文面は、他の契機による email と同様、対応するテーマを変更すれば上書きができる

大きな課題は二点目ですね。
ログインされたよ！通知くらいはできると嬉しいです。できてほしい。

自分自身のアカウントについて強い思いを持っている人ほど、安心感を得られるように設計することが ID 基盤に求められることだと感じています。
そのための方策として有効な手なので、どうにかならないのか探ってみたいところです

というわけで、実現してみました

注意：実装まで遡ってやれてしまったハックなので、あんまりたしからしさはないです。本番適用するかもやや不安なので、もう少し調べるつもりです。

本当にそんな中途半端なことある？と思ったので、実装まで遡って調べてみました。

メール送信処理の確認

EmailEventListenerProvider をみてみます。

この class の実装を読んでいくと、includedEvents にマッチするイベントが発生したらメール送信が行われる、という仕組みなようです。
したがって、includedEvents を設定や引数で上書きできないかを調べればよさそうです。

対応しているイベントの調査

EmailEventListenerProvider 上の includedEvents は、コンストラクタで渡されています。
EmailEventListenerProvider のインスタンス化の責務は Factory にあるはずです。
したがって、EmailEventListenerProviderFactory を確認します。

この辺りを読むと、どうやら include-events という config で上書きできそう・・・？

ドキュメントを読み返すと、exclude-events についての記述が存在していました。

You can exclude events by using the --spi-events-listener-email-exclude-events argument. For example:

つまり同様に、 --spi-events-listener-email-include-events によって　include-events　を設定できそうな気がします

やってみました

• 通知させる対象のイベントは LOGIN （シンプルなので）とします
• 動作を調べた時に判明した通り、対応するテーマが必要になります。event-login.ftl として追加してみます
• 起動時に --spi-events-listener-email-include-events=LOGIN としてみます

動作の確認さえできれば良いので、雑に「ログインされました」という通知を送ってみます。

keycloak/themes/{my-theme}/email/html/event-login.ftl

<#import "template.ftl" as layout>
<@layout.emailLayout>
<p>ログインされました</p>  
</@layout.emailLayout>

keycloak/themes/{my-theme}/email/text/event-login.ftl

<#ftl output_format="plainText">
ログインされました

起動後、ログインを試してみたのち、メールの通知を確認します（ドキドキ）

で、できましたね！？

どうやら仕組みの理解としても間違いがなかったのか、これでうまく動作できるようです。

このまま使用して副作用がないか、の確認は必要そうですが、思っていた以上に可能性がありそうな機能ですね

むすび

今回は Email Event Listener という機能を紹介しました。

有効化が容易であり、通知内容についても従来のテーマと同様にカスタマイズができます。
通知対象のイベントも（おそらく）カスタマイズできそうなことがわかりました。

アカウントの管理という文脈の機能は、今後大事になってくる分野だと思っています。
無駄に深入りした気もしますが、ワンステップとして有用なことを知ることができてよかったかなと思います。

それでは〜ノシ