Keycloak FAPI 2.0, DPoP and CIBA

Keycloak applies FAPI requirements through client policies, which are attached to individual clients. A client policy groups profiles and executors, and each executor performs one check at a defined point in the flow. Realm-wide settings alone will not make a client conform, so the first decision is scope. List every client that must meet a FAPI profile, separate it from clients that stay on standard OpenID Connect, and attach the policy only to the first group. Mixed realms are common because internal tools and financial API clients often share one Keycloak server. Record the scope in your design document before you change any configuration, because the scope determines which clients need testing.

A policy checks three moments in the flow. At authorization time, executors can inspect the request itself, for example the response type, whether PKCE is used, the redirect URI, and whether pushed authorization requests are required. At token time, they check properties of the issued tokens, such as the signing algorithm and whether the token is sender-constrained. At client authentication time, they check how the client proves its identity, including the authentication method and the strength of its keys. The exact set of checks depends on the profile and the Keycloak release you run, so confirm each one against the server administration guide before you map it to a control in your own assessment.

You can define a policy in two places. The admin console provides a client policies area where you create policies, add profiles and executors, and attach them to clients. This suits exploration and a small number of clients. The realm configuration is the other place. Policies are part of the realm representation, so you can export them, keep them in version control and import them into another environment. If you deploy with the Keycloak Operator, the KeycloakRealmImport resource is a natural route. Choose one source of truth. Console edits that never return to the realm file can drift from the version in your repository and be overwritten at the next import.

A client that does not meet the profile should fail, and the failure should be visible. The intended behavior is that Keycloak rejects the request, token or authentication attempt with an error, and does not issue a token under weaker settings. A silent fallback to a standard flow would turn a configuration gap into an unnoticed compliance gap. Test this directly. For each in-scope client, send one request that breaks each rule, such as a missing PKCE challenge or a weak client key, and confirm the rejection and the error in the logs. Keep the results as evidence for the assessor, and repeat the tests after every upgrade, because executor behavior can change between releases.

Take the executor and policy names from the server administration guide for your release, not from community posts or memory, and copy them exactly into your realm configuration. A short mapping table helps. Each row lists a requirement from your chosen profile, the executor that enforces it, the point where it runs and the test that proves it. Share the table with your security team before the build starts, since it becomes the basis for both the configuration and the test plan. Confirm in your own environment that the Keycloak version you deploy supports each executor you rely on.

DPoP changes the core assumption behind an access token. A bearer token works for anyone who holds it, but a DPoP-bound token works only with the key pair that the client generated. The client creates the key pair, Keycloak binds the issued token to the public key, and each request to a protected API carries a signed proof that the client builds with the private key. Your resource servers must do more than read the Authorization header. They must check that the access token is bound to the key in the proof, that the proof was signed by that key, that it is recent, and that it has not been used before. Plan these checks in the resource server code or in the gateway that fronts it, and confirm which token types and proof claims your Keycloak version issues in the current documentation.

The first operational effect is key storage on clients. The private key is what makes a stolen access token useless, so its handling becomes a security control in its own right. Server-side clients can usually keep keys in a hardware-backed store, a secrets manager or a protected file with restricted permissions. Single-page applications and mobile apps need a different answer, and the options depend on the platform and on what the browser or operating system exposes. Ask each application team where the key lives, how long it lives, when it rotates, and what happens after a logout or device loss. Confirm with the Keycloak documentation which client settings enforce DPoP and whether any client types are excluded.

The second effect is time and replay. Each proof carries an issued-at value, and resource servers must accept proofs only within a defined window. If your API servers have clock drift, valid requests will fail intermittently, so confirm time synchronization across every node before go-live. Replay protection also needs shared state. If a proof identifier is stored only in local memory, a request sent to a different instance can be replayed without detection. Behind a load balancer, you need a shared store for recently seen proof identifiers, sized for your request volume, with expiry aligned to the acceptance window. Test this with several instances behind the balancer, not with one server.

The third effect is proxies and mixed clients. The proof includes the HTTP method and target URL, so a reverse proxy, ingress controller or API gateway that rewrites hosts, paths or schemes can make every proof fail. Configure forwarding headers so each resource server reconstructs the URL the client actually signed, and confirm that no intermediary strips the DPoP header. Mixed clients need a deliberate decision. During migration, you may keep some clients on bearer tokens, but that choice weakens the protection for those clients. Decide whether Keycloak should reject requests without proofs for specific clients, whether your APIs should accept both token forms for a fixed period, and who approves the exceptions and their end date.

Decoupled CIBA, the Client-Initiated Backchannel Authentication flow, fits a narrow set of journeys: the device that starts the transaction is not the device where the person approves it. A typical example is a payment initiated by a merchant or call-center agent on one screen, with the customer approving the payment on their own phone. The client starts the request, Keycloak authenticates the user out of band, and the client receives the outcome without the user being redirected through the browser that made the request. Before you plan a CIBA build in Keycloak, confirm that this split of devices is a real requirement of the journey and not a convenience that a standard redirect flow could handle.

The main trade-off is reachability. The user must be able to receive and complete the authentication on the authenticating device, within the time the request stays valid. A customer with no signal, a switched-off phone, or a notification that is silenced will simply fail the flow, and the client has to handle that outcome cleanly. Notification delivery is also part of the design, not an afterthought. You need to decide how the authentication device is registered and bound to the user, how the request reaches it, and whether the client polls for the result, waits for a ping callback, or uses a push mode. Each mode places different demands on your client, your network paths and your retry logic.

The binding message deserves as much attention as the transport. The user sees a short text on the authenticating device, and that text is the only evidence they have of what they are approving. A payment approval should show the payee and amount in plain language, and a call-center verification should say which service is requesting access. Keep the message short enough to fit a phone notification and avoid wording that a fraudster could reuse to make a request look routine. Review the wording with fraud and customer operations teams before build, because it is part of the control, not just the interface.

Whether Keycloak supports each CIBA mode, and how, must be confirmed for the exact version you plan to run, along with any extension points you would need for your notification channel. Do not assume a mode is available because a specification describes it. Ask for a written list of supported modes, the configuration that enables them, and any features that are experimental or unsupported in your version, and test each mode against your own client before committing to a design.

Many teams do not need CIBA at all. If the customer or agent can complete a standard authorization code flow with sender-constrained tokens in the same browser session, that is usually simpler to build, test and audit. Reserve CIBA for journeys where the device split is inherent and the business accepts the reachability and messaging trade-offs. A short written comparison of the two flows for each use case is a useful gate before any CIBA work is scoped.

Three regimes may shape how you configure Keycloak for FAPI 2.0 clients, DPoP-bound tokens and CIBA flows, but none of them is satisfied by a single setting. PCI DSS applies to entities that store, process or transmit cardholder data or sensitive authentication data, and to entities that could affect the security of the cardholder data environment, including merchants, processors, acquirers, issuers and service providers. If the Keycloak realm, its hostnames or the APIs it protects sit in that environment or can affect it, the identity layer falls within the assessment. The PCI SSC does not enforce compliance itself. Confirm with your acquirer or payment brands whether you must validate, and which route applies: a Report on Compliance from a Qualified Security Assessor, or a Self-Assessment Questionnaire, each with an Attestation of Compliance.

DORA, Regulation (EU) 2022/2554, has applied since 17 January 2025 to 20 types of financial entity and applies directly without national transposition. If you are in scope and Keycloak supports an ICT service that carries critical or important functions, two obligations reach the design. Article 28(3) requires a register of information covering all contractual arrangements for ICT services, so the Keycloak deployment, its hosting provider and any implementation partner should appear in that record. Article 28(8) requires documented, tested exit strategies and transition plans for those services. Article 30(2) requires each ICT contract to state where services are provided and data processed, to give advance notice of changes, and to cover data return on insolvency or termination. Check your provider and partner contracts against these terms before go-live.

The FTC Safeguards Rule (16 CFR Part 314) applies to non-bank financial institutions under FTC jurisdiction. Section 314.4(c)(5) requires multi-factor authentication for any individual accessing any information system, unless the Qualified Individual approves an equivalent control in writing. For Keycloak, this means mapping every realm, admin console login and user-facing client flow to a required second factor. Keycloak's OTP policies, W3C WebAuthn, passkeys and recovery codes can supply that factor, but the rule covers people, so staff access, administrator access and any service account a person can use need review too. Confirm which authentication steps each FAPI, DPoP and CIBA flow actually performs. A protocol profile does not automatically prove that an individual passed MFA, and any equivalent control needs written approval.

Keycloak configuration can produce evidence for controls in all three regimes, including client policy settings, realm authentication flows, administrator activity records and documented design decisions. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. The assessor, the payment brand, the regulator or the Qualified Security Assessor decides the outcome. Assessment scope also depends on the entity, not the software: the same Keycloak version can be in scope for one organization and out of scope for another. Agree the boundary with your assessor early, and record which realms, clients, hostnames and flows are included, so the evidence matches what was actually assessed.