Configuring for Production
Running a Nuts node in a production environment has additional requirements regarding security and data integrity compared to development or test environments. This page instructs how to configure your node for running in a production environment and what to consider.
By default the node runs in a mode which allows the operator run configure the node in such a way that it is less secure.
For production it is recommended to enable
strictmode which blocks some of the unsafe configuration options
(e.g. using the IRMA demo scheme).
HTTP Interface Configuration
By default all HTTP endpoints get bound to the default HTTP interface on
You can configure endpoints to have alternative configuration (e.g. CORS, TLS, authentication) and/or be bound on an alternative port using the
All configuration properties that apply to the
http.default HTTP interface are applicable to the alternative interface you configure as well (see the example below).
For production there are a few points to consider; enabling CORS, using alternative HTTP interfaces, and authentication.
Binding HTTP interfaces
Some HTTP endpoints are required to be accessible by the public and others only meant for administrator or your own XIS. You can determine the intended public by observing the first part of the URL:
Endpoints that start with
/publicshould be accessible by the general public,
/internalis meant for XIS application integration and administrators.
It’s advisable to make sure internal endpoints aren’t reachable from public networks.
You can achieve this by binding it to a different port, by using a reverse proxy, or both.
address property of a HTTP binding to expose it on a different port:
http: # The following is the default binding which endpoints are bound to, # which don't have an alternative bind specified under ``alt``. Since it's a default it can be left out or # be used to override the default bind address. # If you specify an alt bind without address, it binds to the default HTTP interface, but # the configuration of the default bind will NOT apply to the alt bind. If required, you need to repeat the config (e.g. cors/auth) for the alt bind. default: address: :1323 alt: # The following binds all endpoints starting with ``/internal`` to ``internal.lan:1111`` internal: address: internal.lan:1111 auth: type: token # The following binds all endpoints starting with ``/public`` to ``:443`` and enables TLS for it public: address: :443 # Given we bind on port 443, we probably want to enable TLS for this endpoint tls: server # The following enables cross-domain requests (CORS) from irma.vendor.nl cors: origin: - irma.vendor.nl
Cross Origin Resource Sharing (CORS)
In some deployments CORS can be required for the public IRMA authentication endpoints when the user-facing
authentication page is hosted on a (sub)domain that differs from Nuts Node’s IRMA backend. CORS can be enabled on a
specific HTTP interface by specifying the domains allowed to make CORS requests as
cors.origin (see the example above).
Although you can enable CORS on the default endpoint it’s not advised to do so in a production environment,
because CORS itself opens up new attack vectors on node administrators.
You might want to secure some HTTP endpoints (notably
/internal) with authentication.
The Nuts node supports JWT Bearer Token authentication which can be enabled on any HTTP endpoint.
You can enable it by setting
auth.type (see example above) to
token for the specific bind.
The specified path, and its all subpaths, will then require a JWT token generated by the Nuts node.
You can generate a token using the following command, which needs to be executed on the Nuts node itself:
nuts http gen-token admin 365
This command generates a token for a user named “admin” which is valid for 365 days. The user’s name is used for logging HTTP requests.
It outputs the token, which should be passed using
--token-file when performing CLI operations or as
Authorization Bearer token header for other clients, such as XIS applications.
You can also save it to a file named
.nuts-client.cfg in your user’s home directory, which will be read by CLI when no other token flags are passed.
See the server configuration and CLI command reference for more information.
To aid problem diagnosis every node in a network should share some information about itself; the type and version of software it’s running,
which peers it is connected to and how long it’s been up. This helps others diagnosing issues when others experience communication problems with your, and other nodes.
Although discouraged, this can be disabled by specifying