API Security

These are the settings for securing the API from unwanted access.

Configuration

{
   "api": {
      "read_only": false,
      "access": {
         "http": {
            "allow": [],
            "block": []
         },
         "https": {
            "allow": [],
            "block": []
         }
      },
      "auth": {
         "enable": fals,
         "disable_localhost": false,
         "username": "",
         "password": "",
         "jwt": {
            "secret": ""
         },
         "auth0": {
            "enable": false,
            "tenants": []
         }
      }
   }
}

CORE_API_READ_ONLY=false
CORE_API_ACCESS_HTTP_ALLOW="127.0.0.1/32,::1/128"
CORE_API_ACCESS_HTTP_BLOCK="127.0.0.1/32,::1/128"
CORE_API_ACCESS_HTTPS_ALLOW="127.0.0.1/32,::1/128"
CORE_API_ACCESS_HTTPS_DENY="127.0.0.1/32,::1/128"
CORE_API_AUTH_ENABLE=true
CORE_API_AUTH_DISABLE_LOCALHOST=true
CORE_API_AUTH_USERNAME=
CORE_API_AUTH_PASSWORD=
CORE_API_AUTH_JWT_SECRET=mySecret
CORE_API_AUTH_AUTH0_ENABLE=false
CORE_API_AUTH_AUTH0_TENANTS=

read_only (bool)

Set this value to true in order to allow only ready access to the API. All API endpoints for writing will not be mounted.

By default this value is set to false.

access.http.allow (array)

A list of IPs that are allowed to access the API via HTTP. Each entry has to be an IP range in CIDR notation, e.g. ["127.0.0.1/32","::1/128"]. Provide the list as comma-separated values for the environment variable, e.g. 127.0.0.1/32,::1/128. If the list is empty, then all IPs are allowed. If the list contains any invalid IP range, the server will refuse to start.

By default the list is empty.

access.http.block (array)

A list of IPs that are not allowed to access the API via HTTP. Each entry has to be an IP range in CIDR notation. Provide the list as comma-separated values for the environment variable. If the list is empty, then no IPs will be blocked. If the list contains any invalid IP range, the server will refuse to start.

By default the list is empty.

access.https.allow (array)

A list of IPs that are allowed to access the API via HTTPS. Each entry has to be an IP range in CIDR notation. Provide the list as comma-separated values for the environment variable. If the list is empty, then all IPs are allowed. If the list contains any invalid IP range, the server will refuse to start.

By default the list is empty.

access.https.block (array)

A list of IPs that are not allowed to access the API via HTTPS. Each entry has to be an IP range in CIDR notation. Provide the list as comma-separated values for the environment variable. If the list is empty, then no IPs will be blocked. If the list contains any invalid IP range, the server will refuse to start.

By default the list is empty.

auth.enable (bool)

Set this value to true to enable JWT authentication for the API. If it is enabled, you have to provide a username and password. The username and password will be sent to the /api/login endpoint in order to obtain an access and refresh JWT.

By default this value is set to false.

auth.disable_localhost (bool)

Set this value to true in order to allow unprotected access from localhost.

Be default this value is set to false.

auth.username (string)

The username for JWT authentication. If JWT authentication is enabled, a username must be defined.

By default this value is empty, i.e. no username defined.

auth.password (string)

The password for JWT authentication. If JWT authentication is enabled, a password must be defined.

By default this value is empty, i.e. no password defined.

auth.jwt.secret (string)

A secret for signing the JWT. If you leave this value empty, a random secret will be generated for you.

By default this value is empty.

auth.auth0.enable (bool)

Set this value to true in order to enable API auth0 protection. With this a valid Auth0 access JWT can be used instead of a username/password in order to obtain the access and refresh JWT. Additionally you have to provide a list of tenants and their users to validate the Auth0 access JWT against.

By default this value is set to false.

auth.auth0.tenants (array)

A list of allowed tenants and their users. A tenant is a JSON object:

{
    "domain": "",
    "audience": "",
    "clientid": "",
    "users": [],
}

You can obtain the domain, audience, and clientid from your Auth0 account. You also have to provide a list of allowed users that are member of that tenant.

For providing the list of tenants and their users as an environement variable you have to provide a comma-separated list of base64 encoded tenant JSON objects.

As of version 16.12.0 there's a different syntax available for providing the tenants as environment variable. A list of comma separated URLs of this form:

auth0://[clientid]@[domain]?aud=[audience]&user=...&user=...

By default this list is empty.