Configuration Reference

The na-user service is configured on startup and the configuration does not change during the run time of the service. That is, to change the configuration you must restart the service.

Configuration is done through a YAML configuration file as described in this section. Configuration items from the file can be overridden using environment variables.

The configuration can contain several important secrets and should be treated accordingly

Examples of how to use the configuration file and environment variables are shown in the Deploy to Docker and Deploy to Kubernetes sections.

Configuation File vs Environment Variables

All configuration file variables can be overridden by environment variables at runtime. The variable names are prefixed with NA_USER_ and converted to upper case. Subkeys are separated by underscores.

For example, the following are equivalent:

Configuration YAML file:

database.mysql.db_host="127.0.0.1"
database.mysql.db_user="mysql_userid"
http_server.port="8080"
http_server.cert_file="/run/secrets/cert.pem"
log.format="json"
license="your_license_string"

Environment variables:

NA_USER_DATABASE_MYSQL_DB_HOST="127.0.0.1"
NA_USER_DATABASE_MYSQL_DB_USER="mysql_userid"
NA_USER_HTTP_SERVER_PORT="8080"
NA_USER_HTTP_SERVER_CERT_FILE="/run/secrets/cert.pem"
NA_USER_LOG_FORMAT="json"
NA_USER_LICENSE="your_license_string"

The reference examples below include both configuration file and environment variable forms.

Configuration File Example

Below is an example of a configuration file with a description of every parameter you can specify. Note that all configuration options can be overridden by environment variables as described above.

Replace the values in <> with your own values:

# Your license for this software. Replace 'YOUR_LICENSE_STRING' with your actual
# license value. Visit https://nulladmin.com/na-user/license to purchase
# and manage your licenses. 

license: "YOUR_LICENSE_STRING"

# Specify authentication types and parameters for the admin user.
#
# Currently only basic HTTP authentication (api_auth.type = "basic") is supported
#
# On startup, if the admin password is not set, the given password will be
# configured for admin authentication. If the admin password is already set in the database,
# as for example for an already initialized instance of the service,
# the 'api_auth.basic.admin_password' setting will have no effect.
#
api_auth:
    # Authentication type
    type: "basic"

    # Basic HTTP authentication parameters
    basic:
        admin_password: "<BASIC_AUTHENTICATION_PASSWORD>"

# Specify a 32 byte secret which will be used to encrypt paging tokens.
# If you're running multiple load balanced servers they should all have
# the same encrypt_secret value configured. The secret must be at least 32 bytes
# long.
#
# Here's a simple way to generate it from the command line on Linux machines 
# with sufficient entropy:
#
#   cat /dev/urandom | tr -dc "a-zA-Z0-9" | fold -w 32 | head -n 1
#
# Each instance of the server on the same load balancer should
# have encrypt_secret set to the same value.
#
encrypt_secret: "<RANDOM_SECRET>"

database:
    # Database type
    # "mysql" - MySQL driver, currently the only supported one
    db_driver: "mysql"

    # Mysql specific settings
    mysql:
        # Database connection details
        db_host: "127.0.0.1"
        db_port: 3306
        db_database: "<DATABASE_NAME>"
        db_userid: "<DATABSE_USERNAME>"
        db_password: "<DATABASE_PASSWORD>"

        # Client timeouts in seconds. Zero values indicate system defaults
        db_connection_timeout: 0
        db_read_timeout: 0
        db_write_timeout: 0

        # Unicode charset and collation support for the connection to the database
        # Note that your database should be configured to support this Unicode
        # charset and collation
        db_charset: "utf8mb4"
        db_collation: "utf8mb4_unicode_ci"

        # TLS encryption setting for the connection to the DB server
        #    "skip-verify" - use TLS with a self-signed certificate on the DB server
        #    "true"        - use TLS connection to the DB server with client certificates
        #    "false"       - do not use TLS encrypted connection to the DB server 
        db_tls: "skip-verify"

        # If using TLS to connect to the database, configure paths to CA, certificate, and key files
        # ssl_ca: "/path/to/mysql_ssl_ca.pem"
        # ssl_cert: "/path/to/mysql_ssl_cert.pem"
        # ssl_key: "/path/to/mysql_ssl_key.pem"

log:
    # Where to send logs. Valid values are stdin, stdout, or a log file path:
    #        "stdout"              - Logs sent to stdout (the default)
    #        "stderr"              - Logs sent to stderr 
    #        "/var/log/na-user.log" - Logs sent to the file '/var/log/na-user.log'. 
    #                                Note that na-user does not handle log rotation.
    output: "stdout"

    # Format for server logging 
    #   "logfmt" - key=value format, human friendly
    #   "json"   - JSON format, for easy parsing by tools like logstash or Splunk
    format: "json"   

    # Log timestamps can be in the local or UTC timezone
    #   "UTC"   - timestamps in UTC time, default used in most production environments
    #   "local" - timestamps in local time
    timestamp_zone: "UTC"   

http_server:

    # If using TLS to connect to the server paths to certificate and private key file paths
    # cert_file: "/path/to/cert.pem"
    # key_file: "/path/to/key.pem"

    # Server bind address and port
    # address:  "" is the default for serving on all interfaces
    address:  ""
    port: 8080

    # Throttle control applied to the HTTP call method (GET, POST, DELETE, PUT, PATCH)
    # Example: maximum burst of 100 which refills at rate of 1 token per second.
    # burst: 100
    # concurrency: 1
    # 
    # Disabled by default 
    concurrency: 0

    # cache_ttl adds HTTP "Expires" and "Cache-Control" headers to limit 
    # browser caching of '/' '/health' and '/metrics' paths.
    # Value in seconds from 0 to 31556926. 
    # A value of -1 turns off caching headers
    cache_ttl: -1

    # HTTP read header timeout in seconds, the time from the connection is
    # accepted to when the API request headers are fully read.
    read_header_timeout:  20

    # HTTP read timeout in seconds, the time from when the connection is
    # accepted to when the API request body is fully read
    read_timeout:  60

    # HTTP write timeout in seconds, the time from the end of the request
    # header read to the end of the API response write
    write_timeout: 60

    # HTTP idle timeout in seconds
    idle_timeout:  120

    # Maximum size of request header in bytes, default is 1MB
    # max_header_bytes: 1000000

# The default number of results to return for all /list and /search API calls
# which don't provide a page_size argument 
default_page_size:  20

# The maximum number of results to return for all /list and /search API calls.
# Overrides any page_size arguments clients may send. Adjust this to limit API clients 
# from asking for too much data at once
max_page_size: 100

# When creating new resources the server can automatically assign unique IDs.
# The 'id_type' config controls the type of identifier. The choices have different 
# DB performance tradeoffs, particularly at very large scale.
#
#   "random" - Random hex encoded 32 byte ID, Example: ce1f93dbb8a03d35dbf95661ba6d00d8
#
#   "ulid"   - Lexically sortable, 48 bit timestamp (milliseconds), 80 bits of 
#              randomness, base32 encoded. Example: 01BJ4ZK7HT4SH5FNKNVKP77C4K
#
#   "uuid"   - Standard type 4 UUID, Example: c3400c09-8f1f-42e6-a445-36c4ef0d35b6
#
id_type: "random"

# User password requirements. Note that a full Unicode character set is allowed
# so user passwords can contain, e.g. emoji
password:
    # Minimum required user password length. A length of 0 is not allowed. 
    min_pw_length:           12

    # Workfactor for the bcrypt password encryption function.
    # Increasing the the bcrypt_workfactor will have an impact 
    # user creation latency due to increased time needed to generate 
    # the user's password hash
    bcrypt_workfactor:       12

    # Seting the following options to true requires at least one of the
    # following Unicode character types to be present in the password
    require_upper_case:      false   
    require_lower_case:      false   
    require_number:          false   # Unicode number (category N)
    require_punctuation:     false   # Unicode punctuation character (category P)

# Resources and permissions can be bound to policies.
# These settings limit how many resources and permissions can be bound to 
# any single policy. Lower limits lead to better performance when checking 
# if a set of permissions applies to a set of resources. Worst case
# this will involve max_resources * max_permissions checks. 
policy:
    max_resources:   100 # maximum number of resources per policy
    max_permissions: 100 # maximum number of permissions per policy

# Enable verbose debug logging, true or false
# debug: false

Configuration Reference

debug

• Type: boolean
• Default: false

When set to true the debug flag enables verbose logging. Not recommended for extended production use.

Examples:

debug: false
NA_USER_DEBUG=false

default_page_size

• Type: integer
• Default: 20
• Values: 0 to max_page_size

The default number of results to return for all /list and /search API calls which don't provide a page_size argument. See also max_page_size

Examples:

default_page_size: 20
NA_USER_DEFAULT_PAGE_SIZE=20

encrypt_secret

• Type: string
• Default: <blank>
• Values: random string 32 or more bytes long

na-user uses an the encrypt_secret for encrypting various security sensitive features such as GUI cookies and paging tokens (a.k.a. continuation tokens). The secret is read from the configuration file or environment variable when starting the na-user container.

IMPORTANT

If running multiple na-user containers all must share the same encryption secret. Make sure all containers have the same configured encryption secret. If this is not done some features (e.g. paging through user listings) will not work as expected.

For example, to generate an encryption secret on Linux you can run the following bash command:

$ cat /dev/urandom | tr -dc "a-zA-Z0-9" | fold -w 32 | head -n 1

Examples:

encrypt_secret: "TedOFqtutgw0Nziuhid4igJ1LVS2J5W3"
NA_USER_ENCRYPT_SECRET="TedOFqtutgw0Nziuhid4igJ1LVS2J5W3"

id_type

• Type: enumeration
• Default: random
• Values: random, ulid, uuid

When creating new resources (e.g. users) the server can automatically assign unique IDs. The 'id_type' config controls the type of identifier. The choices have different DB performance tradeoffs, particularly at very large scale.

• random - Random hex encoded 32 byte ID, Example: ce1f93dbb8a03d35dbf95661ba6d00d8
• ulid - Lexically sortable, 48 bit timestamp (milliseconds), 80 bits of randomness, base32 encoded. Example: 01BJ4ZK7HT4SH5FNKNVKP77C4K
• uuid - Standard type 4 UUID, Example: c3400c09-8f1f-42e6-a445-36c4ef0d35b6

Examples:

id_type: "random"
NA_USER_ID_TYPE="random"

max_page_size

• Type: integer
• Default: 100
• Values: 0 to 9223372036854775807

The max_page_size defines the global maximum number of records to return for all /list and /search API calls. Overrides any page_size arguments clients may send. Adjust this to limit API clients from asking for too much data at once

The max_page_size configuration setting prevents clients from ever fetching more then max_page_size number of records, regardless of the paging size they request. As such it places an tunable upper limit on the value of client specified page_size arguments.

In addition to limiting the resources used during paging, this parameter is useful as a security measure which limits the possible enumeration of user records over time.

Examples:

max_page_size: 100
NA_USER_MAX_PAGE_SIZE=100

api_auth.type

• Type: enumeration
• Default: basic
• Values: basic

Specify authentication types and parameters for the admin user. Currently only basic HTTP authentication (api_auth.type: "basic") is supported, making this config value optional.

Examples:

api_auth.type: "basic"
NA_USER_API_AUTH_TYPE="basic"

api_auth.basic.admin_password

• Type: string
• Default: ""

On startup, if the admin password is not set, the given api_auth.basic.admin_password will be configured for admin authentication. If the admin password is already set in the database the 'api_auth.basic.admin_password' setting will have no effect.

You can set the basic auth admin password through an environment variable on startup like this:

NA_USER_API_AUTH_BASIC_ADMIN_PASSWORD="secret" /path/to/na-user -c /path/to/config/na-user_conf.yaml

Examples:

api_auth.basic.admin_password: "secret"
NA_USER_API_AUTH_ADMIN_PASSWORD="secret"

database.db_driver

• Type: enumeration
• Default: mysql
• Values: mysql

Specifies the database driver. Currently only the MySQL driver is supported.

Examples:

databse.db_driver: "mysql"
NA_USER_DATABASE_DB_DRIVER="mysql"

database.mysql.db_host

• Type: string
• Default: 127.0.0.1

The host name or IP address of the MySQL server.

Examples:

databse.mysql.db_host: "mysql.example.com"
NA_USER_DATABASE_MYSQL_DB_HOST="mysql.example.com"

database.mysql.db_port

• Type: integer
• Default: 3306

The MySQL database port number.

Examples:

databse.mysql.db_port: 3306
NA_USER_DATABASE_MYSQL_DB_PORT="3306"

database.mysql.db_databse

• Type: string
• Default: na_user_users

The name of the MySQL database holding the user data.

Examples:

databse.mysql.db_database: "na_user_users"
NA_USER_DATABASE_MYSQL_DB_DATABASE="na_user_users"

database.mysql.db_userid

• Type: string
• Default: na_user_admin

The MySQL database userid.

Examples:

databse.mysql.db_userid: "na_user_admin"
NA_USER_DATABASE_MYSQL_DB_USERID="na_user_admin"

database.mysql.db_password

• Type: string
• Default: ""

The MySQL database password.

Examples:

databse.mysql.db_password: "secret"
NA_USER_DATABASE_MYSQL_DB_PASSWORD="secret"

database.mysql.db_charset

• Type: string
• Default: utf8mb4

Character set for the connection to the database.

In general, to handle unicode and emoji characters correctly this value should not be changed. Make sure your MySQL database supports this Unicode charset, specifically making sure that you are running MySQL 5.7+

Examples:

databse.mysql.db_charset: "utf8mb4"
NA_USER_DATABASE_MYSQL_DB_CHARSET="utf8mb4"

database.mysql.db_collation

• Type: string
• Default: utf8mb4_unicode_ci

The collation settings for the database.

In general, to handle the collation of unicode and emoji characters correctly this value should not be changed. Make sure your MySQL database supports this Unicode collation, specifically making sure that you are running MySQL 5.7+

Examples:

databse.mysql.db_collation: "utf8mb4_unicode_ci"
NA_USER_DATABASE_MYSQL_DB_COLLATION="utf8mb4_unicode_ci"

database.mysql.db_connection_timeout

• Type: integer
• Default: 0

Connection timeout to the database in seconds. Zero values indicate system defaults.

Examples:

databse.mysql.db_connection_timeout: 0
NA_USER_DATABASE_MYSQL_DB_CONNECTION_TIMEOUT="0"

database.mysql.db_read_timeout

• Type: integer
• Default: 0

Database read timeout. Zero values indicate system defaults.

Examples:

databse.mysql.db_read_timeout: 0
NA_USER_DATABASE_MYSQL_DB_READ_TIMEOUT="0"

database.mysql.db_write_timeout

• Type: integer
• Default: 0

Database write timeout. Zero values indicate system defaults.

Examples:

databse.mysql.db_write_timeout: 0
NA_USER_DATABASE_MYSQL_DB_WRITE_TIMEOUT="0"

database.mysql.db_tls

• Type: enumeration
• Default: skip-verify
• Values: skip-verify, true, false

TLS encryption setting for the connection to the DB server.

• skip-verify: use TLS with a self-signed certificate on the DB server
• false: do not use TLS encrypted connection to the DB server
• true: use TLS encrypted connection to the DB server with client certificates specified

When database.mysql.db_tls: "true" is set you need to also make sure that the databse.mysql.ssl_ca, databse.mysql.ssl_ca, and databse.mysql.ssl_key configuration points to valid PEM certificate/key files.

Typically you would mount these as Docker volumes:

docker run --rm -p 8080:8080 --name=na-user \
           -v /path/to/mysql_ssl_ca.pem:/run/secrets/mysql_ssl_ca.pem
           -v /path/to/mysql_ssl_cert.pem:/run/secrets/mysql_ssl_cert.pem
           -v /path/to/mysql_ssl_key.pem:/run/secrets/mysql_ssl_key.pem
           -v ./na-user_conf.yaml:/na-user_conf.yaml na-user:latest

These files can also be mounted as Kubernetes secrets. Refer to https://kubernetes.io/docs/concepts/configuration/secret/ for information on how to do this.

Examples:

databse.mysql.db_tls: "true" 
NA_USER_DATABASE_MYSQL_DB_TLS="skip-verify"

database.mysql.ssl_ca

database.mysql.ssl_cert

database.mysql.ssl_key

• Type: string
• Default: /run/secrets/mysql_ssl_[ ca | cert | key ].pem

Paths to the TLS certificate files for encrypted connections to the the MySQL server. Only used if database.mysql.db_tls: "true" is set.

Examples:

databse.mysql.ssl_ca: "/run/secrets/mysql_ssl_ca.pem" 
databse.mysql.ssl_cert: "/run/secrets/mysql_ssl_cert.pem" 
databse.mysql.ssl_key: "/run/secrets/mysql_ssl_key.pem" 
NA_USER_DATABSE_MYSQL_SSL_CA: "/run/secrets/mysql_ssl_ca.pem" 
NA_USER_DATABSE_MYSQL_SSL_CERT: "/run/secrets/mysql_ssl_cert.pem" 
NA_USER_DATABSE_MYSQL_SSL_KEY: "/run/secrets/mysql_ssl_key.pem" 

http_server.address

• Type: string
• Default: ""

Server bind address. The value http_server_address: "" is the default for serving on all interfaces

Examples:

http_server.address: ""
NA_USER_HTTP_SERVER_ADDRESS=""

http_server.port

• Type: integer
• Default: 8080

The port on which to serve the API.

Examples:

http_server.port: 8080
NA_USER_HTTP_SERVER_ADDRESS="8080"

http_server.concurrency

• Type: integer
• Default: 0

Request throttle control, in units of N requests per second. For example, a http_server.concurrency: 100 will limit API calls to 100 per second. The default value is 0, which turns off throttling.

Examples:

http_server.concurrency: 0
NA_USER_HTTP_SERVER_CONCURRENCY="0"

http_server.read_timeout

• Type: integer
• Default: 60

The time from when the HTTP connection is accepted to when the request body is fully read. If that timeout is exceeded by the client the connection is closed.

Examples:

http_server.read_timeout: 60 
NA_USER_HTTP_SERVER_READ_TIMEOUT="60"

http_server.write_timeout

• Type: integer
• Default: 60

The time from the end of the request header read to the end of the response write. If that timeout is exceeded by the client the connection is closed.

Examples:

http_server.write_timeout: 60 
NA_USER_HTTP_SERVER_WRITE_TIMEOUT="60"

http_server.idle_timeout

• Type: integer
• Default: 120

This limits the amount of time a Keep-Alive connection will be kept idle before being reused

Examples:

http_server.idle_timeout: 60 
NA_USER_HTTP_SERVER_IDLE_TIMEOUT="60"

http_server.max_header_bytes

• Type: integer
• Default: 1000000

The maximum permitted size of the headers in an HTTP request.

Examples:

http_server.max_header_bytes: 1000000
NA_USER_HTTP_SERVER_MAX_HEADER_BYTES="1000000"

http_server.cert_file

• Type: string
• Default: ""

Path to the TLS certificate file.

Both the http_server.cert_file and http_server.key_file must point to valid certificate and key for the API server to use HTTPS.

Examples:

http_server.cert_file: "/run/secrets/cert.pem"
NA_USER_HTTP_SERVER_CERT_FILE="/run/secrets/cert.pem"

http_server.key_file

• Type: string
• Default: ""

Path to the TLS private key file.

Both the http_server.cert_file and http_server.key_file must point to valid certificate and key for the API server to use HTTPS.

Examples:

http_server.key_file: "/run/secrets/key.pem"
NA_USER_HTTP_SERVER_KEY_FILE="/run/secrets/key.pem"

log.output

• Type: enumeration
• Default: stdout
• Values: stdout, stderr, /path/to/na-user.log

Where to send logs. Valid values are stdin, stdout, or a log file path:

• stdout: Logs sent to stdout (the default)
• stderr: Logs sent to stderr
• /var/log/na-user.log: Logs sent to the file '/var/log/na-user.log'.

Note that na-user does not handle log rotation.

Examples:

log.output: "stdout"
NA_USER_LOG_OUTPUT="stdout"

log.format

• Type: enumeration
• Default: json
• Values: json, logfmt

Format for server logging.

• json: JSON format, for easy parsing by tools like logstash or Splunk (default)
• logfmt: key=value format, human friendly

Examples:

log.format: "json"
NA_USER_LOG_FORMAT="json"

log.timestamp_zone

• Type: enumeration
• Default: UTC
• Values: UTC, local

Log timestamps can be in the local or UTC timezone.

• UTC: timestamps in UTC time, default used in most production environments
• local: timestamps in local time

Examples:

log.timestamp_zone: "UTC"
NA_USER_LOG_TIMESTAMP_ZONE="UTC"