FAPI 2.0 Security Profile

ProAuth supports opt-in FAPI 2.0 Security Profile enforcement for tenants and client applications. FAPI mode is intended for high-value API access where authorization requests, client authentication, and access tokens must be strongly protected.

FAPI mode is disabled by default. Existing tenants and client applications continue to use the non-FAPI behavior unless you explicitly enable the profile.

Effective Policy

The effective security profile is resolved in this order:

1. Tenant option RequireFapi2SecurityProfile = true forces FAPI 2.0 for every client in the tenant.
2. Otherwise, client application SecurityProfile decides.
3. If client application SecurityProfile is null, ProAuth uses tenant option DefaultClientSecurityProfile.

Use None for normal OIDC/OAuth behavior and Fapi2Security for FAPI 2.0 enforcement. Migrated existing clients are set to explicit None to preserve compatibility.

Tenant Options

Configure tenant options through the v2 Management API.

Option	Values	Default	Behavior
DefaultClientSecurityProfile	None, Fapi2Security	None	Applied when a client application's SecurityProfile is null.
RequireFapi2SecurityProfile	true, false	false	Forces all clients in the tenant into FAPI mode.

Client Application Setting

Set SecurityProfile on the v2 client application resource:

{
  "name": "payments-api-client",
  "securityProfile": "Fapi2Security"
}

Admin UI fields are not required for this release; configure the setting through the v2 Management API, import tooling, or automation.

Required Client Configuration

A FAPI client must use:

• Authorization code flow only: response_type=code.
• PAR for every authorization request.
• PKCE with code_challenge_method=S256.
• A confidential client application.
• Client authentication with private_key_jwt, tls_client_auth, or self_signed_tls_client_auth.
• Sender-constrained access tokens through DPoP or certificate binding.

For DPoP-bound FAPI clients, set dpopBoundAccessTokens = true and send a valid DPoP proof at the token endpoint. For mTLS-bound FAPI clients, use tls_client_auth or self_signed_tls_client_auth; certificate-bound access tokens are enabled by default for those methods. Non-mTLS clients can also set requireCertificateBoundAccessTokens = true when a client certificate is presented at the token endpoint.

Authorization Requests

In FAPI mode, clients first send the complete authorization request to the PAR endpoint. The browser-facing authorization request must then contain only:

• client_id
• request_uri

The pushed request itself must include a registered redirect_uri, response_type=code, and S256 PKCE parameters.

Token Requests

In FAPI mode, the token endpoint accepts only authorization_code and refresh_token grants for the client. Authorization-code redemption requires the original authorization code to have been issued with S256 PKCE and the token request to include code_verifier.

private_key_jwt client assertions for FAPI clients must use the issuer URL as the assertion audience and must be signed with asymmetric FAPI-compatible algorithms (PS* or ES*).

Refresh Tokens

Non-FAPI clients keep ProAuth's default rolling refresh-token policy. Each successful refresh-token grant returns a new refresh token, revokes the used refresh token, and treats reuse of an old refresh token as a replay signal that revokes the token family for that user and client.

FAPI clients use stable sender-constrained refresh tokens. A successful FAPI refresh-token grant returns new access and ID tokens but does not return a replacement refresh_token. The client continues to use the original refresh token until it expires or is explicitly revoked.

FAPI refresh-token grants still require the configured FAPI client authentication and sender constraint:

• DPoP-bound clients must send a valid DPoP proof with each refresh request.
• mTLS clients must present the configured client certificate with each refresh request.

If a FAPI refresh request fails before token issuance, for example because the DPoP proof is missing, the refresh token is not consumed. A later compliant refresh request can still use the same refresh token. Explicit revocation, user deactivation, or expiry still makes the refresh token invalid.

Lifetimes

FAPI mode caps PAR handles to less than 600 seconds and authorization codes to at most 60 seconds. Non-FAPI clients keep the configured tenant lifetimes.

Discovery

Discovery stays broad unless tenant option RequireFapi2SecurityProfile is true. When the tenant requires FAPI, discovery advertises only FAPI-compatible response types, grant types, and client authentication methods, and sets require_pushed_authorization_requests to true.

Error Behavior

FAPI-specific failures use the standard OAuth/OIDC error response model. Examples include invalid_request for missing PAR or missing S256 PKCE, unsupported_response_type for implicit or hybrid response types, and invalid_client or unauthorized_client for unsupported client authentication.

Related Configuration

• JWT Client Authentication
• Mutual TLS Client Authentication
• DPoP Token Binding
• PAR and JAR