Fix: Add front channel grant flow details to RAR documentation for all affected versions (Product IS issue #26020)

en/includes/guides/authorization/rich-authorization-requests.md

@@ -1,18 +1,18 @@
 # Rich Authorization Requests
 
 Rich Authorization Requests (RAR) ([RFC 9396](https://datatracker.ietf.org/doc/html/rfc9396){:target="_blank"}) enhance authorization mechanisms by allowing clients to specify fine-grained authorization details in a structured format. 
 This guide outlines how to configure your application for RAR, authorize API resources, customize authorization validation, and obtain tokens with authorization details.
 
 ## Configuring your application for RAR
 You can go through the following steps to prepare your application for rich authorization requests.
 
 ### Step 1: Register a new authorization details type
 
 Before using RAR, you need to define the authorization details types that your application supports. 
 This involves registering an authorization details types using the [API Resource Management Rest API]({{base_path}}/apis/api-resource-management-rest-api/).
 (The `authorizationDetailsTypes` field in the request payload follows the JSON Schema Draft 2020-12 standard.)
 
 The following sample request registers a new authorization details types named `payment_initiation` for a Payments API 
 and the response contains details of the newly registered API resource and its authorization details types.
 This payload's schema can be referenced as a representation of [Figure 1](https://datatracker.ietf.org/doc/html/rfc9396#figure-1) in the RAR specification.
 
@@ -101,7 +101,7 @@
     }
     ```
 
 Once registered, to retrieve the supported authorization details types, invoke the discovery endpoint of {{product_name}}. 
 The response confirms that the `payment_initiation` authorization details type is registered and available for use.
 
 === "Sample request (/openid-configuration)"
@@ -147,15 +147,15 @@
     ```
 
 === "Sample response (/authorized-apis)"
 
     ```curl
     HTTP/1.1 200 OK
     ```
 
 ### Step 3: (Optional) Customize authorization details validation
 
 By default, {{product_name}} validates authorization details against the registered authorization details type schema. 
 However, if additional validation is required, you can extend the `org.wso2.carbon.identity.oauth2.rar.core.AuthorizationDetailsProcessor` 
 Java interface and provide mechanisms to validate, enrich, and identify authorization details specific to your type.
 To execute your custom validation, create a JAR file with your implementation and place it in `<IS_HOME>/repository/components/lib` directory and restart the server.
 
@@ -163,14 +163,14 @@
 
 ```java
 ValidationResult validate(AuthorizationDetailsContext authorizationDetailsContext) throws AuthorizationDetailsProcessingException, IdentityOAuth2ServerException;
 ```
 `validate` method is invoked once a new Rich Authorization Request is received to ensure that the
 authorization details are valid and meet the required criteria. The validation logic should
 be specific to the type of authorization details handled by the implementing class.
 
 ```java
 String getType();
 ```
 `getType` method used to retrieve the type of authorization details handled by this processor. Each implementation should return a unique type identifier that represents the kind of
 authorization details it processes
 
@@ -323,9 +323,78 @@
 
 The client application can now retrieve the user's payment information from the resource server by including the obtained access token in the request.
 
+### Sample authorization code grant flow
+
+The authorization code grant is a front channel grant that requires user interaction and consent. This section describes how to use rich authorization requests with the authorization code flow.
+
+#### Step 1: Initiate authorization request
+
+The client initiates an authorization request to the authorization endpoint with the `authorization_details` parameter. The request includes the url-encoded `payment_initiation` authorization details type.
+
+=== "Sample request (/authorize)"
+
+    ```bash
+    https://localhost:9443/oauth2/authorize?response_type=code&client_id=<clientID>&redirect_uri=<redirectURI>&scope=openid&authorization_details=%5B%7B%22type%22%3A%22payment_initiation%22%2C%22actions%22%3A%5B%22initiate%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample.com%2Fpayments1%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22%3A%22USD%22%2C%22amount%22%3A%223000.00%22%7D%2C%22creditorName%22%3A%22Merchant%20A%22%2C%22creditorAccount%22%3A%7B%22iban%22%3A%22%22%7D%7D%5D
+    ```
+
+The user authenticates and provides consent for the requested authorization details. After consent, the authorization server redirects to the specified redirect URI with an authorization code.
+
+=== "Sample response (/authorize)"
+
+    ```bash
+    <redirectURI>?code=<authorizationCode>&session_state=<sessionState>
+    ```
+
+#### Step 2: Exchange authorization code for access token
+
+The client exchanges the authorization code for an access token by sending a request to the token endpoint.
+
+=== "Sample request (/token)"
+
+    ```bash
+    curl --location 'https://localhost:9443/oauth2/token' \
+    --header 'Content-Type: application/x-www-form-urlencoded' \
+    --header 'Authorization: Basic <base64EncodedClientCredentials>' \
+    --data-urlencode 'grant_type=authorization_code' \
+    --data-urlencode 'code=<authorizationCode>' \
+    --data-urlencode 'redirect_uri=<redirectURI>'
+    ```
+
+=== "Sample response (/token)"
+
+    ```json
+    {
+      "access_token": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
+      "refresh_token": "z9y8x7w6-v5u4-t3s2-r1q0-p9o8n7m6l5k4",
+      "authorization_details": [
+        {
+          "locations": [
+            "https://example.com/payments1"
+          ],
+          "instructedAmount": {
+            "currency": "USD",
+            "amount": "3000.00"
+          },
+          "type": "payment_initiation",
+          "creditorName": "Merchant A",
+          "actions": [
+            "initiate"
+          ],
+          "creditorAccount": {
+            "iban": "c6142dc9-588c-49ec-8341-1b157c441d02"
+          }
+        }
+      ],
+      "token_type": "Bearer",
+      "expires_in": 3600
+    }
+    ```
+
+The client application can now retrieve the user's payment information from the resource server by including the obtained access token in the request.
+
 ### Validate the access token
 
 To verify if an access token is valid and check its associated authorization details, invoke the token introspection endpoint.
 If the token is active, the response will include its associated authorization details.
 
 === "Sample request (/introspect)"