Authentication and access

Codifix defaults to single_user, preserving existing local installs. Set auth.mode = "multi_user" to use Authentik for browser identity and scoped Codifix service tokens for CLI, TUI, watchers, relays, and HTTP MCP.

Identity split

Authentik authenticates people. OpenBao is recommended for distributing machine secrets, but Codifix does not call OpenBao at runtime.

Permission sets and role presets

Authorization in v2 checks explicit permissions. Role names remain convenient presets, and applicable grants are combined; the service does not authorize by comparing an ordinal reader < writer < operator < admin ladder.

A global preset applies to every project. Explicit memberships and Authentik group mappings apply to named projects. /v1/auth/me exposes the expanded permission names so clients do not need to infer capabilities from the role label.

Authentik setup

1. In Authentik, create an application with an OAuth2/OIDC provider.
2. Use a confidential client and select a signing key.
3. Add the strict redirect URI https://memory.example.com/v1/auth/callback.
4. Include the openid, profile, and email scope mappings. Authentik's default profile scope includes group membership.
5. Record the application slug, issuer URL, client ID, and client secret.

Authentik documents the current provider workflow in Create an OAuth2 provider and the issuer/scope behavior in OAuth 2.0 provider.

Service configuration

[auth]
mode = "multi_user"
public_base_url = "https://memory.example.com"
session_ttl = "12h"
multi_user_legacy_token_enabled = false

[auth.oidc]
issuer_url = "https://auth.example.com/application/o/memory/"
client_id = "codifix"
client_secret_env = "CODIFIX_OIDC_CLIENT_SECRET"
scopes = ["openid", "profile", "email"]
groups_claim = "groups"

[[auth.group_mappings.rules]]
group = "memory-admins"
role = "admin"
global = true

[[auth.group_mappings.rules]]
group = "memory-writers"
role = "writer"
project = "memory"

Put the client secret in the adjacent environment file:

CODIFIX_OIDC_CLIENT_SECRET=replace-with-authentik-client-secret

public_base_url must be the browser-visible URL, including the HTTPS scheme. Codifix uses it for the callback URI and exact Origin checks.

Service principals

codifix auth whoami

codifix auth token create \
  --name hermes \
  --project memory \
  --role writer \
  --ttl 30d

export CODIFIX_CLIENT_TOKEN='mlt_...'
codifix auth whoami --json

The raw token is displayed once. Codifix stores only its SHA-256 hash. Store it in OpenBao or another secret manager before closing the output.

Grant the same principal another project:

codifix auth membership grant \
  --principal <principal-uuid> \
  --project another-project \
  --role reader

Global admins can perform the same work from the web UI's Access tab.

Migration

1. Configure Authentik and at least one global-admin group while still in single_user mode.
2. Set the OIDC secret environment variable and restart the service.
3. Switch to multi_user and verify a browser admin can sign in.
4. Issue project-scoped service tokens for every non-browser workload.
5. Disable multi_user_legacy_token_enabled after migration.

Returning to single_user is a config rollback. Do not reverse the auth migration; retaining the rows preserves the audit trail.

Troubleshooting

Existing browser sessions and service tokens keep working during an Authentik outage; only new browser logins depend on provider discovery.