PrometheusとGrafanaによるKeycloak監視の実践ノウハウ:セッション、ログイン失敗、トークンの追跡

Monitoring tutorial - IT technology blog
Monitoring tutorial - IT technology blog

背景とKeycloakがボトルネックになりやすい理由

約6ヶ月前、私たちのチームは社内の6つのマイクロサービスのログインフローをOIDC経由でKeycloakに統合しました。その時点で1日あたりのリクエスト数は12万件に達していました。すべて順調に見えましたが、Keycloakが致命的な単一障害点(SPOF: Single Point of Failure)となってしまいました。このIdPクラスタの応答が2秒遅延したり、PostgreSQLへのコネクションプールが枯渇したりするだけで、6つのサービスすべてのユーザーがログイン画面でフリーズしてしまう事態に陥ったのです。

私たちの監視システムはPrometheusとGrafanaを使用しており、約15ノードを管理しています。以前、Keycloakにメトリクスを導入していなかった頃は、インシデントが発生するたびに原因特定が雲を掴むような状態でした。ある時はパスワード試行テストスクリプトによってCPU使用率が95%まで跳ね上がり、またある時はフロントエンドのリフレッシュトークン無限ループのバグでデータベースが過負荷に陥りました。その当時、オンコール担当者は真っ赤になったCPUグラフをただ無力に見つめることしかできませんでした。

Keycloakに適切なメトリクスを導入したことで、チームは極めて重要な3つの課題をリアルタイムに可視化できるようになりました。それが「ログイン失敗数(Login Failures)」、「実際のアクティブセッション数(Active Sessions)」、そして「トークン発行頻度(Token Operations)」です。

セットアップ

QuarkusベースのKeycloak(Keycloak 17以降)では、旧来のWildFly時代と比べてメトリクスの有効化が格段に容易になりました。KeycloakにはMicrometerが標準で組み込まれており、Prometheus標準のエンドポイントが最初から提供されています。

コンテナにいくつかの環境変数を設定するだけで動作します。以下は、私たちのチームが実際に本番環境で稼働させているdocker-compose.ymlです:

version: '3.8'
services:
  keycloak:
    image: quay.io/keycloak/keycloak:24.0.5
    container_name: keycloak-idp
    command: start --optimized
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: strongpassword123
      KC_HOSTNAME: auth.lab.internal
      KC_METRICS_ENABLED: "true"
      KC_HEALTH_ENABLED: "true"
      KC_HTTP_MANAGEMENT_PORT: 9000
    ports:
      - "8080:8080"
      - "9000:9000"
    restart: unless-stopped

注意点として、Keycloakは管理ポート(management port)をポート9000に分離しています。そのため、メトリクスエンドポイントはアプリケーションポートの8080ではなく、http://keycloak-idp:9000/metricsとなります。

この設計はセキュリティ面で非常に優れています。ポート8080はNginxやIngress経由で外部ユーザーに公開し、ポート9000はPrometheusがデータをスクレイピングするための内部アクセスのみに制限できます。

詳細な設定手順

コンテナを起動したら、curlコマンドでメトリクスエンドポイントをすばやくテストします:

curl -s http://localhost:9000/metrics | head -n 25

jvm_memory_*、agroal_*、http_server_requests_seconds_*といったプレフィックスを持つメトリクスが返ってくれば、準備は完了です。

1. Prometheusでのスクレイプジョブの設定

prometheus.ymlを開き、15秒間隔でスクレイプする設定を追加します:

scrape_configs:
  - job_name: 'keycloak'
    scrape_interval: 15s
    scrape_timeout: 10s
    metrics_path: '/metrics'
    static_configs:
      - targets: ['192.168.1.50:9000']
        labels:
          env: 'production'
          service: 'identity-provider'

プロセスを再起動することなく、即座にPrometheusの設定をリロードします:

curl -X POST http://localhost:9090/-/reload

2. 実戦で役立つ厳選PromQLクエリ

Keycloakは数百種類のメトリクスを出力しますが、本番運用の現場ではまず以下の4つのPromQLクエリをダッシュボードに固定しておけば十分です:

  • レルム別のアクティブセッション数(Active Sessions by Realm):同時にアクティブなセッション数を測定します。この数値は、Infinispanキャッシュに必要なメモリ割り当てを正確に見積もるのに役立ちます:
    sum(keycloak_active_user_sessions) by (realm)
  • ログイン失敗頻度(毎分のLogin Failures):グラフが急激に上昇して毎分30回を超えた場合、90%の確率でブルートフォース攻撃やパスワードリスト攻撃スクリプトが実行されています:
    sum(rate(keycloak_failed_login_attempts_total[5m])) by (realm, client_id) * 60
  • 新規発行およびリフレッシュトークンのレート:リフレッシュトークンを無限ループで呼び出してスレッドプールを枯渇させるクライアント側のバグを検知します:
    sum(rate(keycloak_token_exchange_total[5m])) by (realm, client_id)
  • 処理レイテンシ(P95レスポンスタイム):Keycloakの認証リクエストの処理時間を監視します。P95が1.5秒を超えた場合は、PostgreSQLのI/Oパフォーマンスを確認してください:
    histogram_quantile(0.95, sum(rate(http_server_requests_seconds_bucket{uri=~"/realms/.*"}[5m])) by (le))

実践的なモニタリングとアラート

Grafanaでは、前述の4つのPromQLを使用して独自のパネルを作成するか、テンプレートダッシュボードをインポートできます(Keycloak Quarkus向けではダッシュボードID 18635 が広く利用されています)。自手でパネルを構築することで、各メトリクス変動の意味をより深く理解できるようになります。

適切なアラートルール(Alert Rules)の構築

美しいダッシュボードがあっても、エンジニアが異変に気づかなければシステムを救えません。私たちはAlertmanager経由でTelegramやSlackに直接通知する2つのアラートルールを設定しています:

groups:
  - name: keycloak_alerts
    rules:
      - alert: KeycloakHighLoginFailures
        expr: sum(rate(keycloak_failed_login_attempts_total[5m])) by (realm) * 60 > 30
        for: 3m
        labels:
          severity: warning
        annotations:
          summary: "レルム {{ $labels.realm }} でログイン失敗の急増を検知"
          description: "3分間連続で毎分30回以上のログイン失敗が発生しています。ブルートフォース攻撃またはクレデンシャルスタッフィングの疑いがあります。"

      - alert: KeycloakSlowResponseTime
        expr: histogram_quantile(0.95, sum(rate(http_server_requests_seconds_bucket[5m])) by (le)) > 2.0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Keycloakの応答が極めて低速(P95 > 2s)"
          description: "P95レイテンシが2分間にわたり2秒に達しています。連携サービスでゲートウェイタイムアウトが発生するリスクがあります。"

半年間の運用から得た3つの教訓

夜間の本番オンコールといくつかの冷や汗をかいた障害を経て得られた、今すぐ適用すべき3つの実践的な教訓を紹介します:

  1. Session Idle時間を長く設定しすぎない:運用初期の検証段階ではSSO Session Idleを30日間に設定していました。その結果、45,000件以上の不要なセッションが蓄積し、Infinispanキャッシュが5.2GBものメモリを消費してしまいました。Idle時間を8時間、セッション上限を24時間に短縮したところ、メモリ消費量は一気に60%削減されました。
  2. ポート9000を厳重に保護する:メトリクスには設定ミスによってレルム名、クライアント名、場合によってはユーザー名が含まれる可能性があります。ufwでポート9000を遮断するか、Docker内部ネットワークで隔離し、PrometheusのIPアドレスからのみアクセスできるように制限してください。
  3. データベースのコネクションプールを注視する:ユーザー数に急増が見られないにもかかわらずP95レイテンシが悪化している場合は、直ちにメトリクスagroal_active_countを確認してください。私たちのシステムでは、KC_DB_POOL_MAX_SIZEを20から60に引き上げることで、朝9時のピーク時に発生していたボトルネックを根本解決できました。

PrometheusとGrafanaを活用することで、Keycloakの運用負荷は劇的に軽減されます。Slackでユーザーから障害の連絡が届くのを待つのではなく、運用チームが予兆をいち早く捉え、問題が拡大する前に迅速に対処できるようになります。

Share: