OpenAPI specification and validation

This article provides the OpenAPI Specifications (OAS) in JSON format for the REST APIs of the IAM modules Loginapp, Adminapp and Transaction Approval.

The OAS documents can be used with the API Security feature of Airlock Gateway to enforce an upstream validation of all REST calls to and from the respective IAM module.

Download the OpenAPI specification (OAS) from here: 

Each OAS document contains specifications for REST requests as well as responses. It covers both the public and the protected part of the respective REST API. The specification defines the requirements all REST calls must meet to constitute valid API usage. The OAS includes all endpoints that are potentially available for the full feature set of IAM, independent of the actual configuration of IAM.

 
Notice

API enforcement must be licensed separately and enabled explicitly in Airlock Gateway. If you do not want to use API enforcement, you could disable this feature in Airlock Gateway and delete the corresponding mappings imported with the IAM mapping template files.

Limitations

Some specifications in each OAS refer to “internal” endpoints, which are exclusively used by the UIs of the Loginapp, Adminapp or the Transaction Approval module, respectively. These internal endpoints may change without prior notice and are therefore not suitable for other purposes. In the OAS file, internal endpoints are identified by the extension “x-internal”: “true”.

Preparation of the OpenAPI specification document

Airlock Gateway matches the front-end path of requests against the specified endpoint paths.

The default OAS documents assume that the REST APIs are deployed on the front-end path /auth/rest. If the mapping in your setup is configured differently, adjust the provided OAS documents accordingly. To do this, change the JSON property servers >> url to match your mapping. See also the code snippet below (which shows the default setting).

 
Example
...
"servers": [
{
  "url": "/auth/rest"
}
],
...

Enabling API enforcement in Airlock Gateway

This section explains how to enable API enforcement in Airlock Gateway. You do this in the Airlock Gateway Configuration Center.

Proceed as follows:

  1. Upload the required OAS documents onto the central API security page in the Configuration Center:
    1. In the Configuration Center, go to
      Application Firewall >> API Security
    2. In section OpenAPI Specification, upload the OAS documents.
  3. Next, enforce OpenAPI validation per mapping:
    1. In the Configuration Center, go to
      Application Firewall >> Reverse Proxy
    2. Open the detail page of each mapping for which you want to enable API validation.
    3.  
      Notice

      Because all HTTP requests are validated against OpenAPI by default, enabling API validation is only necessary for mappings that are exclusively used for REST calls.

    4. In the mapping's detail page, go to the OpenAPI section.
    5. Enable the Enforce API property.
    6. In the API field, reference the OAS document relevant for this mapping.
    7.  
      Notice

      Per IAM module, reference the same OAS document for both the public and the protected REST mappings.

    8. REST requests are checked against the OpenAPI specifications by default after enabling Enforce API. To also check the responses, enable Check responses against API specification.
    9. Do not enable Offer API specification file publicly, as the OAS documents also contain unpublished endpoints.
  5. Activate your configuration.
  6. You have now enabled OpenAPI validation in Airlock Gateway for all relevant mappings.

Validation of error responses

When OpenAPI validation is enabled in Airlock Gateway, violating REST requests are blocked by Gateway before they reach IAM. In this case, the REST client receives a generic response indicating that the request has been blocked. For an example of such a response, see the code block below:

 
Example
<html>
<head>
	<base href="/error_path/">
	<title>400 Bad Request</title>
</head>
<body>
	<h1>Bad Request</h1>
	<p>The server detected a syntax error in your request.<br>
Check your request and all parameters.</p>
		<p>Your request ID was: XbcYL8Wv5f1DSaXz@-pn9gAAAO4</p>
</body>
</html>

When the REST API of an IAM module is accessed without upstream OpenAPI validation, IAM validates the JSON content of the request. Schema violations result in an error response status code 400. The error response typically includes a pointer and meta information about the violation.

For example, a request to the Loginapp REST API that is missing the required property username results in the following error message:

 
Example
{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2019-10-28T17:24:25.913+01:00"
    },
    "errors": [
        {
            "code": "VALIDATION_FAILED",
            "source": {
                "pointer": "/username"
            },
            "meta": {
                "type": "jsonapi.metadata.validation.error",
                "detail": "REQUIRED"
            }
        }
    ]
}

In general, REST clients should never send REST requests that violate the OAS, let alone rely on a specific REST response in such cases.