Version: current

Service configuration

A single inway can expose multiple services. You can tell an inway which services to expose by providing the inway a toml file which contains the service configuration.

Below is an example configuration named service-config.toml.

version = 2
[services]
# This block defines an service exposed by this inway.
# A single inway can expose multiple services, therefore this block can be added multiple times.
# The name of the API (in this example SwaggerPetstore) must be unique for each block.
[services.SwaggerPetstore]
# In this example we expose the petstore.swagger.io website.
endpoint-url = "https://petstore.swagger.io"
documentation-url = "https://petstore.swagger.io"
api-specification-document-url = "https://petstore.swagger.io/swagger.json"
authorization-model = "whitelist"
public-support-contact = "support@my-organization.nl"
tech-support-contact = "tech@my-organization.nl"
ca-cert-path = "/path/to/custom-root-ca.crt"
[[services.SwaggerPetstore.authorization-whitelist]]
organization-name = "DemoRequesterOrganization1"
[[services.SwaggerPetstore.authorization-whitelist]]
organization-name = "DemoRequesterOrganization2"
public-key-hash = "tGbzEuAy88OB0zZWm+dolZoakhIKScV7zTK3wA15Ci8="
[[services.SwaggerPetstore.authorization-whitelist]]
public-key-hash = "yX0i/6NJZxaZWw7+LoCoq/vlA+06qb/5j/cg4n/zT/A="

Top level fields

version

Required Should be set to the version of the config that is used, a deprecation warning is logged when the value is empty or less than 2.

Example

version = 2

Service configuration fields

endpoint-url

Required Should be set to the address at which the API is available. Please make sure the inway can reach the API on this address!

Example

endpoint-url = "https://petstore.swagger.io"

documentation-url

Should be set to the url at which the documentation for this API is available.

Example

documentation-url = "https://petstore.swagger.io"

api-specification-document-url

If there is an OpenAPI Specification (OAS) available for the exposed API you can supply an URL to the OAS in this field. The OAS will be published to the directory. When using the ca-cert-path option, the server behind this URL should provide a certificate signed by that root certifictate. The following OAS versions are supported: 2.0, 3.0.0, 3.0.1, 3.0.2

Example

api-specification-document-url = "https://petstore.swagger.io/swagger.json"

authorization-model

Required The authorization model tells the inway how to authorise outways who are trying to consume this service. Currently there are two options available:

  1. none All outways with a valid NLX certificate can consume this service from the inway. No authorization check will be performed.
  2. whitelist An outway has to have a valid NLX certificate and the organization name and/or public key fingerprint of this certificate should be present in the authorization-whitelist of the inway. If not, the inway will not accept requests from this outway.

Example

authorization-model = "whitelist"

authorization-whitelist

A whitelist of organizations who are authorized to consume the service. When using the authorization-whitelist field the authorization-model of the service should be set to whitelist. Each entry in the whitelist consists of an organization-name and/or public-key:

  • public-key is the preferred method of authorization as this:
    • This restricts the certificates from a particular organization that can be used to setup NLX connections.
    • This allows organizations to compartiment their security by having different security zones.
    • This protects the NLX system of compromised CA's by pinning to specific public keys of certificates.
  • organization-name offers backward compatibility with the previous version of the whitelist.

Example

[[services.SwaggerPetstore.authorization-whitelist]]
organization-name = "DemoRequesterOrganization1"
[[services.SwaggerPetstore.authorization-whitelist]]
organization-name = "DemoRequesterOrganization2"
public-key-hash = "tGbzEuAy88OB0zZWm+dolZoakhIKScV7zTK3wA15Ci8="
[[services.SwaggerPetstore.authorization-whitelist]]
public-key-hash = "yX0i/6NJZxaZWw7+LoCoq/vlA+06qb/5j/cg4n/zT/A="

Example v1

This syntax is deprecated and will cause a warning to be logged

authorization-whitelist = ["DemoRequesterOrganization1", "DemoRequesterOrganization2"]

ca-cert-path

Can be used if the API you are trying to expose is providing a TLS certificate signed by a custom root certificate. The root certificate has to be available on the machine running the inway and the absolute path to the root certificate should be the value of this field.

Example

ca-cert-path = "/path/to/custom-root-ca.crt"`

public-support-contact

Contains an email address which NLX users can contact if they need your support when using this service. This email address is published in the directory.

Example

public-support-contact = "support@my-organization.nl"

tech-support-contact

Contains an email address which we (the NLX organization) can contact if we have any questions about your API. This email address will NOT be published in the directory.

Example

tech-support-contact = "tech@my-organization.nl"