Workflow Authentication (API Gateway)
One of the authentication mechanisms of API Gateway is Workflow Authentication. It allows us to execute an auxiliary workflow that decides whether to run the main workflow of a deployment. We call this extra workflow authentication workflow.
Before the Gateway can run the authentication workflow, it must be deployed, like any regular workflow. The deployment of auth flow does not differ from the deployment of a regular flow. It is up to the designer of the API if the auth deployment will be in the same stage as the business deployments or if all the auth deployments will be in separate stage/stages.
Configuring Workflow Authentication
After auth workflow is deployed, navigate to Application settings, Authentications, choose Workflow, and then choose the stage and endpoint, onto which the auth workflow was deployed. If the chosen stage is “Current" then in runtime, flow from the current stage deployed on the selected endpoint will be executed. If there is no deployment on the selected stage and endpoint, then API Gateway fails as if it could not find deployment of the main business flow, with status code 404. The GUI displays a warning if auth workflow is not deployed on the selected stage/endpoint pair.
Authentication workflow interface
The auth workflow plugs into the request processing chain of Pliant APP Gateway, for this reason, there are a number of predefined input and output parameters and predefined behavior of the flow. If the authentication flow completes successfully, then the business flow is executed with eventually overridden user credentials. If it completes unsuccessfully, then its response mapping is used to produce the result of the execution.
Input variables
The values of the input variables are retrieved based on the method of the mapping endpoint. For GET and DELETE methods, input variables are mapped from the query string parameters. For POST, PUT and PATCH methods, input variables are mapped from the body of the request (interpreted as a JSON object).
Note, that here the method is used only to choose where the auth flow gets its inputs from. You can deploy a business flow to POST /hello endpoint and guard it with auth flow, deployed on GET /auth endpoint. In that case, the input of the hello flow will be mapped from the body, while the inputs of the auth flow will be mapped from the query parameters of the request.
The APP Gateway honors the wrap headers and wrap body system variables. This feature can be used when the flow needs access to the headers or to system variables and parameters with the same name, as described later.
Implicit input variables
Auth flow has access to system values through predefined names of input variables. These variables are:
application: string, optional - the name of the applicationstage: string, optional - the current stagemethod: string, optional - the methodpath: string, optional - the path, that is used to run the flow
All of these system values are of type string and if an input variable of the same name is defined in the flow, then the system value will be provided in it. System values will override values from the query string or body, so if auth flow wants to access both the application name of the current API and the query parameter named “application", then it must use the wrap body option and access the query parameter as body.applcation.
Implicit output variables
Auth flow has a set of output variables, through which it controls the execution of the business flow:
success: boolean, required - if the authentication is successful and the business flow should runuserName: string, optional - the authenticated user's usernameauthorities: string or string[], optional - the authenticated user's authoritiescontext: an object of {userName, authorities}, optional - a single object, containing both the user name and the authorities
The most important implicit output variable is success. If it is not present in the response or has a falsy value, it is considered that the authentication is unsuccessful, otherwise, the authentication is successful.
Upon successful authentication, the business flow is executed with eventually overridden user credentials (as described below). On unsuccessful authentication, the business flow is not executed and auth flow’s response mapping (using the implicit response configuration or the explicit Custom response configuration from the deployment) is used to produce the result of the execution.
The Common integration contains a Context block, whose purpose is to provide information about the running flow as well as which user runs it. Normally when flows are executed from the Gateway, the context user is the Pliant user, which owns the application, and authorities property contains a list of the Pliant roles of that user. Authentication flow may override the userName and the authorities that are returned from the Context block. If the context output variable is present in the response of the flow, then its properties are propagated to the Context block. If the context output variable does not exist, but any of userName or authorities output variables are present, then a new context object is created. userName and authorities output variables, if present, override the values of the context output variable (even if their value is null or falsy).
Implicit response configuration
Deployments contain Custom Response Configuration section that enables API Gateway to return a custom view over the whole response. In order to facilitate quick development, API Gateway uses implicit mapping of output variables (if present), that follows the rules of the Custom Response Configuration:
responseBody: any, optional - contains the body for the response.responseFormat: string, optional, one of 'JSON', 'STRING', 'BINARY', defaults to 'JSON'.responseContentType: string, optional - specifies the content type of the result. If present overridesContent-Typeheader in the returnedresponseHeaders.responseHeaders: object, optional - returns the headers for the response.responseStatusCode: number, optional - specifies the status code of the response.
Explicit Custom Response Configuration mapping overrides the implicit one. Note, that response configuration for headers and content type is enabled only when ENABLE_INSECURE_MAPPINGS environment variable is set on both frontend and app-gateway deployments with value "1".
Error handling
If the auth flow throws an error, then the business flow is not executed and the response contains the whole response from auth flow (quite similar to handling errors from the business flow). In this case, API Gateway honors the Error Status Code deployment configuration. If no Error Status Code is set in the auth deployment, a default value of 401 (Unauthorized) is returned in the response.