Merge pull request #4853 from malithie/actions-docs

Update docs for ERROR and FAILED responses.
wso2 · Nov 12, 2024 · ccbe5b4 · ccbe5b4
2 parents bb05fd9 + b0e8b70
commit ccbe5b4
Show file tree

Hide file tree

Showing 3 changed files with 176 additions and 43 deletions.
diff --git a/...eferences/actions/pre-issue-access-token-action/api/pre-issue-access-token-action-v1.yaml b/...eferences/actions/pre-issue-access-token-action/api/pre-issue-access-token-action-v1.yaml
@@ -24,15 +24,26 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/SuccessResponse'
-              example:
-              - actionStatus: SUCCESS
-                operations:
-                  - op: add
-                    path: /accessToken/claims/-
-                    value:
-                      name: customSID
-                      value: "12345"
+                oneOf:
+                  - $ref: '#/components/schemas/SuccessResponse'
+                  - $ref: '#/components/schemas/FailedResponse'
+              examples:
+                successExample:
+                  summary: Success response
+                  value:
+                    actionStatus: SUCCESS
+                    operations:
+                      - op: add
+                        path: /accessToken/claims/-
+                        value:
+                          name: customSID
+                          value: "12345"
+                failedExample:
+                  summary: Failed response
+                  value:
+                    actionStatus: FAILED
+                    failureReason: invalid_scope
+                    failureDescription: "The requested scope is invalid, unknown, or malformed."
         "400":
           description: Bad Request
           content:
@@ -41,7 +52,7 @@ paths:
                 $ref: '#/components/schemas/ErrorResponse'
               example:
               - actionStatus: ERROR
-                error: invalid_request
+                errorMessage: invalid_request
                 errorDescription: SID claim is missing
         "500":
           description: Server Error
@@ -51,7 +62,7 @@ paths:
                 $ref: '#/components/schemas/ErrorResponse'
               example:
               - actionStatus: ERROR
-                error: server_error
+                errorMessage: server_error
                 errorDescription: Failed to process the response
 components:
   schemas:
@@ -282,6 +293,20 @@ components:
           items:
             $ref: '#/components/schemas/Operations'
       description: Defines the success response.
+    FailedResponse:
+      type: object
+      properties:
+        actionStatus:
+          type: string
+          enum:
+          - FAILED
+          description: Indicates the outcome of the request. For a failed operation, this should be set to FAILED.
+        failureReason:
+          type: string
+          description: Provides the reason for failing to issue an access token.
+        failureDescription:
+          type: string
+          description: Offers a detailed explanation of the failure.
     ErrorResponse:
       type: object
       properties:
@@ -290,16 +315,15 @@ components:
           enum:
           - ERROR
           description: Indicates the outcome of the request. For an error operation, this should be set to ERROR.
-        error:
+        errorMessage:
           type: string
-          description: The error code, as specified in OAuth 2.0 error response definitions.
+          description: The cause of the error.
         errorDescription:
           type: string
           description: A detailed description of the error.
       description: |
-        When the external service responds with an ERROR state, it can return an HTTP status code of 400, 401, or 500, indicating that the expected validations are not met or there is an issue processing the request. 
-        
-        If the defined error response is not received, or if the external service fails to respond, this is identified as an error in executing the action. In such cases, the flow will proceed as if the action was not applied, ensuring that the process continues without disruption.
+        When the external service responds with an ERROR state, it can return an HTTP status code of 400, 401, or 500, indicating either a validation failure or an issue processing the request. 
+
     RequestBody:
       type: object
       properties:

diff --git a/...eferences/actions/pre-issue-access-token-action/api/pre-issue-access-token-action-v1.yaml b/...eferences/actions/pre-issue-access-token-action/api/pre-issue-access-token-action-v1.yaml
@@ -30,15 +30,26 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/SuccessResponse'
-              example:
-              - actionStatus: SUCCESS
-                operations:
-                  - op: add
-                    path: /accessToken/claims/-
-                    value:
-                      name: customSID
-                      value: "12345"
+                oneOf:
+                  - $ref: '#/components/schemas/SuccessResponse'
+                  - $ref: '#/components/schemas/FailedResponse'
+              examples:
+                successExample:
+                  summary: Success response
+                  value:
+                    actionStatus: SUCCESS
+                    operations:
+                      - op: add
+                        path: /accessToken/claims/-
+                        value:
+                          name: customSID
+                          value: "12345"
+                failedExample:
+                  summary: Failed response
+                  value:
+                    actionStatus: FAILED
+                    failureReason: invalid_scope
+                    failureDescription: "The requested scope is invalid, unknown, or malformed."
         "400":
           description: Bad Request
           content:
@@ -47,7 +58,7 @@ paths:
                 $ref: '#/components/schemas/ErrorResponse'
               example:
               - actionStatus: ERROR
-                error: invalid_request
+                errorMessage: invalid_request
                 errorDescription: SID claim is missing
         "500":
           description: Server Error
@@ -57,7 +68,7 @@ paths:
                 $ref: '#/components/schemas/ErrorResponse'
               example:
               - actionStatus: ERROR
-                error: server_error
+                errorMessage: server_error
                 errorDescription: Failed to process the response
 components:
   schemas:
@@ -288,6 +299,20 @@ components:
           items:
             $ref: '#/components/schemas/Operations'
       description: Defines the success response.
+    FailedResponse:
+      type: object
+      properties:
+        actionStatus:
+          type: string
+          enum:
+          - FAILED
+          description: Indicates the outcome of the request. For a failed operation, this should be set to FAILED.
+        failureReason:
+          type: string
+          description: Provides the reason for failing to issue an access token.
+        failureDescription:
+          type: string
+          description: Offers a detailed explanation of the failure.
     ErrorResponse:
       type: object
       properties:
@@ -296,16 +321,14 @@ components:
           enum:
           - ERROR
           description: Indicates the outcome of the request. For an error operation, this should be set to ERROR.
-        error:
+        errorMessage:
           type: string
-          description: The error code, as specified in OAuth 2.0 error response definitions.
+          description: The cause of the error.
         errorDescription:
           type: string
           description: A detailed description of the error.
       description: |
-        When the external service responds with an ERROR state, it can return an HTTP status code of 400, 401, or 500, indicating that the expected validations are not met or there is an issue processing the request. 
-        
-        If the defined error response is not received, or if the external service fails to respond, this is identified as an error in executing the action. In such cases, the flow will proceed as if the action was not applied, ensuring that the process continues without disruption.
+         When the external service responds with an ERROR state, it can return an HTTP status code of 400, 401, or 500, indicating either a validation failure or an issue processing the request. 
     RequestBody:
       type: object
       properties:

diff --git a/en/includes/guides/customize/actions/pre-issue-access-token-action b/en/includes/guides/customize/actions/pre-issue-access-token-action
@@ -338,14 +338,13 @@ When {{product_name}} invokes your external service as part of the pre-issue acc
 
 This response plays a crucial role in determining how the access token is ultimately issued or modified. Here’s a breakdown of the expected response:
 
-The response can have two possible states: <code>SUCCESS</code> and <code>ERROR</code>.
+The response can have three possible states: <code>SUCCESS</code>, <code>FAILED</code>and <code>ERROR</code>.
 
-<code>SUCCESS</code>: Indicates that the request was processed successfully and includes any state changes or modifications that should be applied.
+<code>SUCCESS</code>: Indicates that the request was processed successfully, including any state changes or modifications that need to be applied.
 
-<code>ERROR</code>: Indicates a failure in processing, accompanied by an error message that should be communicated to the application. This error message should adhere to OAuth 2.0 error response definitions to ensure compliance. However, it is your responsibility to ensure this compliance when extending the flow.
+<code>FAILED</code>: Represents a selective failure within the token flow due to validation logic or business rules enforced by your external service. A 400 (Client Error) response is returned to the application, incorporating the failure message provided by your external service. It is your responsibility to supply an OAuth 2.0-compliant failure message when extending the flow.
 
-!!! note
-    Currently, <code>ERROR</code> responses are not communicated back to the client, but this functionality is planned for inclusion by end October 2024.
+<code>ERROR</code>: Indicates a processing failure, typically caused by server-side issues. A 500 (Server Error) response is returned to the application.
 
 #### Response for SUCCESS state:
 
@@ -376,9 +375,68 @@ Http Status Code: 200
 !!! tip
     Refer the [sample responses for successful access token updates]({{base_path}}/references/actions/pre-issue-access-token-action/sample-success-responses/) to learn how to construct success responses for different scenarios.
 
+#### Response for FAILED state:
+
+When the external service returns a 200 OK status code with a <code>FAILED</code> state, it means the service has intentionally opted to prevent access token issuance. This decision is based on specific validation logic or business rules defined by your application's requirements.
+
+The response body must be a JSON object containing the following properties:
+
+Http Status Code: 200
+
+<table>
+<thead>
+<tr class="header">
+<th>Property</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr class="odd">
+<td>actionStatus</td>
+<td><p>Indicates the outcome of the request. For a failed operation, this should be set to <code>FAILED</code>.</p></td>
+</tr>
+</tr>
+<tr class="even">
+<td>failureReason</td>
+<td><p>Provides the reason for failing to issue an access token. This value will be mapped to the error field in the response returned from the /oauth2/token endpoint.</code>.</p></td>
+</tr>
+<tr class="odd">
+<td>failureDescription</td>
+<td><p>Offers a detailed explanation of the failure. This value will be mapped to the error_description field in the <code>/oauth2/token</code> endpoint response.</p></td>
+</tr>
+</tbody>
+</table>
+
+Below is an example of a failed response due to invalid scopes in the access token request.
+
+Response from external service:
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "actionStatus": "FAILED",
+  "failureReason": "invalid_scope",
+  "failureDescription": "Scope platinum_state is invalid"
+}
+```
+
+This will result in the following error response being sent to the application that initiated the token request.
+
+Error response to the application:
+```http
+HTTP/1.1 400 
+Content-Type: application/json
+
+{
+  "error": "invalid_scope",
+  "error_description": "Scope platinum_state is invalid"
+}
+```
+
 #### Response for ERROR state:
 
-When the external service responds with an <code>ERROR</code> state, it can return an HTTP status code of 400, 401, or 500, indicating that the expected validations are not met or there is an issue processing the request.
+When the external service responds with an <code>ERROR</code> state, it can return an HTTP status code of 400, 401, or 500, indicating either a validation failure or an issue processing the request. 
 
 Http Status Code: 400, 401 or 500
 
@@ -396,8 +454,8 @@ Http Status Code: 400, 401 or 500
 </tr>
 </tr>
 <tr class="even">
-<td>error</td>
-<td><p>The error code, as specified in OAuth 2.0 error response definitions.</code>.</p></td>
+<td>errorMessage</td>
+<td><p>Describes the cause of the error.</code>.</p></td>
 </tr>
 <tr class="odd">
 <td>errorDescription</td>
@@ -406,7 +464,35 @@ Http Status Code: 400, 401 or 500
 </tbody>
 </table>
 
-!!! note
-    Currently, <code>ERROR</code> responses are not communicated back to the client, but this functionality is planned for inclusion by end October 2024.
+If the external service returns an error response (either defined or undefined) or fails to respond entirely, it will be treated as an error in executing the action. In any of these cases, the application that initiated the token request will receive a 500 Internal Server Error.
+
+Below is an example of an error response returned by the service implementing the pre issue access token action.
+
+Response from external service:
+```http
+HTTP/1.1 500
+Content-Type: application/json
+
+{
+  "actionStatus": "ERROR",
+  "errorMessage": "Server error",
+  "errorDescription": "Error while processing request."
+}
+```
+
+This will result in the following error response being sent to the application that initiated the token request.
 
-If the defined error response is not received, or if the external service fails to respond, this is identified as an error in executing the action. In such cases, the flow will proceed as if the action was not applied, ensuring that the process continues without disruption.
+Error response to the application:
+```http
+HTTP/1.1 500 
+Content-Type: application/json
+
+{
+  "error":”server_error",
+  "error_description": "Internal Server Error."
+}
+
+```
+
+!!! note
+    Currently, the <code>errorMessage</code> or <code>errorDescription</code> from the external service’s <code>ERROR</code> response is not directly included in the error response sent back to the application.