Skip to content

Static Authentication

Static Authentication in KDB.AI

This page explains how to set up and use static authentication in KDB.AI. It includes details on environment variables, Docker examples, and Python client usage.

If you're new to this topic, start with Learn: Authentication.

KDB.AI supports static authentication, allowing access management for different users.

flowchart LR

    Client[Client]

    TCP[TCP or QIPC Connection]
    HTTP[HTTP or REST Connection]

    KDBAI[KDB.AI Server]

    Config[AUTH_TYPE = static]
    Secret["Configured Secret - AUTH_PASSWORD or mounted file"]

    Client --> TCP --> KDBAI
    Client --> HTTP --> KDBAI

    Config --> KDBAI
    Secret --> KDBAI

With static authentication, the server verifies the client password with a static key provided to the server. You can supply the static key as an environment variable or as a mounted file path (for example, using a Kubernetes secret). The following variables enable static authentication:

Variable Purpose Supported values Mandatory Default
AUTH_TYPE Authentication type static Yes None
AUTH_PASSWORD Authentication password any string No (password file can be mounted instead) None

Static authentication with environment variable

To configure static authentication, add the following environment variables to your Docker/Kubernetes configuration:

AUTH_TYPE=static
AUTH_PASSWORD="secret" # required when using an environment variable; omit if using a mounted password file

Static authentication with password file

To use a mounted secret file, mount it at the path /opt/kx/secret/auth_pwd. A mounted secret file always takes precedence over the AUTH_PASSWORD environment variable.

Python Client version

To maintain compatibility with the server, use kdbai-client>=1.6.0:

  • kdbai-client==1.6.0 supports TCP/QIPC connection with authentication.

  • kdbai-client>=1.7.0 supports TCP/QIPC and HTTP connections with authentication.

  • kdbai-client<1.6.0 is not compatible.

Docker examples

Authentication from environment variable

Use the AUTH_PASSWORD variable:

docker run -it --rm -p 8081:8081 -p 8082:8082 \
        -e KDB_LICENSE_B64="$KDB_LICENSE_B64" \
        -e AUTH_TYPE=STATIC \
        -e AUTH_PASSWORD="secret" \
        -v "$PWD/vdbdata":/tmp/kx/data \
         portal.dl.kx.com/kdbai-db:1.9.0

Authentication from file

Create a password file and mount it into the container:

echo "secret" > /tmp/auth_pwd
docker run -it --rm -p 8081:8081 -p 8082:8082 \
        -e KDB_LICENSE_B64="$KDB_LICENSE_B64" \
        -e AUTH_TYPE=STATIC \
        -v /tmp/auth_pwd:/opt/kx/secret/auth_pwd \
        -v "$PWD/vdbdata":/tmp/kx/data \
         portal.dl.kx.com/kdbai-db:1.9.0

No authentication specified

Run as normal without specifying any authentication variables:

docker run -it --rm -p 8081:8081 -p 8082:8082 \
        -e KDB_LICENSE_B64="$KDB_LICENSE_B64" \
        -v "$PWD/vdbdata":/tmp/kx/data \
         portal.dl.kx.com/kdbai-db:1.9.0

Examples

HTTP authentication using curl

curl http://localhost:8081/api/v2/version
{"message":"You are not authorized to access this resource."}

curl -u user:password-file http://localhost:8081/api/v2/version
{"serverVersion":"1.9.0","clientMinVersion":"1.9.0","clientMaxVersion":"latest"}

Authentication using Python Client

Replace "secret" with your configured AUTH_PASSWORD value.

import kdbai_client as kdbai
PASSWORD = "secret"
try:
    session = kdbai.Session(
        host="localhost",
        port=8082,
        mode='qipc',
        options={"username": "user", "password": PASSWORD}
    )
    print(f"Success, connected to server with qipc")
except kdbai.KDBAIException as e:
    print(f"Failed to connect with password={PASSWORD} --> {e}")

Recommendation: use TLS in production

Encrypt connections to protect credentials in transit. KDB.AI does not terminate TLS directly — you need a TLS-terminating proxy (for example, nginx or a load balancer) in front of it. The proxy handles encryption and forwards connections to KDB.AI unencrypted. Add options={'tls': True} to enable TLS on the client side:

session = kdbai.Session(
    host="localhost",
    port=8082,
    mode='qipc',
    options={"username": "user", "password": PASSWORD, "tls": True}
)

import kdbai_client as kdbai
PASSWORD = "secret"
try:
    session = kdbai.Session(
        endpoint="http://localhost:8081",
        mode='rest',
        options={"username": "user", "password": PASSWORD}
    )
    print(f"Success, connected to server with rest")
except kdbai.KDBAIException as e:
    print(f"Failed to connect with password={PASSWORD} --> {e}")

Recommendation: use TLS in production

Encrypt connections to protect credentials in transit. KDB.AI does not terminate TLS directly — you need a TLS-terminating proxy (for example, nginx or a load balancer) in front of it. The proxy handles encryption and forwards connections to KDB.AI unencrypted. Use https:// in the endpoint URL to connect over TLS:

session = kdbai.Session(
    endpoint="https://localhost:8081",
    mode='rest',
    options={"username": "user", "password": PASSWORD}
)