The Natural OpenAPI Server provides configuration options to secure communication:

• between the Natural OpenAPI server and the Subprogram Server.

• between the client and the Natural OpenAPI Server.

This document covers the following topics:

• Secure Communication between Natural OpenAPI Server and Subprogram Server

• Secure Communication between Client and Natural OpenAPI Server

• Authentication

---

Secure Communication between Natural OpenAPI Server and Subprogram Server

The Natural OpenAPI Server can use SSL/TLS to encrypt communication between the Natural OpenAPI Server and the subprogram servers.

SSL/TLS can be enabled using the following property:

com.softwareag.natural.openapi.server.config.host.ssl.enabled=true

When SSL/TLS is enabled, the server uses the configured certificate chain to establish secure connections. The certificate can be configured using the certsChain property:

com.softwareag.natural.openapi.server.config.host.ssl.certsChain[0]=classpath:natsubsrv.server.cert.crt

The property specifies the location of the server certificate. The classpath: prefix indicates that the certificate is loaded from the application's classpath.

Multiple certificates can be specified as part of the certificate chain by using additional indexed properties, for example, certsChain[1], certsChain[2], and so on.

Secure Communication between Client and Natural OpenAPI Server

The Natural OpenAPI Server supports secure communication using SSL/TLS. When SSL/TLS is enabled, clients connect to the server using HTTPS instead of HTTP.

The default port used by the server is 8080. A different port can be configured for HTTPS, for example, 8443, by setting the following property:

server.port=8443

To enable SSL/TLS, set the following property:

server.ssl.enabled=true

The following properties configure the SSL certificate and key store used by the server:

Key Store Path

This specifies the path to the key store containing the SSL certificate and private key. For example:

server.ssl.key-store=file:///opt/softwareag/NaturalOpenAPIServer/conf/keystore.p12

Key Store Password

This specifies the password required to access the key store. For example:

server.ssl.key-store-password=password

Key Store Type

This specifies the type of key store. The supported types are JKS and PKCS12. For example:

server.ssl.key-store-type=PKCS12

Key Store Alias

This specifies the alias used to identify the certificate and private key within the key store. For example:

server.ssl.key-alias=noa-server

Authentication

The Natural OpenAPI server does not authenticate the client sending the request by itself, but rely on the authentication module of the Natural Subprogram Server. However, if the Natural Subprogram Server is configured to use an authentication method, you must define the appropriate configuration in the Natural OpenAPI Server. Defining the correct configuration will create the related definition in the OpenAPI document located at http://localhost:OpenAPIServer_port/v3/api-docs.

There are 3 different ways to define the authentication:

Using Basic Authentication

Setting the com.softwareag.natural.openapi.web.config.authenticationType property to basic will require the client application to send username and password encoded with Base64 encoding (defined in RFC-7617).

Using OAuth2 Token

Token retrieval is the responsibility of the client application, while token validation is performed by the Natural Subprogram Server authentication module.

Setting the com.softwareag.natural.openapi.web.config.authenticationType property to oauth2 adds a requirement to the OpenAPI document for the client application to send a Bearer token.

The client application is required to include the special HTTP header X-Impersonate-User to specify the user to impersonate, alongside the provided token.

The following configuration can be used when testing with the Swagger UI web client. The Swagger UI embedded in the Natural OpenAPI Server currently supports only the Client Credentials flow. When OAuth2 authentication is enabled, you can define the tokenURL and required scopes. These values are exposed in the OpenAPI document but are not used by the Natural OpenAPI Server for authentication. In the case of impersonation, it must be performed after a successful token verification.

Using Anonymous Requests

When an authentication type is not defined in the application.properties file, the requests are considered anonymous by default and should not be authenticated. It is also possible to execute the request as another user using the special HTTP header X-Impersonate-User.