API Authentication

The na-user API is protected by HTTP basic authentication and also supports TLS encryption using certificates specified in the server configuration file.

Best practice is to either run na-user on a network with encrypted network traffic, or to secure API calls with SSL certificates.

Kubernetes clusters will typically have inter-pod communication secured either via sidecar proxies (e.g. Nginx in front of the service) or by a service mesh (e.g. Istio). In that scenario basic authentication serves as a shared secret between the na-user pod and any other services which connect to it.

In Kubernetes, the basic authentication password for the default admin user can be injected as a Kubernetes secret into the na-user pod on startup through the configuration file or an environment variable. See the Deploy to Kubernetes section for an example.

If na-user is being run in a standalone container then it is possible to generate self-signed SSL certificates and inject them into the container as secrets. In that case the API is protected both by the shared secret of the Basic HTTP authentication as well as the encrypted network transit provided by the certificates.

Basic Authentication Configuration

On server startup na-user reads its configuration either from the config file or from environment variables. The api_auth.basic.admin_password configuration parameter (alternatively the NA_USER_API_AUTH_BASIC_ADMIN_PASSWORD environment variable) specifies the password for the default admin user. For example, in the configuration file:

api_auth:
    type: "basic"
    basic:
        admin_password: "secret"

Basic Authentication with SSL Configuration

Assume that we generate a self signed certificate and key pair. There are many ways to do this but we'll use the super simple mkcert tool:

$ mkcert -cert-file /path/to/sef_signed/cert.pem -key-file /path/to/sef_signed/key.pem localhost 127.0.0.1
The certificate is at "/path/to/sef_signed/cert.pem" and the key at "/path/to/sef_signed/key.pem"

Now assume the na-user configuration file has the following entries in it:

api_auth:
    type: "basic"
    basic:
        admin_password: "secret"
...
http_server:
    cert_file: "/path/to/self_signed/cert.pem"
    kay_file: "/path/to/self_signed/key.pem"
...

The API can then be accessed as follows (e.g. using curl):

curl --cacert /path/to/self_signed/cert.pem -s https://admin:secret@na-user.example.com/users/list