OpenAPI specification

Download OpenAPI specification (OAS) of the complete Loginapp REST API in JSON format from here:
login-rest-openapi-8.2.4.json.

The document covers both the public and protected part of the Loginapp REST API. The specification defines the minimum requirements that all REST calls have to meet to constitute valid API usage. The OAS is a static resource that is independent of the configuration of IAM. As such it includes all endpoints that are potentially available for the full feature set of IAM.

Limitations

The following limitations apply:
The OAS is provided as a security feature to allow Airlock Gateway to protect Airlock IAM against fraudulent requests to the Loginapp REST API. It is not intended as a Swagger resource or official API documentation of the Loginapp. The contained operation IDs are subject to change.
The OAS contains endpoint specifications that are intended for use by the Loginapp UI exclusively. These endpoints may change without prior notice and are therefore not suitable for other purposes.
The OAS enforces security on all requests. Responses returned by Airlock IAM are implicitly trusted and not filtered. Therefore, response schemas are not restricted by the OAS.

Refer to Loginapp REST API Reference for the documentation of the published Loginapp REST API.

Note that the API enforcement must be licensed separately on Airlock Gateway.

There are the following options:
Assure the feature is licensed and enabled in Airlock Gateway
Disable the feature in Airlock Gateway and delete the corresponding mappings imported with the IAM mapping template files.

OpenAPI validation using Airlock Gateway

The OAS document can be used with the OpenAPI Validation feature of Airlock Gateway to enforce an upstream validation of all Loginapp REST calls.

Preparation of OpenAPI specification document

Airlock Gateway matches the front-end path of requests against the specified endpoint paths. The default OAS document assumes the Loginapp REST API to be deployed at the front-end path /auth/rest. Therefore, if the mapping is configured differently, the provided OAS document has to be adapted first.

For this, change the JSON property url under servers accordingly:

copy

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

Enabling API enforcement

Upload the resulting OAS document in the Airlock Gateway Configuration Center on the central API security page under:
Application Firewall >> API Security

Mappings for which the Loginapp REST API should be enforced can then be configured in the tab API Security as follows:
Enable Enforce API
Reference the uploaded OAS document under API
Do not enable Offer API specification file publicly, as it also contains unpublished endpoints.

Because all HTTP requests are validated against the OAS, the document is only applicable for mappings that are exclusively used for Loginapp REST calls.

The same OAS document should be referenced from both the public and the protected Loginapp REST mappings.

Validation of error responses

When the Loginapp REST API is accessed without upstream OpenAPI validation, IAM validates the JSON content of the request. Schema violations result in an error response status code 400 potentially containing a pointer and meta information detailing the violation.

For instance, a request that is missing the required property username results in:

copy

{
    "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"
            }
        }
    ]
}

When upstream OpenAPI validation is enabled, violating REST requests are blocked by Airlock Gateway before they reach IAM.

As a consequence, the REST client receives a generic response indicating that the request has been blocked, such as:

copy

<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>

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