はじめに
本記事は、あくまで執筆者の個人的な見解であり、日立製作所の公式ドキュメントではありません。
2025年10月に PostgreSQL 18 がリリースされ、データベースが OAuth 2.0 アクセストークンによる接続を正式にサポートしました。新しい接続方式が選べるようになったことで、アーキテクチャ設計の幅が広がることを期待している方も多いのではないでしょうか。
まずは PostgreSQL 18 がサポートした OAuth ベースの接続方式がどのように動くのか、その仕組みを説明します。そのうえで、OAuth 2.0の認可サーバとして動作可能な Keycloak と連携して実際にこの機能を試してみましょう。
この記事の内容は、筆者が KubeCon NA 2025 で登壇したセッションでも紹介しています：
https://sched.co/27FXv
また、すぐに試せるアセットを GitHub で公開しています：
https://github.com/Hitachi/oss-assets/tree/main/sessions/2025/kubecon-na/securing-ai-agent-infra-authn-authz-mcp-a2a
PostgreSQL 18 がサポートした「OAuth 2.0 アクセストークンによる接続」とは
PostgreSQL 18 では、外部の IdP が発行する OAuth 2.0 アクセストークンをデータベース接続時に利用できる仕組み が追加されました。
アクセストークンに含まれる claims をもとに、どのロールを適用するかを判断することで、データベース内のアクセス制御に反映します。
ポイントは次のとおりです：
- PostgreSQL は接続時にアクセストークンを受け取り、内部の Validator を通じて内容を検証する
- トークン内の claims から、接続ユーザーに適用すべき ロール（権限） を決定する
この仕組みによって、アプリケーション側でDBアカウントやパスワードを個別に管理する必要が減り、外部IdPのアクセス制御モデルをより自然に取り込めるようになりました。
PostgreSQL における OAuth アクセストークン利用の流れ
アクセストークンを使ってセッションが確立される流れは次のとおりです：
- クライアントがアクセストークンを取得する
- クライアントがアクセストークンを PostgreSQL に提示して接続を試みる
- PostgreSQL が Validator を呼び出してトークンを検証する
- トークン署名の検証（JWKS）
- claims の抽出
- claims に基づいたロール判定
- ロールが決定し、セッションが確立される
- 以降、セッション中は決定されたロールの権限が適用される
ロールマッピングの仕組み
claims と DB ロールを結び付ける方法は2つあります。
- pg_ident.conf：claims の値を静的にロールへ紐づける
- delegate_ident_mapping=1：ロール決定処理を Validator 側へ委譲する
後者を利用すると、IdP 側で設定したロール体系をそのまま取り込むような柔軟な構成が可能です。
Validator とは何か
PostgreSQL 本体はアクセストークンの構造や署名検証のロジックを持っていません。そのため、Validator（検証モジュール） がトークンの検証とロール決定を担当します。
Validator の役割：
- トークン署名の検証
- claims の抽出
- claims → ロール の判定
- 不正トークンの拒否
Validator を切り替えることで、連携する IdPを柔軟に選べる設計になっています。
Keycloak 用 Validator を使って試してみる
CloudNativePG プロジェクトでは、Keycloak 用の公式 Validator PostgreSQL OAuth Validator for Keycloak が提供されています：
https://github.com/cloudnative-pg/postgres-keycloak-oauth-validator
筆者はこのコンポーネントのコンポーネントオーナーに就任いたしました。設定方法や利用方法はリポジトリの README にまとめられていますので、そちらをご参照ください。
psql で簡単に動作確認する
OAuth では認可コードフローが一般的ですが、まずは psql で手軽に動作を試したいという場合、CLI と相性の良い デバイスフロー が便利です。
デバイスフローの概要
デバイスフローとは、RFC 8628で定義されたOAuth 2.0 Device Authorization Grantの通称です。
以下のような認可フローとなり、CLIなど入力制限のあるツールがOAuthクライアントとしてふるまう際に適した認可フローです。
Keycloakでは、クライアントの設定でOAuth 2.0 Device Authorization Grantを有効にすることでデバイスフローを利用することができます。
また、PostgreSQL OAuth Validator for Keycloakでは、Keycloakの認可サービスを用いてデータベース接続の認可判断をしています。
認可サービスの設定方法については公式ドキュメントを参照ください。
適宜冒頭で紹介したセッション動画やGitHubアセットも参照しながら設定を進めるとよいでしょう。
利用イメージ
実際に動作を確認してみましょう。まずは以下のようなコマンドでPostgreSQLへの接続を試みます。適宜自身の環境の値に置き換えて実行してください。
$ psql "host=DB_HOST user=app_readonly dbname=appdb oauth_issuer=https://keycloak.example.com:8443/realms/demo oauth_client_id=appA oauth_client_secret=CLIENT_SECRET oauth_scope='db_access'"
すると、以下のようなレスポンスが表示されます。左のURLがverification_uriで、右のコードがdevice_codeです。
Visit https://keycloak.example.com:8443/realms/demo/device and exter the code: EZUK-ZFGH
verification_uriにブラウザでアクセスすると、device_code入力画面が表示されるので、device_codeを入力して送信します。
ログイン画面が表示されるので、適当なユーザでログインします。
同意画面が表示されるので、同意します。
ログイン成功画面が表示されるので、CLIに戻ってみましょう。
すると、以下のように表示され、PostgreSQLの指定したデータベースに接続できることが確認できました。
appdb=>
まとめ
PostgreSQL 18 の OAuth 2.0 アクセストークン対応により、データベースアクセスの新しい形が生まれました。アクセストークンの claims を用いてロールを割り当てる仕組みは、外部 IdP のポリシーをデータベースへ取り込む柔軟なアプローチとなります。
Keycloak を利用している方は、CloudNativePG の公式 Validator を用いることで簡単に動作確認できます。公開されている GitHub アセットも活用し、ぜひこの新しい接続方式を体験してみてください。