FAPI (Financial-Grade API) Compliance in Keycloak
A zero-prior-knowledge guide to the strictest, most demanding security profile in the OAuth world — built for banks and regulators — and how Keycloak lets an application switch into this heightened mode with a single configured policy.
Most websites you log into are protected by security good enough for the job at hand — a forum, a newsletter subscription, a shopping cart. But some systems move real money between banks, or expose a person’s complete financial history to a third-party application they have never directly interacted with before. For situations like these, “good enough” security is not good enough at all. This is exactly the gap the Financial-Grade API security profile, universally known as FAPI, was built to close, and Keycloak provides direct, built-in support for meeting it. This article explains, from first principles, what FAPI actually demands, why each of its stricter rules exists, and how Keycloak lets an application step into this heightened level of security through configuration rather than custom engineering.
Foundations
Core Concepts
Before diving into FAPI’s specific rules, it helps to understand what problem it exists to solve, and why ordinary OAuth and OpenID Connect, while already solid, were not considered strict enough on their own for the highest-stakes scenarios.
What is FAPI?
FAPI is a security profile — a formally defined, stricter set of additional rules layered on top of OAuth 2.0 and OpenID Connect — published by the OpenID Foundation specifically for APIs that handle extremely sensitive data or high-value transactions, most famously in banking and open finance. Rather than inventing an entirely new protocol, FAPI takes the existing, well-understood OAuth and OIDC foundation and closes off specific weaknesses or ambiguities that are acceptable for an ordinary application but unacceptable for a financial one.
Why ordinary OAuth needed tightening for this use case
OAuth 2.0 was deliberately designed to be flexible, supporting many different kinds of applications with many different risk profiles, which means it leaves several important security decisions optional or configurable rather than mandatory. A photo-sharing app skipping an optional protection might be a minor risk; a banking API skipping that same optional protection could enable real financial fraud. FAPI exists to take those optional protections and make them mandatory, specifically for this class of high-stakes application.
Think of general building safety codes versus the far stricter codes that apply specifically to hospitals or nuclear facilities. Both are built on the same underlying engineering principles, but a hospital’s code makes mandatory many things that an ordinary office building code leaves optional or simply does not address at all, precisely because the consequences of a failure are so much more severe. FAPI is the hospital-grade building code for OAuth-based logins and API access.
The two major generations: FAPI 1.0 and FAPI 2.0
FAPI has evolved through more than one version. FAPI 1.0 introduced two levels — a Baseline profile and a stricter Advanced profile — and became the foundation for numerous real-world regulatory mandates, including several national open banking initiatives. FAPI 2.0 represents a more recent, further-refined security profile, simplifying and consolidating some of FAPI 1.0’s requirements while incorporating newer, additional security mechanisms developed since the original profile was published.
OAuth 2.0 / OIDC
The general-purpose standard, flexible enough for a huge range of applications with varying risk levels.
FAPI
A stricter profile making previously optional protections mandatory, specifically for high-stakes financial and sensitive-data APIs.
FAPI 1.0 (Baseline / Advanced)
The original profile, widely adopted as the backbone of real open banking regulatory mandates around the world.
FAPI 2.0
A refined, consolidated successor profile incorporating newer security mechanisms and simplifications.
Structure
Architecture & Components
FAPI compliance is not a single setting — it is a bundle of specific, individually meaningful requirements, each closing off a particular category of risk.
Pushed Authorization Requests (PAR)
FAPI requires that the initial authorization request be sent directly, server-to-server, from the client to Keycloak’s own dedicated endpoint, rather than being passed through the user’s browser as part of a visible URL. This is called a Pushed Authorization Request, and it prevents the sensitive parameters of that request from being exposed to browser history, referrer headers, or tampering along the way.
Request Object signing (JAR)
Rather than sending individual authorization parameters as plain, separate values, FAPI requires them to be bundled together into a single, digitally signed Request Object, following the JWT-Secured Authorization Request specification, commonly abbreviated JAR. This ensures the entire set of request parameters is tamper-evident as a whole, rather than each parameter being independently exposed and potentially alterable.
Strong client authentication: mTLS or private_key_jwt
FAPI explicitly disallows the simplest, weakest form of client authentication — a shared client secret sent as a simple credential — in favor of stronger methods: either Mutual TLS client authentication, discussed elsewhere as its own dedicated topic, or an alternative method called private_key_jwt, where the client proves its identity by presenting a self-signed, cryptographically verifiable token rather than a plain, reusable secret value.
Sender-constrained tokens
FAPI’s more advanced requirements mandate that access tokens themselves be sender-constrained — cryptographically bound to the specific client that obtained them, using either Mutual TLS certificate binding or a mechanism called DPoP (Demonstrating Proof of Possession). This ensures that even a stolen access token cannot be successfully reused by anyone other than the original, legitimate client.
JARM: signed and encrypted authorization responses
Just as the request itself is signed and protected, FAPI requires the authorization server’s response — confirming the outcome of the login and authorization process — to also be returned as a signed, and optionally encrypted, JWT, through a mechanism called JARM (JWT Secured Authorization Response Mode), rather than as plain, unsigned query parameters that could more easily be tampered with in transit.
flowchart TD
A["Client Application"] --> B["Signed Request Object (JAR) sent via Pushed Authorization Request (PAR)"]
B --> C["Keycloak validates signature and stores request"]
C --> D["User authenticates and authorizes"]
D --> E["Signed Authorization Response (JARM)"]
E --> F["Client exchanges code using strong Client Authentication: mTLS or private_key_jwt"]
F --> G["Sender-Constrained Access Token issued: mTLS-bound or DPoP-bound"]
G --> H["Resource Server verifies token binding on every request"]
Fig 1 — How FAPI’s individual requirements stack together across a single, complete login and token issuance flow.
Every one of these components addresses a specific, real weakness that exists somewhere in ordinary, less strict OAuth deployments. FAPI’s real contribution is not inventing new cryptography, but rather bundling these already-existing tools together into one mandatory, coherent, well-tested package specifically for the highest-stakes use cases.
This chapter looks at how Keycloak actually enforces these many individual FAPI requirements together, as a single, coherent configuration.
Client Policies as the enforcement mechanism
Keycloak implements FAPI compliance through its Client Policies feature — a general-purpose mechanism for defining conditions and required behaviors that apply to specific clients. Rather than requiring an administrator to individually configure every single FAPI requirement by hand across dozens of separate settings, Keycloak provides pre-built client policy profiles specifically corresponding to the FAPI 1.0 Baseline, FAPI 1.0 Advanced, and FAPI 2.0 security profiles.
What applying a FAPI client policy actually does
When a client is placed under one of these FAPI client policy profiles, Keycloak begins enforcing the full bundle of requirements that profile demands — rejecting authorization requests that are not properly pushed and signed, refusing weak client authentication methods, requiring sender-constrained tokens, and validating every other rule the specific profile mandates — automatically, as part of normal request processing, without needing each individual rule to be separately configured and verified by hand.
Think of a restaurant kitchen that can operate under either a standard local health code, or, when preparing food specifically for a hospital’s patients, a much stricter medical-facility food-safety code. Rather than a chef individually remembering and manually checking every single one of dozens of extra rules for that stricter code, the kitchen simply switches into “hospital mode,” and every relevant extra safeguard — stricter temperature checks, tighter handling procedures — is automatically expected and enforced as a bundled whole. A FAPI client policy is Keycloak’s version of switching a specific client into that stricter mode.
Distinguishing between the profile levels
FAPI 1.0 Baseline enforces a solid, meaningfully strengthened set of requirements suitable for many read-oriented, lower-risk financial API scenarios. FAPI 1.0 Advanced adds further, stricter requirements — including mandatory sender-constrained tokens and signed request objects — appropriate for higher-risk scenarios, such as APIs that can actually initiate a financial transaction rather than merely read account information. FAPI 2.0 further refines and, in some respects, simplifies this model while incorporating newer mechanisms like DPoP more centrally.
Validation happens at each relevant step of the flow
Rather than a single, one-time check at the very start, Keycloak’s FAPI enforcement validates compliance at each relevant step along the way — checking that the authorization request itself meets the profile’s requirements, checking that the client authenticates using an approved strong method during token exchange, and checking that the resulting tokens are correctly sender-constrained, ensuring the entire flow, start to finish, genuinely meets the chosen profile’s standard rather than only its initial step.
Lifecycle
Data Flow & Lifecycle
Following a single, complete login attempt under a FAPI Advanced client policy shows exactly how each requirement fits into the real sequence of events.
The client prepares a signed request object
A banking application, needing to initiate a payment authorization, assembles its authorization request parameters into a signed JWT, following the Request Object requirement.
The request is pushed directly to Keycloak
Rather than redirecting the user’s browser with these parameters visible in a URL, the application sends this signed request object directly, server-to-server, to Keycloak’s Pushed Authorization Request endpoint.
Keycloak validates the request and only then redirects the user
Keycloak checks the request object’s signature and validity, and only after confirming it meets the FAPI Advanced profile’s requirements does it proceed to authenticate the actual banking customer.
The customer authenticates and authorizes the payment
The customer logs in, likely including a strong second factor given the sensitivity of the action, and explicitly consents to the specific payment being authorized.
A signed authorization response is returned
Keycloak returns the outcome as a signed JARM response, rather than plain, unsigned parameters, protecting the integrity of this critical confirmation on its way back to the application.
The client authenticates strongly to exchange the code
When exchanging the authorization code for tokens, the client proves its own identity using Mutual TLS or private_key_jwt, since a plain shared secret is not permitted under this profile.
A sender-constrained access token is issued
The resulting access token is cryptographically bound to this specific client, meaning that even if it were somehow intercepted, it could not be successfully reused by anyone else to complete or repeat the payment.
Weighing the Choice
Advantages, Disadvantages & Trade-offs
Adopting FAPI compliance is a significant commitment, and it is worth being clear-eyed about exactly what it buys, and what it costs, compared to a standard OAuth deployment.
Advantages
- Closes off a well-documented, comprehensive set of real weaknesses that a standard, less strict OAuth deployment could otherwise leave open
- Provides a globally recognized, standardized benchmark that regulators, auditors, and partner organizations already understand and trust
- Sender-constrained tokens and signed requests together neutralize entire categories of token theft and request tampering attacks
- Keycloak’s built-in client policy profiles make adopting the full bundle of requirements dramatically simpler than implementing each rule manually from scratch
Disadvantages & Trade-offs
- Requires genuinely more infrastructure and operational discipline — certificate management for mTLS, or key management for private_key_jwt and signed requests
- Adds real complexity and additional round trips to the login flow compared to a simpler, standard OAuth setup
- Client applications integrating with a FAPI-compliant Keycloak deployment must themselves correctly implement the corresponding stricter requirements, which is a real engineering investment on their side as well
- Not every application genuinely needs this level of strictness, and applying it unnecessarily adds cost and complexity without a corresponding security benefit for lower-risk use cases
Recognizing when FAPI is the right call
FAPI compliance earns its considerable complexity specifically for applications handling genuinely high-stakes financial data or transactions, particularly where regulatory frameworks explicitly require it. For the broad majority of ordinary applications, standard, well-implemented OAuth and OpenID Connect, without the full FAPI bundle, remain an entirely appropriate and proportionate choice.
Defense
Security
FAPI is, at its core, entirely a security specification, but achieving genuine compliance requires more than simply flipping a configuration switch.
Configuration alone is necessary, but not sufficient
Applying a FAPI client policy in Keycloak correctly configures the authorization server’s side of the relationship, but the connecting client application itself must also correctly implement its own half of the requirements — properly signing request objects, correctly handling sender-constrained tokens, managing its own certificates or signing keys appropriately. A misconfigured or poorly implemented client can still introduce real vulnerabilities even when the authorization server side is fully FAPI-compliant.
It is tempting to assume that simply enabling a FAPI client policy in Keycloak automatically makes an entire integration “FAPI compliant” end to end. In reality, FAPI compliance is a property of the whole system — both the authorization server and every connecting client application — and a genuinely secure deployment requires both sides to correctly implement their respective responsibilities under the chosen profile.
Key and certificate management becomes central
Because FAPI relies heavily on strong client authentication and signed requests, the security of an entire FAPI-compliant deployment ultimately rests on how well the underlying cryptographic keys and certificates involved are generated, stored, rotated, and protected, making rigorous key management practices a genuinely central, ongoing security responsibility rather than a one-time setup task.
Regulatory context adds its own obligations
Many organizations adopting FAPI do so specifically because a regulatory framework requires it, which typically brings additional obligations beyond the technical specification itself — audit requirements, specific certification processes, and ongoing compliance verification — that should be understood and planned for separately from the purely technical implementation work.
FAPI does not replace broader application security
FAPI specifically strengthens the authentication and authorization layer of a system. It does not, by itself, address every other security concern an application might have — proper input validation, secure data storage, and sound overall application security practices remain just as necessary as they would be in any other system, FAPI-compliant or not.
Visibility
Monitoring, Logging & Metrics
Given the regulatory and financial stakes typically involved, monitoring a FAPI-compliant deployment deserves particular rigor.
Tracking client policy rejections
Keycloak’s logs record when a request is rejected specifically for failing to meet a configured client policy’s requirements — for example, an authorization request that was not properly pushed, or a token exchange attempted with an unapproved authentication method. Reviewing these rejections helps distinguish between genuine attack attempts and legitimate clients that have not yet correctly implemented their required side of the FAPI profile.
Certificate and key expiry monitoring
Because FAPI-compliant authentication methods depend heavily on certificates or signing keys, proactively monitoring their expiry timelines is especially critical here, since an expired certificate or key in this context does not merely cause inconvenience — it can suddenly and completely block a client’s ability to authenticate at all, in a system where availability itself may carry regulatory significance.
Auditing for compliance drift over time
As client applications and their own implementations evolve, periodically re-verifying that a client genuinely continues to meet its assigned FAPI profile’s requirements — rather than assuming an initial certification remains valid indefinitely — helps catch compliance drift before it becomes a genuine regulatory or security issue.
Incident response readiness for financial-grade systems
Given the potential financial and regulatory consequences of a security incident in a FAPI-compliant system, maintaining well-rehearsed, specific incident response procedures — including how to quickly revoke compromised certificates or keys — is a particularly important complement to the preventative security measures FAPI itself provides.
Shape
Design Patterns & Anti-patterns
Organizations that successfully operate FAPI-compliant systems in production tend to converge on a small number of consistently sound patterns.
Pattern: Matching profile strictness to actual risk
Mature deployments deliberately choose between FAPI 1.0 Baseline, FAPI 1.0 Advanced, or FAPI 2.0 based on the genuine risk profile of each specific client and its use case, rather than defaulting every single client to the strictest possible profile regardless of whether its actual functionality warrants that level of complexity.
Pattern: Dedicated key and certificate lifecycle management
Given how central cryptographic material is to FAPI’s guarantees, well-run deployments treat key and certificate lifecycle management — generation, secure storage, rotation, and revocation — as its own dedicated operational discipline, rather than an afterthought bolted onto general client configuration.
Pattern: Conformance testing before production rollout
Organizations preparing a genuinely FAPI-compliant integration commonly run their configuration through established, publicly available conformance test suites before going live, verifying both the authorization server and client-side implementation genuinely meet the chosen profile’s requirements rather than relying solely on internal assumptions.
Anti-pattern: Assuming a client policy alone guarantees full compliance
A risky shortcut is treating the act of enabling a FAPI client policy in Keycloak as the entire compliance task complete, without separately verifying that every connecting client application has correctly implemented its own required half of the profile.
Situation
A financial institution enables a FAPI 1.0 Advanced client policy in Keycloak for a new third-party partner integration, and, seeing the policy configured and active, declares the integration compliant and moves the partner directly into production.
Consequence
Months later, an external audit reveals the partner’s own client implementation had been silently falling back to a weaker authentication method that Keycloak happened to still accept due to an overlooked configuration gap, meaning the integration had never genuinely operated under the full protection the FAPI Advanced profile was meant to guarantee.
Better Approach
Require the partner to pass a recognized conformance test suite specifically validating their client-side implementation against the chosen FAPI profile before granting production access, treating Keycloak’s own configuration as necessary but not, by itself, sufficient proof of end-to-end compliance.
Getting It Right
Best Practices & Common Mistakes
A disciplined set of habits consistently separates a FAPI adoption that genuinely delivers on its security promise from one that merely appears compliant on paper.
Choose the right profile deliberately
Match FAPI 1.0 Baseline, Advanced, or FAPI 2.0 to the genuine risk level of each specific client and use case.
Verify client-side implementation, not just server configuration
Require partner and client applications to demonstrate correct implementation of their own required half of the profile.
Invest properly in key and certificate management
Treat this as a dedicated, ongoing operational responsibility central to the whole system’s security.
Run recognized conformance testing before production
Validate the full, real-world flow against established test suites rather than relying on configuration review alone.
Applying FAPI everywhere regardless of actual need
Adding this level of complexity to low-risk applications adds cost without a matching security benefit.
Treating initial compliance as permanent
Client implementations and infrastructure evolve; compliance should be periodically re-verified, not assumed to hold indefinitely.
Before onboarding any new client under a FAPI client policy, require them to walk through and successfully pass an established, recognized conformance test suite for the specific profile involved, and keep a documented record of that result as part of the onboarding process, rather than relying solely on a verbal or contractual assurance of compliance.
In Practice
Real-World & Industry Examples
FAPI compliance shows up specifically wherever regulation or genuine risk demands the strongest available OAuth-based security guarantees.
Open banking regulatory mandates
Several national and regional open banking initiatives around the world explicitly require FAPI, or a closely related security profile, for the APIs banks expose to authorized third-party providers, reflecting the direct financial stakes involved when a third-party application can initiate payments or read complete account information on a customer’s behalf.
Open finance and open insurance ecosystems
As the open banking model has expanded into broader “open finance” and “open insurance” ecosystems, covering a wider range of financial products, FAPI has similarly been adopted as the underlying security foundation for these newer, related regulatory frameworks, given their comparable data sensitivity and transaction risk.
Government digital identity systems
Some national digital identity platforms, handling extremely sensitive citizen verification and authorization, have adopted FAPI or closely aligned security profiles, recognizing that the risk profile of a compromised government identity credential shares much in common with the risk profile FAPI was originally designed to address in banking.
High-value enterprise API ecosystems
Beyond regulated financial services, some enterprises operating extremely high-value API ecosystems — for example, systems capable of authorizing large corporate transactions — voluntarily adopt FAPI’s stricter requirements even without a specific regulatory mandate, simply because the underlying risk profile of their system genuinely warrants this heightened level of protection.
Questions Answered
FAQ
Wrapping Up
Summary & Key Takeaways
FAPI compliance represents the point where OAuth-based security stops being merely “reasonable” and becomes deliberately, comprehensively hardened for the situations that can least afford to get it wrong. By bundling together pushed and signed authorization requests, strong client authentication, sender-constrained tokens, and signed responses into a single, coherent, mandatory package, FAPI closes off an entire category of risks that a standard OAuth deployment might otherwise leave optional. Keycloak’s client policy profiles make adopting this bundle dramatically more approachable than implementing every individual rule from scratch — but the real security guarantee still depends on every participant in the system, not just the authorization server, correctly holding up their end of a genuinely demanding standard.
Key Takeaways
- FAPI is a stricter security profile built on top of OAuth 2.0 and OpenID Connect — not a replacement, but a mandatory tightening for the highest-stakes use cases.
- It bundles several individually meaningful protections together — pushed authorization requests, signed request objects, strong client authentication, sender-constrained tokens, and signed responses.
- Keycloak implements FAPI through Client Policies — pre-built profiles for FAPI 1.0 Baseline, FAPI 1.0 Advanced, and FAPI 2.0.
- Compliance requires both sides of the system to cooperate — Keycloak’s configuration alone does not guarantee a client application has correctly implemented its own required half.
- Sender-constrained tokens neutralize stolen-token reuse — a core protection distinguishing FAPI from many standard OAuth deployments.
- Regulatory mandates are the most common real-world driver — open banking and open finance frameworks around the world frequently require FAPI directly.
- FAPI’s complexity should be matched to genuine risk — not every application needs it, and applying it without real need adds cost without a corresponding security benefit.