OpenAPI specification

Download OpenAPI specification (OAS) of the complete Loginapp REST API in JSON format from here:
login-rest-openapi-7.7.7.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 REST 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.

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

Since all HTTP calls are validated against the OAS, the document is only applicable for mappings that are restricted to Loginapp REST calls. If separate mappings are in place for the protected and public REST API parts, the same OAS document should be referenced from both. Mappings that combine REST and non-REST traffic, which were previously shipped with IAM, have to be split first.

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