Authentication

Set up authentication for your Deckyard installation.

Overview

Authentication is on by default. Deckyard refuses to start while authentication is enabled and AUTH_SECRET is missing, so an instance never runs wide open by accident. To run without authentication on purpose, set AUTH_ENABLED=false (see Disabling Authentication). Sandbox and demo mode are the only other cases where the server starts without a secret.

Authentication supports:

Database users with password login
Magic link (passwordless) login via email
Single sign-on (SSO) with one OpenID Connect (OIDC) provider
Development bypass mode for local testing

Account settings showing profile photo upload, display name field, and password change form

AUTH_SECRET

The secret key used for signing session tokens. This is required when authentication is enabled.

AUTH_SECRET=your-random-secret-string-at-least-32-characters

Generate a secure secret:

# Using OpenSSL
openssl rand -base64 48

# Using Node.js
node -e "console.log(require('crypto').randomBytes(48).toString('base64'))"

Important:

The secret must be at least 32 characters; the server refuses to start with a shorter one. AUTH_ALLOW_WEAK_SECRET=true overrides this check, but that is not recommended: rotate to a strong secret instead.
Keep this secret secure and never commit it to version control
Changing this secret will invalidate all existing sessions

Users

Users are stored in the database; there is no way to define users in environment variables. Admins add, edit and remove users in the admin panel, and can send a new user an invitation email (this needs the email service). Every user has one of two roles: admin or user. See User Management.

AUTH_ADMIN_EMAIL

Set the administrator email address. The user matching this email automatically receives admin privileges, regardless of their configured role.

AUTH_ADMIN_EMAIL=admin@yourdomain.com

If not set, no user has automatic admin privileges; roles must be assigned explicitly.

Magic Link Authentication

Passwordless login via email links. Users receive a secure link that logs them in automatically.

Requirements:

Email service configured (see Email Configuration)
The user must already have an account; no link is sent to unknown addresses

How it works:

User enters their email address
System sends a secure, time-limited link
Clicking the link authenticates the user and creates a session
Each link works once and expires after 15 minutes

Rate limits:

5 link requests per email per hour
15 link requests per IP per hour

Password Reset Flows

Users with a password can reset it by email.

Requirements:

Email service configured

Flow:

User requests a password reset
System sends an email with a secure reset link, valid for 1 hour
User clicks the link and enters a new password (at least 8 characters)
All existing sessions are invalidated
User signs in with the new password

Rate limits:

3 reset requests per email per hour
10 reset requests per IP per hour

Single Sign-On (OIDC)

Point the whole instance at one OpenID Connect provider, such as Google Workspace, Microsoft Entra ID, Okta, Auth0 or Keycloak. Users click “Sign in with SSO”, authenticate at the provider and land in Deckyard with the same account as a password or magic-link user with that email address.

SSO_ENABLED=true
SSO_PROVIDER=oidc
OIDC_ISSUER_URL=https://login.example.com
OIDC_CLIENT_ID=...
OIDC_CLIENT_SECRET=...
OIDC_REDIRECT_URI=https://deck.example.com/api/auth/oidc/callback

OIDC_REDIRECT_URI must exactly match the redirect URI registered at the provider. The server refuses to start when SSO_ENABLED=true but one of these settings is missing or a URL is malformed. oidc is the only supported provider.

Optional settings:

Variable	Default	Meaning
`OIDC_ALLOWED_DOMAINS`	(none)	Comma-separated email domains allowed to sign in
`OIDC_AUTO_PROVISION`	`true`	Create unknown users on their first login; `false` means users must be invited first
`OIDC_DEFAULT_ROLE`	`user`	Role for newly created users: `user` or `admin`
`OIDC_ADMIN_GROUPS`	(none)	Comma-separated provider group or role values that grant admin
`SSO_ENFORCE`	`false`	`true` hides the password and magic-link forms, leaving SSO only

An SSO login can grant admin (through OIDC_ADMIN_GROUPS or AUTH_ADMIN_EMAIL) but never removes it; demoting an admin is done in the admin panel.

Development Bypass Mode

For local development, you can bypass authentication entirely.

NODE_ENV=development
AUTH_DEV_BYPASS=true

When enabled:

All requests are treated as coming from an admin user (dev@local.test)
No login required
Full admin privileges granted

The bypass only takes effect when NODE_ENV=development; in any other environment it is ignored.

⚠️ Security Warning: Never enable this in production. With NODE_ENV=production the server refuses to start while AUTH_DEV_BYPASS is on.

COOKIE_DOMAIN

Set a cookie domain to share sessions across subdomains.

# Share sessions across all subdomains
COOKIE_DOMAIN=.example.com

# Single domain only
COOKIE_DOMAIN=app.example.com

SECURE_COOKIES

Force secure cookies (HTTPS only). Secure cookies are used automatically when the request arrives over HTTPS, including behind a proxy that sets X-Forwarded-Proto: https.

SECURE_COOKIES=true

Session Behavior

Sessions are valid for 14 days; this is fixed, not configurable
Sessions are stored as signed cookies (HttpOnly, SameSite=Lax)
Password changes invalidate all existing sessions for that user
Sessions are verified against the database on each request

Disabling Authentication

To run Deckyard without authentication (not recommended for production):

AUTH_ENABLED=false

When disabled, all users have anonymous admin access. Only an explicit false, 0, no or off disables authentication; an empty or misspelled value leaves it on.