From b0e8b709bae73652dd121e46a276e308f46ba70c Mon Sep 17 00:00:00 2001 From: malithie Date: Tue, 12 Nov 2024 06:46:02 +0530 Subject: [PATCH] Update docs for ERROR and FAILED responses. --- .../api/pre-issue-access-token-action-v1.yaml | 56 ++++++--- .../api/pre-issue-access-token-action-v1.yaml | 55 ++++++--- .../actions/pre-issue-access-token-action | 108 ++++++++++++++++-- 3 files changed, 176 insertions(+), 43 deletions(-) diff --git a/en/asgardeo/docs/references/actions/pre-issue-access-token-action/api/pre-issue-access-token-action-v1.yaml b/en/asgardeo/docs/references/actions/pre-issue-access-token-action/api/pre-issue-access-token-action-v1.yaml index d1937774a9..48b25ddaa5 100644 --- a/en/asgardeo/docs/references/actions/pre-issue-access-token-action/api/pre-issue-access-token-action-v1.yaml +++ b/en/asgardeo/docs/references/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/en/identity-server/next/docs/references/actions/pre-issue-access-token-action/api/pre-issue-access-token-action-v1.yaml b/en/identity-server/next/docs/references/actions/pre-issue-access-token-action/api/pre-issue-access-token-action-v1.yaml index 93dfe2d287..9255ff3b21 100644 --- a/en/identity-server/next/docs/references/actions/pre-issue-access-token-action/api/pre-issue-access-token-action-v1.yaml +++ b/en/identity-server/next/docs/references/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 index d2b9f721d3..8d8ff3e5d1 100644 --- 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: SUCCESS and ERROR. +The response can have three possible states: SUCCESS, FAILEDand ERROR. -SUCCESS: Indicates that the request was processed successfully and includes any state changes or modifications that should be applied. +SUCCESS: Indicates that the request was processed successfully, including any state changes or modifications that need to be applied. -ERROR: 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. +FAILED: 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, ERROR responses are not communicated back to the client, but this functionality is planned for inclusion by end October 2024. +ERROR: 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 FAILED 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 + + + + + + + + + + + + + + + + + + + + + + + +
PropertyDescription
actionStatus

Indicates the outcome of the request. For a failed operation, this should be set to FAILED.

failureReason

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..

failureDescription

Offers a detailed explanation of the failure. This value will be mapped to the error_description field in the /oauth2/token endpoint response.

+ +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 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. +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. Http Status Code: 400, 401 or 500 @@ -396,8 +454,8 @@ Http Status Code: 400, 401 or 500 -error -

The error code, as specified in OAuth 2.0 error response definitions..

+errorMessage +

Describes the cause of the error..

errorDescription @@ -406,7 +464,35 @@ Http Status Code: 400, 401 or 500 -!!! note - Currently, ERROR 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 errorMessage or errorDescription from the external service’s ERROR response is not directly included in the error response sent back to the application.