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 leave this feature disabled.

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 followong front-end paths:

  • Loginapp: /auth/rest
  • Adminapp: /auth-admin/rest
  • Transaction Approval: /auth-transaction-approval/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 the code snippet below (which shows the default setting for the Loginapp).

 
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 in each module's basic mapping template:
    1. In the Configuration Center, go to
      Application Firewall >> Reverse Proxy
    2. Open the detail page of the basic mapping for which you want to enable API validation.
    3. In the mapping's detail page, open the API Security tab.
    4. Go to the OpenAPI section and configure it as follows:
    5. Tick the ON radio button to enable OpenAPI spec enforcement.
    6. In the Entry path (first match only) field, enter a pattern that matches the full request path - for example ^%ENTRYDIR%/rest/.*.
    7. In the API field, reference the OAS document relevant for this module. For example, login-rest-openapi-8.5.0.json for the Loginapp mapping.
    8. The Gateway mapping can be configured to rewrite the incoming URL to a different back-end URL (asymmetric mappings). Because of this rewriting, the URL path seen by the client (Client view) may differ from the one sent to the back-end (Back-end view). In the Path Matching field, select Client view to ensure the URL path matches the definitions in the API specification (which are typically written from the client perspective).
    9. After enabling OpenAPI, REST requests are automatically validated against the OpenAPI specifications. To also validate responses, select either Strict or Lax in the Check responses field.
      • Strict: Validation will fail if a response is not declared in the specification.
      • Lax: Undeclared responses are not validated.
    11.  
      Functional limitation

      Currently, IAM only supports the Lax option.

    12. 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. The code block below shows an example response:

 
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. If the JSON violates the schema, the system typically responses with an error that includes a pointer and meta information about the violation.

For example, a request to the Loginapp REST API 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.