Disabling adding REST services without OpenAPI declaration

Owned by Allan Bernard
Last updated: Oct 14, 2023
3 min read

The purpose of this change is to allow the enforcement of an OpenAPI specification for registering a subsystem using REST principles in X-Road (like the PubSub component). Without this change a REST subsystem could be registered without providing it’s declaration.

This change will directly affect the code of NIIS X-Road 7.x and implemented in that, preferably included in the upstream as a pull request but if needed by forking the released version. All changes are backwards compatible.

 

Solution 

Currently the Security Server supports adding two types of REST services, REST and OPENAPI3 within the proxy-ui-api module. For us to enable the possibility for the Security Server admin to prevent the adding of services without specification, the simplest and most straight-forward solution is to create a system property that, if turned on, will disable the the functionality of adding (plain) REST service.

To achieve this:

  1. A new property (e.g. 'proxy-ui-api.disable-rest-service-type') with the default value of 'false' is added as an optional system property.

  2. The value of the property will be checked in the method that adds a new REST service and an exception is thrown if the property is 'true' (meaning adding REST services is disabled).

  3. The value will not be checked during (and hence the solution will not affect the process of) adding a new OPENAPI3 service.

  4. The Security Server UI will be amended to be aware of the property value.

    1. Currently the system displays 'URL type' radio button selection with two options 'REST API Base Path' and 'OpenAPI 3 Description).

    2. Since if the property is set to 'true' the 'URL type' selection would become redundant (with just one option) it should be hidden an the label of URL insert text box renamed to 'Open API 3 description URL'

 

For GovStack specific configuration meta package (similar to current country based packages) is added that, if applied, will override that default value.

 

As a result there will exist a system property for allowing only OPENAPI3 services to be added, that can be automatically loaded and enabled when GovStack IM-BB is deployed.

 

Manual control of the variable

The fact that Security Server Administrator can disable/enable the feature or modify the installation scripts to not include the GovStack meta package is known and intentional. This is intended to provide backwards compatibility with existing x-road implementations and allow for the GovStack IM-BB to be applied in those systems if needed.

Furthermore, currently all services deployed within a subsystem have the service description available, regardless whether someone is authorized to use the service or not. So even though a policy of requiring OpenAPI declarations can be established and Security Server Admins required to keep plain REST services disabled, exceptions can be made if needed (for example for law enforcement or security related members).

GovStack IM-BB will not verify whether or not the feature is disabled or enabled, nor will it verify whether or not the OpenAPI declaration (if required) matches the endpoints the service actually exposes. All these concerns should be addressed as separate processes if needed when implementing the IM-BB as they are not strictly relevant in terms of the interoperability framework but rather in terms of services themselves.