FAPI対応 — 金融グレードAPIのためのKeycloak設定

オープンバンキングや金融連携の要件として登場するFAPI(Financial-grade API)。KeycloakはFAPI 1.0 Advanced/JARM/CIBAで認証取得済みで、FAPI 2.0のconformanceも通過しています。本記事ではclient policies/profilesを軸に、PAR・JARM・mTLS・private_key_jwt・DPoPを実際にどう組むかを整理します。

01FAPIとは何か — 要件の位置づけ

FAPI(Financial-grade API)は、OpenID FoundationがOAuth 2.0/OpenID Connectの上に定義した高セキュリティのプロファイル群です。オープンバンキング(英国、ブラジル、オーストラリアCDR等)や金融API連携で「準拠必須」として指定されることが増えています。素のOIDCが許容する緩い選択肢を締め、攻撃面を体系的に潰すのが狙いです。

大きく2系統あります。FAPI 1.0はBaseline(Part 1)とAdvanced(Part 2)からなり、Advancedは署名付きリクエスト、送信者制約トークン(sender-constrained token)、強い認証方式を要求します。FAPI 2.0はSecurity Profileとして再設計され、PARを必須化しつつ全体をシンプルにした、いわば「実装しやすく守りやすい」後継です。KeycloakはFAPI 1.0 Advanced FinalおよびJARM・CIBAでOpenID Foundationの認証を取得済みで、FAPI 2.0系はconformance test suiteを通過しています(Specifications implemented)。

現場のコツ：「FAPI対応」と一言で言われても、1.0 Advancedか2.0か、mTLS系かprivate_key_jwt系か、JARMやCIBAを含むかで設定が大きく変わります。RFPや接続仕様書のどのマトリクスを満たすのかを、最初にクライアント側と合意しておくと手戻りが激減します。

02Keycloakの武器 — client policies と profiles

Keycloakでは、個々のクライアント設定を手作業で厳格化するのではなく、Client Policiesという宣言的な仕組みでポリシーを強制します。中核となるのは以下の2概念です。

Client Profile：「PKCE S256を強制」「PARを必須」「署名アルゴリズムをPS256/ES256に限定」といった個々のルール(executor)の束。KeycloakはFAPI用のグローバルプロファイルを各realmに標準搭載しています。
Client Policy：どのクライアント(条件)に、どのプロファイルを適用するかを結びつけるルール。「client-roles に fapi を持つクライアントには fapi-1-advanced を適用」のように条件で束ねます。

標準で用意されているFAPI関連のグローバルプロファイルは次の通りです(Securing applications with OpenID Connect)。

fapi-1-baseline / fapi-1-advanced — FAPI 1.0のBaseline/Advanced
fapi-ciba — CIBA固有のexecutor群(単独では不足、後述)
fapi-2-security-profile / fapi-2-message-signing — FAPI 2.0(mTLS/private_key_jwt系)
fapi-2-dpop-security-profile / fapi-2-dpop-message-signing — FAPI 2.0でDPoPを使う場合

ポイントは、これらを「クライアント個別のトグルの寄せ集め」ではなく、realmレベルのポリシーとして一元適用できることです。監査でも「このrealmのFAPIクライアントは全てこのプロファイルで縛っている」と一枚で示せます。

現場のコツ：プロファイルとポリシーはRealm設定のJSONにそのまま出ます。Admin UIでポチポチ作るのではなく、マルチアカウント統制と同様にIaC(Terraform provider や kcadm、Admin REST API)でコード管理し、環境間で差異が出ないようにするのが本番運用の定石です。

03FAPI 1.0 Advanced をKeycloakで満たす

FAPI 1.0 Advancedが要求する主要素は、Keycloakのexecutorにほぼ一対一で対応します。fapi-1-advancedプロファイルを適用すると、代表的には次が強制されます。

クライアント認証：mTLS(tls_client_auth)または private_key_jwt(private-key-jwt)のみ許容。client_secret系は拒否。
送信者制約トークン：mTLSによる証明書バウンドのアクセストークン(RFC 8705, holder-of-key)。トークンを盗んでも別クライアント証明書では使えません。
署名アルゴリズム：PS256 または ES256。RS256やHS256は不可。
リクエストの完全性：署名付きのrequest object、および認可レスポンスの改ざん防止(後述のJARM)。
PKCE：pkce-enforcer executor によりS256を強制。特にPAR利用時に効いてきます。

クライアント認証方式は、接続先の金融機関仕様がmTLS前提かprivate_key_jwt前提かで分かれます。両者はトレードオフがあり、mTLSはTLS終端(ロードバランサ/リバースプロキシ)でクライアント証明書をどう受け渡すかが設計上の勘所です。Keycloak(Quarkus版が現行)では、フロント側でmTLSを終端して証明書情報をヘッダで渡す構成が一般的で、--https-client-auth や証明書ヘッダの取り扱いをインフラ側と合わせ込む必要があります。バージョン依存が強い領域なので、稼働バージョンの公式ドキュメントで最終確認してください。

図：FAPI 1.0 Advancedの主要4ステップとKeycloakでの対応(PAR→認可→JARM→証明書バウンドトークン)。

04PAR(Pushed Authorization Requests)

PAR(RFC 9126)は、認可リクエストのパラメータをブラウザのリダイレクトURLに載せず、事前にバックチャネルでKeycloakへpushし、返ってきたrequest_uriだけをフロントで使う仕組みです。これにより、認可URLの改ざん・パラメータ注入・URL長制限といった問題を根本から回避できます。FAPI 1.0 AdvancedではPARの利用が実質的に前提、FAPI 2.0ではPARが必須です。

Keycloakは、PARエンドポイントのURLをメタデータ名 pushed_authorization_request_endpoint(RFC 9126 §5)としてwell-knownに公開します。クライアントはclient_credentials相当の認証を伴ってrequest objectをpushします。
PAR利用時はPKCE S256が特に重要になるため、pkce-enforcerが効くようfapi-1-baselineとfapi-1-advancedを併用する構成が推奨されます。
クライアント設定で「PARを必須(require pushed authorization requests)」を有効にすると、通常の認可エンドポイント直叩きを拒否できます。

PARは仕様としては小さいですが、request objectの署名(PS256/ES256)、鍵の登録(JWKSまたはjwks_uri)、mTLS/PKJWTによるPARエンドポイントへのクライアント認証が絡むため、認可コードフロー(OIDCグラントタイプ参照)の理解が前提になります。

05JARM — 認可レスポンスの署名

JARM(JWT Secured Authorization Response Mode)は、認可エンドポイントからのレスポンスをJWTで署名して返すモードです。標準のOAuthではcode等が素のクエリパラメータで返るため、注入攻撃(authorization code injection)や改ざんの余地があります。JARMはresponse_mode=jwt(またはquery.jwt/fragment.jwt)でレスポンス全体を署名付きJWTにまとめ、クライアントが署名検証することで、発行元と完全性を保証します。

KeycroakはJARMをFAPI認証の一部としてサポートしており、単体でのconformanceも取得済みです。
FAPI 1.0 Advancedでは、署名付きrequest object(入口)とJARM(出口)を両端で締めることで、認可フロー全体の完全性を担保します。
クライアント側の署名アルゴリズムはPS256/ES256に揃えます。RS256を選びがちですが、FAPIプロファイル下では拒否される点に注意してください。

現場のコツ：JARMとPARは役割が対称です。PARが「入口(リクエスト)の保護」、JARMが「出口(レスポンス)の保護」。接続先仕様がどちらを要求しているか(片方だけのこともある)を仕様書で確認し、必要な側だけを有効にすると、クライアント実装側の負担を過剰に増やさずに済みます。

06クライアント認証：mTLS と private_key_jwt

FAPIではclient_secret(共有シークレット)による認証は許されず、公開鍵ベースの2方式に限られます。

mTLS(tls_client_auth / RFC 8705)：クライアント証明書でTLS相互認証を行い、同時にアクセストークンをその証明書に紐づけます(certificate-bound / holder-of-key)。トークンが漏れても、対応する秘密鍵を持たない相手はAPIを叩けません。インフラ側の証明書配布・失効管理・TLS終端設計が主な検討点です。
private_key_jwt(private-key-jwt / RFC 7523)：クライアントが自身の秘密鍵で署名したJWTをclient_assertionとして提示します。TLS終端の制約を受けにくい一方、トークン自体はデフォルトでは証明書バウンドにならないため、FAPI 2.0ではDPoPと組み合わせて送信者制約を実現するのが一般的です。

どちらもクライアント側の公開鍵(JWKSのインライン登録またはjwks_uri)をKeycloakに登録し、鍵ローテーションの運用を決めておく必要があります。鍵管理は「作って終わり」ではなく、失効・更新のプロセス込みで設計するのが金融グレードの前提です。

07FAPI 2.0 と DPoP

FAPI 2.0 Security Profileは、FAPI 1.0 Advancedの複雑さを整理し、PARを必須にしつつ選択肢を絞った後継です。KeycloakはFAPI 2.0 Security ProfileとMessage Signingのconformance testを通過しており、対応するグローバルプロファイル(fapi-2-security-profile、fapi-2-message-signing、およびDPoP版)を備えています。

FAPI 2.0では送信者制約トークンが必須で、その手段としてmTLSに加えてDPoP(RFC 9449)が使えます。DPoPは、クライアントが保持する鍵で署名したproof JWTをリクエストごとに付与し、トークンをその鍵に紐づける方式です。mTLSのようなTLS層の相互認証を必要とせず、アプリケーション層で送信者制約を実現できるため、TLS終端の自由度が高い構成で有利です。

Keycloak 26系ではDPoPがpreviewから正式サポートに昇格し、bearerトークンで保護される全エンドポイントがDPoPトークンを扱えるようになりました(Keycloak 26.4.0 released)。
publicクライアントについて、リフレッシュトークンのみをDPoPバウンドにしてアクセストークンのバインドは省く、といった細かな制御も可能です。
DPoPでFAPI 2.0を目指す場合は、fapi-2-dpop-security-profile(必要に応じてfapi-2-dpop-message-signing)を適用します。バージョンによりconformanceの対象組み合わせ(MTLS+DPoP、private_key_jwt+DPoP等)が拡張されてきているため、稼働バージョンのリリースノートで最終確認してください。

現場のコツ：新規に金融API連携を組むなら、接続先が許すならFAPI 2.0を第一候補にする価値があります。1.0 Advancedより設定・実装の分岐が少なく、DPoPを使えばmTLS終端の作り込みを避けられるためです。ただし接続先(銀行・アグリゲータ)がFAPI 1.0 Advanced固定を指定するケースはまだ多く、そこは相手仕様に従います。

08導入の進め方 — 実務チェックリスト

KeycloakでFAPI準拠を実装する際の、現場での進め方を整理します。

要件確定：接続先の仕様書で「FAPIバージョン/クライアント認証方式/PAR・JARM・CIBAの要否/許容署名アルゴリズム」を特定する。ここが曖昧なまま進めると必ず後戻りします。
プロファイル選定：1.0系ならfapi-1-baseline+fapi-1-advanced(CIBA併用時はfapi-cibaも追加、単独では不足)。2.0系ならfapi-2-security-profile系、DPoPならfapi-2-dpop-*。
ポリシー適用：Client Policyの条件でFAPIクライアントだけに適用。全クライアントを一律FAPI化しない(社内向けの緩いクライアントまで巻き込まない)こと。
鍵とmTLSの運用設計：JWKS/jwks_uri登録、証明書配布・失効、TLS終端でのクライアント証明書受け渡し。インフラ担当との合わせ込みが最大の山場です。
IaC化と検証：Realm設定をコード管理し、OpenID FoundationのFAPI conformance test suiteでクライアント実装込みの疎通を確認する。

認証フローそのものの設計は認証フロー設計、多要素の引き上げはステップアップ認証もあわせて検討すると、FAPIの「強い認証」要件を実装に落とし込みやすくなります。EMWではKeycloakによるエンタープライズ認証基盤の実構築実績があり、要件整理から本番運用設計まで一気通貫でご支援できます(導入事例)。

—まとめ

KeycloakのFAPI対応は、client policies/profilesという宣言的な仕組みに集約されているのが強みです。PAR(入口)・JARM(出口)・mTLS/private_key_jwt(クライアント認証)・DPoP(送信者制約)という部品を、接続先仕様に合わせてプロファイルで束ね、ポリシーで対象クライアントだけに強制する。この形にできれば、監査対応も環境間の一貫性も担保しやすくなります。FAPI 1.0 Advancedは認証取得済み、FAPI 2.0系もconformance通過済みという実績あるベースの上に、自社の接続要件を正確に写し取る作業が本質です。

—参考(一次情報)

FAPI準拠の認証基盤をKeycloakで設計・構築する具体案件は、お問い合わせください。実装実績をもとに要件整理からご支援します。

相談する

← ブログ一覧へ戻る