Authentication

WackyTracky uses a separate SQLite database for accounts, sessions, API keys, and roles. Task data stays in your chosen task backend (todo.txt, Neo4j, or YAML files).

First administrator

On first start with an empty IAM database, the service creates:

Username Password

admin

admin

Change this password before exposing the instance. The first account is placed in the Administrators group (full access).

Config

In config.yaml:

iam:
  database: ./data/iam.sqlite   # SQLite file for users/sessions/RBAC

auth: {}                        # optional httpauthshim settings (JWT, trusted headers, mTLS)
  • iam.database — Path to the IAM SQLite file. Created automatically if missing.

  • auth — Optional httpauthshim configuration for JWT, reverse-proxy headers, or mTLS. Empty {} is valid (username/password only).

Persist the IAM database (and your task data) across container restarts with volumes.

Browser sessions vs API keys

Method How

Web UI

Login sets an HttpOnly cookie named wacky-tracky-sid

Scripts / MCP (HTTP)

Create an API key in the UI, send Authorization: Bearer <key> (keys use the wt_ prefix)

Read-only API keys cannot change data. Cookie auth is not used on /mcp; use a Bearer API key there.

How access works

Permissions come from groups and roles, not from ticking boxes on a single user:

  1. A role lists permissions (for example app.access or users.view).

  2. A group is given one or more roles.

  3. Users belong to groups and inherit the union of those roles.

Built-in seeds include the Everyone group (member access) and Administrators (superuser). Do not leave the system with zero administrators.

Development: disable auth

For local development only:

export WACKYTRACKY_DEV_DISABLE_AUTH=true

Requests run as an anonymous superuser. Never enable this in production.

To allow non-HTTPS cookies in local HTTP:

export WACKYTRACKY_SECURE_COOKIES=false

Optional single sign-on

Extend auth: for JWT, trusted headers, or mTLS via httpauthshim. Strip inbound identity headers at your reverse proxy unless you trust the source. Most self-hosted setups only need username and password.

JWT from a reverse proxy (Cloudflare Access)

WackyTracky can trust a signed JWT added by an authenticating reverse proxy, such as Cloudflare Access. Users who reach WackyTracky through the proxy are signed in automatically:

auth:
  jwt:
    certsUrl: "https://<team>.cloudflareaccess.com/cdn-cgi/access/certs"
    issuer: "https://<team>.cloudflareaccess.com"
    aud: "<Access application AUD tag>"
    claimUsername: "email"
    header: "Cf-Access-Jwt-Assertion"
    cookieName: "CF_Authorization"
  • certsUrl verifies the token signature (pubKeyPath or hmacSecret can be used instead). Always set issuer and aud.

  • claimUsername is the claim used as the WackyTracky username.

  • header and cookieName say where the token is read from; set either or both.

The startup log shows httpauthshim: JWT header authentication enabled (and …​ cookie …​) when it is active. Only enable this when WackyTracky is reachable solely through the proxy.

The first time a JWT user visits, their account is created automatically (created_by: sso-autocreated) and added to the Everyone group. Grant further groups or roles from the IAM pages. Usernames match exactly, so an existing local account with the same username is used as-is.

Signing out and switching accounts

Signing out of a JWT session does not end the proxy’s session. Instead WackyTracky sets a wacky-tracky-sso-off cookie in that browser and ignores the JWT while it is present, so the login form stays and you can sign in with a username and password.

To go back to the JWT user, choose Sign in with Single Sign-On on the login page. This clears the cookie and signs you in from the proxy again.