Workflow authentication (API gateway)

Edit online

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. This process is the 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 the auth workflow is deployed, navigate to Application settings, then 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, the 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 the API gateway, for this reason, there are various 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 API 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

The Authentication flow has access to system values through predefined names of input variables. These variables are:

Table 1. Implicit input variables
Name	Description	Type	Required/Optional
`application`	The name of the application.	String	Optional
`stage`	The current stage.	String	Optional
`method`	The API method.	String	Optional
`path`	The path that is used to run the flow.	String	Optional

If an input variable that has the same name as one of these system values 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:

Table 2. Implicit output variables
Name	Description	Type	Required/Optional
`success`	Required if the authentication is successful and the business flow should run.	Boolean	Required
`userName`	The authenticated user's username.	String	Optional
`authorities`	The authenticated user's authorities.	String or string array	Optional
`context`	A single object, containing both the user name and the authorities.	An object of {userName, authorities}	Optional

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 in the following section). 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 user, which owns the application, and authorities property contains a list of the 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 a custom response configuration section that enables the API gateway to return a custom view over the whole response. In order to facilitate quick development, the API gateway uses implicit mapping of output variables (if present), that follows the rules of the custom response configuration:

Table 3. Implicit response configuration variables
Name	Description	Type	Required/Optional
`responseBody`	Contains the body for the response.	Any	Optional
`responseFormat`	One of `JSON`, `STRING`, or `BINARY`, Defaults to `JSON`.	String	Optional
`responseContentType`	Specifies the content type of the result. If present overrides `Content-Type` header in the returned `responseHeaders`.	String	Optional
`responseHeaders`	Returns the headers for the response.	Object	Optional
`responseStatusCode`	Specifies the status code of the response.	Number	Optional

Explicit custom response configuration mapping overrides the implicit one. Note, that response configuration for headers and content type is enabled only when the ENABLE_INSECURE_MAPPINGS environment variable is set on both frontend and app-gateway deployments with the value of 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, the 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 (that is, unauthorized) is returned in the response.