Skip to content

auth.md

Latest commit

 

History

History
150 lines (101 loc) · 4.47 KB

auth.md

File metadata and controls

150 lines (101 loc) · 4.47 KB

Authentication

NodeDB supports multiple authentication methods, usable together.

Password Auth (SCRAM-SHA-256)

Compatible with any PostgreSQL client (psql, pgcli, application drivers).

-- Create a user with password
CREATE USER alice WITH PASSWORD 'strong_password_here';

-- Create with a specific role
CREATE USER bob WITH PASSWORD 'secret' ROLE readonly;

-- Create for a specific tenant (superuser only)
CREATE USER service_bot WITH PASSWORD 'key' ROLE readwrite TENANT 42;

-- View all users
SHOW USERS;

Roles: readonly, readwrite, admin, tenant_admin, superuser

Connect via psql:

psql -h localhost -p 6432 -U alice

API Keys

For service-to-service communication without passwords.

-- Create an API key (returns the key once — store it securely)
CREATE API KEY 'my-service' ROLE readwrite;

-- Create a key scoped to specific databases
CREATE API KEY 'analytics-svc' FOR service_account WITH DATABASES (analytics, logs);

-- Revoke
DROP API KEY 'my-service';

Database scoping:

-- Create a key accessible only to the 'prod' database
CREATE API KEY 'prod-reader' FOR alice WITH DATABASES (prod);

-- Attempt to use key on a different database is rejected
-- Error: DATABASE_NOT_AUTHORIZED

API keys default to the owner's accessible databases. Narrow with WITH DATABASES (db1, db2) to restrict to a subset.

Use in HTTP requests:

curl -H "Authorization: Bearer <api-key>" http://localhost:6480/v1/query

Service Accounts

Credentials for daemons, batch jobs, and application backends. Service accounts are scoped to a database.

-- Create a service account for a database
CREATE SERVICE ACCOUNT 'batch-processor' FOR DATABASE analytics;

-- Create an API key on the service account
CREATE API KEY 'batch-key' FOR 'batch-processor' WITH DATABASES (analytics);

-- Adjust accessible databases
ALTER SERVICE ACCOUNT 'batch-processor' SET DATABASES (analytics, logs);

-- View all service accounts
SHOW SERVICE ACCOUNTS;

Service accounts are isolated from user accounts and cannot authenticate via password.

OIDC Single Sign-On

Authenticate via external identity providers (Auth0, Okta, Keycloak) using JWT bearer tokens. One-time setup per provider, then users authenticate directly with the provider.

-- Admin registers provider
CREATE OIDC PROVIDER auth0 WITH (
    issuer = 'https://your-domain.auth0.com/',
    jwks_url = 'https://your-domain.auth0.com/.well-known/jwks.json',
    audience = 'nodedb-api'
);

Supported on: Native protocol and HTTP. Not on pgwire — the Postgres wire protocol has no standard bearer-token framing; pgwire stays SCRAM-SHA-256 only.

See OIDC Single Sign-On for full setup and claim mapping.

JWKS (JWT Auto-Discovery) — Legacy

Multi-provider support for Auth0, Clerk, Supabase, Firebase, Keycloak, and Cognito via nodedb.toml configuration.

Configure in nodedb.toml:

[auth.jwks]
providers = [
    { issuer = "https://your-domain.auth0.com/", audience = "your-api" },
]

JWT claims map to $auth.* session variables:

JWT Claim Session Variable Usage
sub $auth.id RLS: WHERE user_id = $auth.id
role / custom $auth.role RLS: WHERE $auth.role = 'admin'
org_id / custom $auth.org_id RLS: WHERE org_id = $auth.org_id
scope $auth.scopes RLS: WHERE $auth.scopes CONTAINS 'read:orders'

Supported algorithms: ES256, ES384, RS256. Built-in JWKS cache with disk fallback and circuit breaker for provider outages.

Note: The OIDC provider mechanism (above) is the recommended approach for modern SSO; this nodedb.toml method is supported for backward compatibility.

mTLS (Mutual TLS)

For zero-trust environments. Both client and server present certificates.

Configure in nodedb.toml:

[server.tls]
cert = "/path/to/server.crt"
key = "/path/to/server.key"
client_ca = "/path/to/ca.crt"     # enables mTLS
crl = "/path/to/revocation.crl"   # optional CRL

Auth Priority

When multiple methods are configured, NodeDB checks in order:

  1. mTLS (if client certificate present)
  2. JWT Bearer token (if Authorization header present)
  3. API key (if Authorization: Bearer matches a key)
  4. SCRAM-SHA-256 (pgwire password auth)

Back to security