API Security: FAPI 2.0 & Open Banking Security

Overview

OAuth 2.0 was designed as a delegated authorization framework for consumer web applications. A user grants a third-party app access to their Google calendar — the threat model assumes the access token is short-lived, the damage from theft is bounded, and replay attacks are mitigated by HTTPS. That threat model is wrong for payment initiation. A stolen payment authorization token replayed once drains an account. A tampered redirect parameter redirects the authorization code to an attacker. An insufficient proof-of-possession model means a token stolen from one client can be used by any bearer.

FAPI 2.0 (Financial-grade API Security Profile 2.0) is an OpenID Foundation specification that profiles OAuth 2.1 specifically for high-value financial API use cases. It mandates the controls that fill the gaps OAuth 2.0 leaves open: Pushed Authorization Requests to prevent parameter tampering, DPoP or mTLS to bind tokens to the client that requested them, Pushed Authorization Requests for request integrity, Rich Authorization Requests for fine-grained consent, and JARM for signed authorization responses. SAMA Open Banking Phase 2 mandates FAPI 2.0 as the security baseline for all Third Party Provider (TPP) access — AIS, PIS, and Confirmation of Funds.

FAPI 2.0 Requirements

FAPI 2.0 is defined in two parts: the Security Profile (FAPI2SP) and the Message Signing profile (FAPI2MS). For SAMA Open Banking, both apply. The normative requirements that distinguish FAPI 2.0 from a standard OAuth 2.1 deployment:

PKCE S256 (SHA-256 code challenge) is mandatory — plain PKCE is banned because the plain method provides no security benefit. The state parameter is still recommended for CSRF protection at the redirect level, but it is no longer the primary authorization request integrity mechanism — that role moves to PAR.

Pushed Authorization Requests (PAR)

The fundamental problem with the OAuth 2.0 authorization endpoint is that the authorization request parameters are sent as query parameters in a browser redirect URL. The URL is visible in the browser history, referer headers, and server access logs. An attacker who can modify the redirect URL — through an open redirect vulnerability, a misconfigured redirect_uri, or a browser extension — can tamper with the scope, redirect_uri, or state parameters before the authorization server sees them.

PAR (RFC 9126) solves this by moving the authorization request out of the browser. The client POSTs all authorization parameters directly to the server’s /par endpoint, authenticated with its client credentials. The server validates the parameters and returns a request_uri (valid for 90 seconds by default). The client then redirects the user to the authorization endpoint using only client_id and the request_uri — no sensitive parameters in the URL.

# Step 1: POST authorization_details to PAR endpoint
POST /par HTTP/1.1
Host: auth.openbanking.saib.sa
Content-Type: application/x-www-form-urlencoded
Authorization: Basic dHBwLWNsaWVudC1pZDpjbGllbnQtc2VjcmV0

response_type=code
&client_id=tpp-client-id
&redirect_uri=https%3A%2F%2Ftpp.example.sa%2Fcallback
&scope=openid+payments
&code_challenge=s256-challenge-value
&code_challenge_method=S256
&authorization_details=%5B%7B
  "type"%3A"sama_payment_initiation"%2C
  "actions"%3A%5B"initiate"%5D%2C
  "locations"%3A%5B"https%3A%2F%2Fapi.openbanking.saib.sa%2Fpis"%5D%2C
  "instructedAmount"%3A%7B
    "amount"%3A"500.00"%2C
    "currency"%3A"SAR"
  %7D%2C
  "creditorAccount"%3A%7B
    "iban"%3A"SA44 2000 0001 2345 6789 1234"
  %7D%2C
  "debtorAccount"%3A%7B
    "iban"%3A"SA03 8000 0000 6080 1016 7519"
  %7D
%7D%5D

# Server response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "request_uri": "urn:ietf:params:oauth:request_uri:bwc4JQ-ESc0w8wM7M9K7w5sNe3vh",
  "expires_in": 90
}

# Step 2: redirect user with ONLY client_id + request_uri
GET /authorize?client_id=tpp-client-id
  &request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3Abwc4JQ-ESc0w8wM7M9K7w5sNe3vh
  HTTP/1.1
Host: auth.openbanking.saib.sa

DPoP — Demonstrating Proof of Possession

DPoP (RFC 9449) is the primary mechanism for sender-constraining access tokens in FAPI 2.0 when client certificate infrastructure is not available for every TPP. The core idea: the client generates an ephemeral EC key pair (P-256 or P-384) at request time, signs a DPoP proof JWT that binds the request to that key, and sends the proof alongside the access token. The resource server verifies that the proof is valid for this specific HTTP method, URL, and timestamp — and that the token’s cnf claim matches the public key in the proof.

The DPoP proof JWT header carries typ: "dpop+jwt" and the client’s ephemeral public key (jwk). The payload carries: htm (HTTP method), htu (HTTP URL without query), iat (issued-at), and jti (unique nonce to prevent replay). The proof is valid only for the specific request it is attached to.

// DPoP Proof JWT — Header
{
  "typ": "dpop+jwt",
  "alg": "ES256",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x":   "base64url-encoded-x-coordinate",
    "y":   "base64url-encoded-y-coordinate"
  }
}

// DPoP Proof JWT — Payload
{
  "jti": "e1e24b80-7d1d-4f6a-9cb0-2a5b3c1d4e5f",  // unique nonce; must be cached + rejected if replayed
  "htm": "GET",                                   // must match actual HTTP method
  "htu": "https://api.openbanking.saib.sa/pis/v1/payment-consents",  // no query string
  "iat": 1725494400,                              // issued-at; server rejects if skew > 60s
  "ath": "base64url(sha256(access_token_bytes))"   // RFC 9449 §4.3: bind proof to specific token
}

// Spring Security 6.3 — DPoP validation configuration (resource server side)
// In SecurityFilterChain bean:
http
  .oauth2ResourceServer(rs -> rs
    .jwt(jwt -> jwt
      .decoder(NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build())
    )
    .opaqueToken(opaque -> opaque
      .introspectionUri("https://auth.openbanking.saib.sa/realms/openbanking/protocol/openid-connect/token/introspect")
      .introspectionClientCredentials(clientId, clientSecret)
    )
  )
  .addFilterBefore(new DPoPProofValidationFilter(dpoPProofValidator, jtiCache), BearerTokenAuthenticationFilter.class);

// DPoPProofValidationFilter validates:
// 1. typ = "dpop+jwt"
// 2. alg in allowlist (ES256, RS256 — no none/HS256)
// 3. htm matches request method
// 4. htu matches request URL (scheme + host + path, no query)
// 5. iat within 60s clock skew window
// 6. jti not seen in Redis cache (insert + TTL on first sight)
// 7. token cnf.jkt thumbprint matches JWK in DPoP header

mTLS-Bound Tokens

mTLS sender-constraining (RFC 8705) is an alternative to DPoP — stronger in some respects, more operationally demanding in others. Instead of a per-request DPoP proof, the TPP presents its TLS client certificate during the token request. The authorization server computes a thumbprint of the certificate (x5t#S256: SHA-256 of the DER-encoded certificate) and embeds it in the access token’s cnf claim. The resource server extracts the certificate from the TLS session (via the X-Client-Cert header at Kong, injected by the TLS terminator) and verifies the thumbprint matches the token’s cnf.x5t#S256.

The security model is stronger than DPoP in that the binding is established at the TLS layer before the HTTP request reaches the application — a stolen access token is useless without the private key of the client certificate. The operational cost is higher: every TPP must have a client certificate provisioned, renewed, and revoked through a certificate management process, and the certificate infrastructure must integrate with SAMA’s TPRM TPP registration process.

Rich Authorization Requests (RAR)

Standard OAuth 2.0 scopes are coarse-grained: openid payments accounts grants blanket access to all of the TPP’s payment and account operations. SAMA Open Banking Phase 2 requires granular consent that specifies the exact accounts, amounts, and operations covered by each authorization. RAR (RFC 9396) adds the authorization_details parameter to carry a structured JSON array of consent objects with rich, resource-specific semantics.

Each authorization_details object carries: type (the resource type identifier, e.g. sama_account_information or sama_payment_initiation), actions (what operations are permitted), locations (the resource server URLs that may receive the token), and resource-specific fields (amount, currency, account identifiers for PIS; account list for AIS). The authorization server embeds the consented authorization_details into the access token, and the resource server validates on every call that the requested operation is within the consented scope.

SAMA’s consent model defines three consent states: pending (created, awaiting PSU authorization), authorised (PSU approved), rejected (PSU declined or expired), and revoked (PSU or TPP explicitly cancelled). The resource server must check the consent status on every API call, not just at token issuance — a consent can be revoked mid-session.

Keycloak 24 FAPI 2.0 Configuration

Keycloak 24 ships a built-in FAPI 2.0 Security Profile realm policy that can be enabled via Admin Console or the REST API. It configures the realm to enforce PKCE S256, require PAR, enable JARM, and validate DPoP proofs. The client policy engine applies these checks to all clients in the realm that are tagged as FAPI 2.0 clients.

{
  "realm": "openbanking",
  "enabled": true,
  "sslRequired": "all",
  "accessTokenLifespan": 300,
  "ssoSessionMaxLifespan": 7776000,    // 90 days for AIS per SAMA

  "clientPolicies": {
    "policies": [
      {
        "name": "sama-fapi2-policy",
        "enabled": true,
        "conditions": [
          { "condition": "client-roles",
            "configuration": { "roles": ["fapi2-client"] } }
        ],
        "profiles": ["fapi-2-security-profile", "fapi-2-message-signing"]
      }
    ],
    "profiles": [
      {
        "name": "fapi-2-security-profile",
        "executors": [
          { "executor": "pkce-enforcer",
            "configuration": { "allow-plain-method": false } },
          { "executor": "par-enforcer",
            "configuration": {
              "par-required": true,
              "request-uri-lifespan": 90
            }
          },
          { "executor": "dpop-bind-enforcer",
            "configuration": {
              "dpop-required": true,
              "allowed-algorithms": ["ES256", "PS256"]
            }
          },
          { "executor": "holder-of-key-enforcer",
            "configuration": { "autoConfigure": true } },
          { "executor": "jarm-enforcer",
            "configuration": {
              "signing-key-id": "jarm-signing-rsa-key",
              "response-mode": "jwt"
            }
          },
          { "executor": "secure-response-type-enforcer",
            "configuration": {
              "allow-token-response-type": false  // no implicit flow
            }
          }
        ]
      }
    ]
  },

  "attributes": {
    "par.request.uri.lifespan": "90",
    "oauth2.device.code.lifespan": "0",
    "cibaBackchannelAuthRequestedExpiry": "120"
  }
}

Kong & IBM API Connect Enforcement

The authorization server (Keycloak) issues FAPI 2.0-compliant tokens. The API gateway (Kong 3.7 or IBM API Connect 10.0.7) enforces token validity, DPoP binding, consent scope, and rate plans on every API call from TPPs. The gateway sits between the internet and the resource server — no API call reaches the resource server without passing through Kong’s plugin chain.

Kong’s OIDC plugin performs token introspection against Keycloak on every request. The response includes the cnf claim (DPoP or mTLS binding), the authorization_details (RAR consent), and the sub (TPP identity). A custom Lua plugin validates that the DPoP proof in the DPoP header matches the cnf.jkt thumbprint in the introspected token. IBM API Connect accomplishes the same via a GatewayScript assembly policy that reads the introspection response and validates the cnf claim.

Rate plans in IBM API Connect are tied to the SAMA consent type: an AIS (Account Information Service) plan allows high-frequency reads (up to 4 calls per second per TPP per account), while a PIS (Payment Initiation Service) plan is throttled more aggressively (10 payment initiations per minute per TPP) and requires the payment amount to be within the consented limit from the authorization_details.

SAMA Open Banking Phase 2 Alignment

SAMA Open Banking Phase 2 defines three API classes and distinct security requirements for each. AIS (Account Information Service) allows TPPs to read account data — balances, transactions, statements — with consent lasting up to 90 days and access tokens valid for up to 5 minutes per call. PIS (Payment Initiation Service) is single-consent, single-use: the authorization covers exactly one payment, the access token is single-use and expires after it has been used to submit the payment instruction, and the consent expires as soon as the payment reaches a terminal state. CoF (Confirmation of Funds) confirms whether a specified amount is available in an account without initiating any transaction — consent is typically longer-lived for merchant use cases.

SAMA’s TPRM (Third-Party Risk Management) requirements mandate that TPPs are registered through the SAMA Open Banking Directory before they can onboard to any ASPSP (Account Servicing Payment Service Provider). TPP registration produces a client ID, a software statement assertion (SSA) signed by the SAMA directory, and optionally a client certificate for mTLS binding. The ASPSP’s Dynamic Client Registration (DCR) endpoint accepts the SSA and creates the OAuth 2.0 client in Keycloak automatically — no manual client provisioning.

Production Checklist

1. Audit your OAuth 2.0 foundation first. Ensure token introspection works, refresh token rotation is enabled, and all existing scopes map to a resource server. FAPI 2.0 controls layer on top — a weak OAuth foundation magnifies vulnerabilities rather than containing them.
2. Enable PAR in Keycloak. Set par.request.uri.lifespan to 90 seconds. Instrument the PAR endpoint to log every request with TPP identity, IP, and request_uri jti. Alert on reuse of any request_uri.
3. Choose DPoP or mTLS binding (or both). DPoP is lower-friction for TPP onboarding; mTLS is stronger and easier to enforce at the TLS layer. If your TPP onboarding process can provision client certificates, prefer mTLS; otherwise DPoP with a robust jti cache is SAMA-compliant.
4. Deploy the jti replay prevention cache. Redis Cluster with TTL equal to the DPoP proof validity window (60–300 seconds). Instrument cache hit rate — a hit on a jti that is not from a known legitimate retry is a security event.
5. Implement RAR consent model. Define authorization_details types for AIS, PIS, and CoF matching SAMA Open Banking schema. Build a consent store (persistent, queryable by TPP + PSU + status). Expose a consent query endpoint. Embed approved authorization_details in the token introspection response.
6. Configure JARM in Keycloak. Generate a dedicated RSA-4096 JARM signing key. Set response_mode=jwt as the required response mode for all FAPI 2.0 clients. Verify that TPP clients correctly parse and validate the JARM JWT before extracting the authorization code.
7. Configure Kong DPoP validation plugin. Validate DPoP proof on every resource server request (not just at token issuance). Forward the client certificate header (X-Client-Cert) from the TLS terminator for mTLS binding validation.

1. PAR endpoint active; request_uri single-use enforced; reuse logged as security event.
2. PKCE S256 mandatory; plain challenge method rejected at authorization endpoint.
3. DPoP or mTLS binding active on all TPP-facing token and resource endpoints.
4. jti replay prevention cache (Redis Cluster) deployed with TTL matching DPoP validity window.
5. JARM active; response_mode=jwt enforced; JARM signing key rotated annually.
6. RAR authorization_details schema validated at PAR endpoint; consent store persists approved details.
7. Consent status checked on every API call, not just at token issuance.
8. AIS access token lifetime: 300 s; PIS token single-use enforced at resource server.
9. Keycloak client policies applying FAPI 2.0 profile to all TPP clients; manual client creation blocked.
10. Dynamic Client Registration active; SAMA directory SSA validated before client creation.
11. TPP identity (client_id, SSA subject) logged in every audit event (PAR, auth, token, resource access).
12. Implicit grant, ROPC, and plain PKCE blocked at realm policy level.
13. Kong rate plans differentiated by consent type (AIS vs PIS); PIS rate plan aligned with SAMA API class limits.