Merge pull request #5698 from himeshsiriwardana/fapi-compliance-doc

himeshsiriwardana · web-flow · commit 7b16e6e778a3 · 2025-12-01T12:20:02.000+05:30
Added FAPI 2.0 configurations and the related settings
diff --git a/.vale/styles/Microsoft/Acronyms.yml b/.vale/styles/Microsoft/Acronyms.yml
@@ -69,3 +69,4 @@ exceptions:
   - SAML
   - JWT
   - UTC
+  - FAPI
diff --git a/en/identity-server/7.0.0/docs/deploy/compliance/fapi.md b/en/identity-server/7.0.0/docs/deploy/compliance/fapi.md
@@ -0,0 +1 @@
+{% include "../../../../../includes/deploy/compliance/fapi.md" %}
diff --git a/en/identity-server/7.0.0/docs/deploy/compliance/index.md b/en/identity-server/7.0.0/docs/deploy/compliance/index.md
@@ -10,4 +10,6 @@ Being compliant with industry regulations and law is a vital responsibility for
 
 - [FIPS]({{base_path}}/deploy/compliance/fips)
 
+- [FAPI]({{base_path}}/deploy/compliance/fapi)
+
 - [Accessibility Compliance]({{base_path}}/deploy/compliance/accessibility)
diff --git a/en/identity-server/7.0.0/mkdocs.yml b/en/identity-server/7.0.0/mkdocs.yml
@@ -827,6 +827,7 @@ nav:
           - eIDAS: deploy/compliance/eidas.md
           - CCPA: deploy/compliance/ccpa.md
           - FIPS: deploy/compliance/fips.md
+          - FAPI: deploy/compliance/fapi.md
           - Accessibility compliance: deploy/compliance/accessibility.md
       - Analytics:
         - Configure ELK analytics: deploy/elk-analytics-installation-guide.md
diff --git a/en/identity-server/7.1.0/docs/assets/img/guides/applications/fapi-compliant-apps/fapi-2.0-compliant-application.png b/en/identity-server/7.1.0/docs/assets/img/guides/applications/fapi-compliant-apps/fapi-2.0-compliant-application.png
diff --git a/en/identity-server/7.1.0/docs/deploy/compliance/fapi.md b/en/identity-server/7.1.0/docs/deploy/compliance/fapi.md
@@ -0,0 +1 @@
+{% include "../../../../../includes/deploy/compliance/fapi.md" %}
diff --git a/en/identity-server/7.1.0/docs/deploy/compliance/index.md b/en/identity-server/7.1.0/docs/deploy/compliance/index.md
@@ -10,4 +10,6 @@ Being compliant with industry regulations and law is a vital responsibility for
 
 - [FIPS]({{base_path}}/deploy/compliance/fips)
 
+- [FAPI]({{base_path}}/deploy/compliance/fapi)
+
 - [Accessibility Compliance]({{base_path}}/deploy/compliance/accessibility)
diff --git a/en/identity-server/7.1.0/docs/references/financial-grade-api-2.0.md b/en/identity-server/7.1.0/docs/references/financial-grade-api-2.0.md
@@ -0,0 +1 @@
+{% include "../../../../includes/references/financial-grade-api-2.0.md" %}
diff --git a/en/identity-server/7.1.0/mkdocs.yml b/en/identity-server/7.1.0/mkdocs.yml
@@ -900,6 +900,7 @@ nav:
           - eIDAS: deploy/compliance/eidas.md
           - CCPA: deploy/compliance/ccpa.md
           - FIPS: deploy/compliance/fips.md
+          - FAPI: deploy/compliance/fapi.md
           - Accessibility compliance: deploy/compliance/accessibility.md
       - Analytics:
           - Configure ELK analytics: deploy/elk-analytics-installation-guide.md
@@ -1183,7 +1184,9 @@ nav:
               - Token binding: references/token-binding/index.md
               - Client-request: references/token-binding/client-request.md
           - Token hashing: references/token-hashing.md
-          - Financial-grade API: references/financial-grade-api.md
+          - Financial-grade API:
+              -  FAPI 1.0 Advanced: references/financial-grade-api.md
+              - FAPI 2.0: references/financial-grade-api-2.0.md
           - App-native authentication: references/app-native-authentication.md
           - OIDC session management: references/concepts/oidc-session-management.md
           - Push Notification based authentication: references/concepts/push-notification-based-authentication.md
diff --git a/en/identity-server/7.2.0/docs/deploy/compliance/fapi.md b/en/identity-server/7.2.0/docs/deploy/compliance/fapi.md
@@ -0,0 +1 @@
+{% include "../../../../../includes/deploy/compliance/fapi.md" %}
diff --git a/en/identity-server/7.2.0/docs/deploy/compliance/index.md b/en/identity-server/7.2.0/docs/deploy/compliance/index.md
@@ -10,4 +10,6 @@ Being compliant with industry regulations and law is a vital responsibility for
 
 - [FIPS]({{base_path}}/deploy/compliance/fips)
 
+- [FAPI]({{base_path}}/deploy/compliance/fapi)
+
 - [Accessibility Compliance]({{base_path}}/deploy/compliance/accessibility)
diff --git a/en/identity-server/7.2.0/mkdocs.yml b/en/identity-server/7.2.0/mkdocs.yml
@@ -964,6 +964,7 @@ nav:
           - eIDAS: deploy/compliance/eidas.md
           - CCPA: deploy/compliance/ccpa.md
           - FIPS: deploy/compliance/fips.md
+          - FAPI: deploy/compliance/fapi.md
           - Accessibility compliance: deploy/compliance/accessibility.md
       - Analytics:
         - Configure ELK analytics: deploy/elk-analytics-installation-guide.md
diff --git a/en/identity-server/next/docs/deploy/compliance/fapi.md b/en/identity-server/next/docs/deploy/compliance/fapi.md
@@ -0,0 +1 @@
+{% include "../../../../../includes/deploy/compliance/fapi.md" %}
diff --git a/en/identity-server/next/docs/deploy/compliance/index.md b/en/identity-server/next/docs/deploy/compliance/index.md
@@ -10,4 +10,6 @@ Being compliant with industry regulations and law is a vital responsibility for
 
 - [FIPS]({{base_path}}/deploy/compliance/fips)
 
+- [FAPI]({{base_path}}/deploy/compliance/fapi)
+
 - [Accessibility Compliance]({{base_path}}/deploy/compliance/accessibility)
diff --git a/en/identity-server/next/mkdocs.yml b/en/identity-server/next/mkdocs.yml
@@ -964,6 +964,7 @@ nav:
           - eIDAS: deploy/compliance/eidas.md
           - CCPA: deploy/compliance/ccpa.md
           - FIPS: deploy/compliance/fips.md
+          - FAPI: deploy/compliance/fapi.md
           - Accessibility compliance: deploy/compliance/accessibility.md
       - Analytics:
         - Configure ELK analytics: deploy/elk-analytics-installation-guide.md
diff --git a/en/includes/deploy/compliance/fapi.md b/en/includes/deploy/compliance/fapi.md
@@ -0,0 +1,45 @@
+# Financial-grade API (FAPI)
+
+The Financial-grade API (FAPI) specifications, developed by the OpenID Foundation, define strict security requirements for OAuth 2.0 and OpenID Connect flows in financial and high-risk environments. FAPI compliance ensures that applications securely handle sensitive data, prevent token theft, mitigate replay attacks, and comply with industry standards for financial APIs.
+
+{{product_name}} implements [FAPI 1.0 – Advanced](https://openid.net/specs/openid-financial-api-part-2-1_0.html){: target="_blank"} {% if is_version == "7.1.0" %}and [FAPI 2.0](https://openid.net/specs/fapi-security-profile-2_0-final.html){: target="_blank"} profiles{% endif%} to help organizations achieve secure, standards-compliant API access.
+
+To create a FAPI compliant application, refer to the guide on [registering a FAPI-compliant application]({{base_path}}/guides/applications/register-a-fapi-compliant-app/).
+
+## FAPI 1.0 – Advanced compliance features
+
+{{product_name}} fully supports the FAPI 1.0 Advanced Security Profile:
+
+- **Mandatory Signed Request Objects**: Requests can be passed by value (request) or by reference (request_uri) for enhanced security.
+
+- **JWT Secured Authorization Response Mode (JARM)**: Authorization responses are returned as signed JWTs to ensure authenticity.
+
+- **Client Authentication**: Supports confidential clients using mutual TLS and Private Key JWT.
+
+- **Sender-Constrained Access Tokens**: Access tokens are bound to clients with Mutual TLS (MTLS).
+
+- **Secure Token Handling**: Access and refresh tokens are issued and validated according to FAPI 1.0 Advanced security requirements.
+
+These features protect financial API interactions against interception, forgery, and replay attacks.
+
+{% if is_version == "7.1.0" %}
+## FAPI 2.0 compliance features
+
+{{product_name}} supports FAPI 2.0 security profiles, including Read and Read/Write flows, with the following capabilities:
+
+- **Pushed Authorization Requests (PAR)**: Clients must push authorization requests to the `/par` endpoint, enhancing security by using back-channel communication.
+
+- **Proof Key for Code Exchange (PKCE)**: PKCE with the `S256` code challenge method is mandatory for authorization code flows.
+
+- **Authorization code** - Restrict response type to authorization code.
+
+- **Client Authentication**:  Supports confidential clients using mutual TLS and Private Key JWT.
+
+- **Sender-Constrained Access Tokens**: Access tokens are bound to clients via Mutual TLS (MTLS).
+
+- **Secure Token Handling**: Access and refresh tokens are issued and validated according to FAPI 2.0 Advanced security requirements.
+{% endif %}
+
+{{product_name}} undergoes continuous security reviews and updates. Compliance with the latest FAPI specifications is verified with every release. Cryptographic algorithms and frameworks are updated to meet industry standards. New security features and compliance enhancements are integrated without disrupting existing deployments.
+
+Organizations deploying {{product_name}} can confidently achieve FAPI 1.0 Advanced {% if is_version == "7.1.0" %}and FAPI 2.0{% endif %} compliance, protecting financial data, reducing operational risk, and simplifying regulatory adherence.
diff --git a/en/includes/guides/applications/register-a-fapi-compliant-app.md b/en/includes/guides/applications/register-a-fapi-compliant-app.md
@@ -1,38 +1,155 @@
 # Register a FAPI-compliant application
 
-Financial-Grade API (FAPI) specification is an extension to the OAuth and OIDC frameworks that defines additional technical requirements to enhance API security. This guide explains how you can create a FAPI-compliant application in {{product_name}}.
+Financial-Grade API (FAPI) specification extends the OAuth and OIDC frameworks and defines additional technical requirements to protect high-value APIs. {% if is_version == "7.1.0" %}{{product_name}} provides full support for both [FAPI 1.0 Advanced](https://openid.net/specs/openid-financial-api-part-2-1_0.html){: target="_blank"} and [FAPI 2.0](https://openid.net/specs/fapi-security-profile-2_0-final.html){: target="_blank"} allowing developers to build applications that meet these advanced security standards.{%else%}{{product_name}} provides full support for [FAPI 1.0 Advanced](https://openid.net/specs/openid-financial-api-part-2-1_0.html){: target="_blank"} allowing developers to build applications that meet advanced security standards.{% endif %}
+
+This guide walks you through creating and configuring a FAPI-compliant application in WSO2 Identity Server.
 
 {% if product_name == "WSO2 Identity Server" %}
-## Prerequisites
+## Configure {{product_name}} for FAPI compliance
+
+{{product_name}} supports both FAPI 1.0 Advanced and FAPI 2.0 specifications.
+
+To configure {{product_name}} to issue FAPI-compliant tokens, open the `<IS_HOME>/repository/conf/deployment.toml` file and add the configurations specific to your FAPI version. After saving the changes, restart WSO2 Identity Server to apply the configuration.
 
-Open the `deployment.toml` file found in the `<IS_HOME>/repository/conf/` folder, enter the following configurations and restart the {{product_name}}.
+{% if is_version != "7.1.0" %}
 
 - Limit cipher suites for TLSv1.2.
+
     ```bash
     [transport.https.sslHostConfig.properties]
     ciphers="TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
     ```
+
 - Specify a FAPI-compliant signing algorithm for ID tokens (PS256, ES256).
+
     ```bash
     [oauth.oidc]
     id_token.signature_algorithm="PS256"
     ```
+
 - Specify a signing algorithm for tokens issued at the token endpoint.
+
     ```bash
     [oauth.oidc.token_endpoint]
     signing_algorithms=["PS256","ES256"]
     ```
+
 - Specify a signing algorithm for the userinfo response.
+
     ```bash
     [oauth.oidc.user_info]
     jwt_signature_algorithm="PS256"
     ```
+
 - If your implementation involves TLS termination, specify the following MTLS header name.
+
     ```bash
      [oauth.mutualtls]
      client_certificate_header = "x-wso2-mtls-cert"
     ```
+
+{% else %}
+=== "FAPI 2.0"
+    - Limit cipher suites for TLSv1.2.
+
+        ```bash
+        [transport.https.sslHostConfig.properties]
+        ciphers="TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
+        ```
+
+    - Specify a time skew for JWT token validation.
+        
+        ```bash
+        [oauth]
+        timestamp_skew = 10
+        ```
+
+    - Specify supported FAPI version.
+        
+        ```bash
+        [oauth.oidc]
+        fapi.version= "2"
+        ```
+
+    - Specify the id-token issuer and force using entity id as the issuer in jwt tokens.
+        
+        ```bash
+        [oauth.oidc]
+        id_token.issuer = "https://$ref{server.hostname}:${carbon.management.port}/oauth2/oidcdiscovery"
+        id_token.use_entityid_as_issuer = true
+        ```
+    
+    - Specify a FAPI 2.0 compliant signing algorithm for ID tokens (PS256).
+
+        ```bash
+        [oauth.oidc]
+        id_token.signature_algorithm="PS256"
+        ```
+
+    - Specify the authorization code validity as 50 seconds.
+
+        ```bash
+        [oauth.token_validation]
+        authorization_code_validity = 50
+        ```
+
+    - If your implementation involves TLS termination, specify the following MTLS header name.
+
+        ```bash
+        [oauth.mutualtls]
+        client_certificate_header = "x-wso2-mtls-cert"
+        ```
+
+    - Change the well-known endpoint of the Console and MyAccount applications.
+  
+        ```bash
+        [myaccount.idp_configs]
+        wellKnownEndpoint = "https://<IS_HOST>/oauth2/token/.well-known/openid-configuration"
+
+        [console.idp_configs]
+        wellKnownEndpoint = "https://<IS_HOST>/oauth2/token/.well-known/openid-configuration"
+        ```
+
+=== "FAPI 1.0 Advanced"
+
+    - Limit cipher suites for TLSv1.2.
+
+        ```bash
+        [transport.https.sslHostConfig.properties]
+        ciphers="TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
+        ```
+
+    - Specify a FAPI-compliant signing algorithm for ID tokens (PS256, ES256).
+
+        ```bash
+        [oauth.oidc]
+        id_token.signature_algorithm="PS256"
+        ```
+
+    - Specify a signing algorithm for tokens issued at the token endpoint.
+
+        ```bash
+        [oauth.oidc.token_endpoint]
+        signing_algorithms=["PS256","ES256"]
+        ```
+
+    - Specify a signing algorithm for the userinfo response.
+
+        ```bash
+        [oauth.oidc.user_info]
+        jwt_signature_algorithm="PS256"
+        ```
+
+    - If your implementation involves TLS termination, specify the following MTLS header name.
+
+        ```bash
+         [oauth.mutualtls]
+         client_certificate_header = "x-wso2-mtls-cert"
+        ```
+
+{% endif %}
 {% endif %}
+
 ## Create a FAPI-compliant application
 
 Follow the guides below to create a FAPI-compliant application either using the Console or using Dynamic Client Registration (DCR).
@@ -58,7 +175,6 @@ If you wish to register your application manually using the Console, follow the
 
 6. [Enable the application]({{base_path}}/guides/applications/#enabledisable-an-application) when it is ready for users to log in.
 
-
 ### Use Dynamic Client Registration (DCR)
 
 If you have applications that need to dynamically register with {{product_name}} during runtime, follow the steps below to make them FAPI-compliant.
diff --git a/en/includes/references/financial-grade-api-2.0.md b/en/includes/references/financial-grade-api-2.0.md
diff --git a/en/includes/references/financial-grade-api.md b/en/includes/references/financial-grade-api.md

-Original file line number
+Diff line change
   - SAML
   - JWT
   - UTC
 +  - FAPI
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+{% include "../../../../../includes/deploy/compliance/fapi.md" %}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+{% include "../../../../includes/references/financial-grade-api-2.0.md" %}`