User Story -2 : FAPI 2.0 Compatible RP Backend Library for eSignet Integrations in Java, JS and Python <WIP>

[rachik1709]

1. Purpose

As a developer, I want to create a reusable OIDC client backend library that automatically implements all required FAPI 2.0 compliance checks and validations (as defined in OAuth 2.0, PAR, DPoP, PKCE, JWT Client Authentication RFCs), so that external Relying Parties (RPs) can integrate with eSignet securely without needing to perform manual FAPI-related backend development.

2. Basic Flow

RP backend uses the library to initiate an OIDC authorization code flow with eSignet.

Library automatically:

Creates and sends Pushed Authorization Requests (PAR) as per RFC 9126.

Applies PKCE (RFC 7636) with secure code challenge and verifier generation.

Handles JWT client authentication (RFC 7523) for client assertion and token exchange.

Adds DPoP proof headers (RFC 9449) for every request to ensure sender-constrained tokens.

Upon receiving tokens, the library validates:

iss, aud, iat, exp claims in ID Token and Access Token.

Token binding between DPoP and the access token.

Response mode, nonce, and authorization code parameters as per OAuth 2.0 (RFC 6749) and FAPI 2.0 Security Profile.

Tokens and responses are verified and made available to the RP backend in a standard response format.

3. Acceptance Criteria (AC)

The library must support end-to-end OIDC authorization code flow with:

PKCE (code_challenge, code_verifier) handling.

JWT-based client authentication at token endpoint.

Pushed Authorization Request endpoint usage (PAR).

DPoP proof-of-possession implementation for access tokens.

Must validate issuer, audience, and nonce claims as per FAPI 2.0.

Must reject any response with missing or invalid iss or aud values.

Must verify DPoP nonce and binding between proof and token.

Must handle token expiration, replay prevention, and uniqueness checks.

Must log and return descriptive errors for all failed compliance validations.

Must expose easy-to-use methods for RPs:

initiateAuth()

handleCallback()

exchangeToken()

validateToken()

4. Business Rules

All FAPI 2.0 mandatory security extensions must be pre-enabled by default.

No RP should modify core validation logic; configuration should be limited to client credentials and endpoints.

Library should enforce strict TLS usage and reject insecure endpoints.

Only registered redirect URIs are to be accepted as per OIDC registration metadata.

The library should generate detailed FAPI compliance logs for audit and troubleshooting.

Support both confidential clients (server-side) and public clients (where applicable).

Token introspection and revocation endpoints must be optionally supported.

5. Technical Details (To be detailed)

Relevant RFCs

RFC 6749 – OAuth 2.0 Authorization Framework (base authorization code flow)

RFC 7636 – PKCE for public clients

RFC 7523 – JWT Profile for Client Authentication

RFC 9126 – Pushed Authorization Requests (PAR)

RFC 9449 – Demonstrating Proof of Possession (DPoP)

FAPI 2.0 Security Profile – OpenID Financial-grade API Security Baseline

Implementation Notes

Language support: Java (Spring Boot), Node.js (Express), or Python (FastAPI)

Testing: Must include conformance testing with eSignet FAPI-compliant authorization server.