You can add
check pipelines to request units to perform checks on incoming requests.
check pipelines needs only to explicitly green-light the incoming request, otherwise an error is returned to the caller without executing the main pipeline.
check pipelines can also be used to contribute to the rate limiting and access control features of Xapix.
check pipeline needs to adhere to the following data structure:
result.pass - Boolean, requiredresult.error.body - String, optional; error bodyresult.error.status - Integer, optional; http error status
result.pass is set to false (or undefined), an error is returned to the user. If
result.error.status are set, those are used to create the error response. In case multiple check pipelines fail and provide an error body / status, one of them is picked. It's recommended to always define both, error body and status. If no error body or status is defined, a 401 with the body "Access denied." is returned.
result.pass is set to true for all check pipelines, the request is allowed to proceed.
The check pipeline can also be used to authenticate users, and pass details about the user back to the main pipeline. The result can also be used with the rate limiting and access control features of Xapix.
To use the rate limiting and access control features with check pipelines, you first need to set the user management to custom (see examples section below).
And one of the check pipeline needs to return the following data structure, with
result.pass set to true in case the authorization passed:
result.pass - Boolean, requiredresult.user.id - String; user id to be used for rate limitingresult.user.roles - Array of Strings; roles to be used for access control and rate limiting
result.user.id needs to be unique per user, and will be used to rate limit access as defined in the users' roles.
result.user.roles needs to list the user's roles, which are used to control access and enforce rate limits as defined by those roles. The roles are looked up by their id. If the user has no roles or no matching roles, access will be denied.
For an easy example, let's assume you want to require basic authentication to be present, and otherwise deny access. In that case you could use the following check pipeline:
---version: v1kind: Pipelinemetadata:id: simple-checkproject: simple-checkdefinition:units:- version: v1kind: Unit/Entrymetadata:id: entrydefinition:name: Entryparameters:- name: headertype: objectproperties:- name: Authorizationtype: stringsample: Basic dGVzdDp0ZXN0- version: v1kind: Unit/Resultmetadata:id: resultdefinition:name: Resultinputs:- entryparameters:- name: resulttype: objectproperties:- name: passtype: booleanformula: "entry.header.Authorization = 'Basic dGVzdDp0ZXN0'"
The request pipeline would then look like this:
---version: v1kind: Endpoint/RESTmetadata:id: testproject: simple-checkdefinition:name: testpath: testhttpMethod: getpipeline:units:- version: v1kind: Unit/Requestmetadata:id: requestdefinition:name: Requestparameters:- name: headertype: objectproperties:- name: Authorizationtype: stringcheckPipelines:- simple-check- version: v1kind: Unit/Endpointmetadata:id: endpointdefinition:name: Endpointinputs:- requestparameters:- name: bodytype: objectproperties:- name: statusformula: '"ok"'
checkPipelines in the
Unit/Request resource which references the
simple-check pipeline defined above.
To switch a project to use a custom check pipeline for authentication, and to use rate limiting and access controls, apply the following
ApiPublishing resource definition to switch user management to
---version: v1kind: ApiPublishingmetadata:id: <project-id>definition:enabled: trueuserManagement: custom
Then adjust the check-pipeline above to return