grist-authn

Email/password and OIDC authentication for Grist.

Image

ghcr.io/gwhthompson/grist-authn:latest

Tags follow grist-core releases (e.g., v1.1.15).

Configuration

Required

Variable	Description
GRIST_PASSWORD_AUTH	Set to true to enable
GRIST_NODEMAILER_CONFIG	Email transport config (JSON)
GRIST_NODEMAILER_SENDER	Sender details: {"name":"Grist","email":"noreply@example.com"}

Optional

Variable	Description
APP_HOME_URL	Base URL for email links (e.g., https://grist.example.com)
GRIST_APP_NAME	App name in emails (default: your account)
GRIST_2FA_TOTP	Enable TOTP two-factor authentication (default: true)
REDIS_URL	Redis connection for notification batching

Email Transport

The GRIST_NODEMAILER_CONFIG value is passed directly to nodemailer's createTransport().

SMTP:

{"host":"smtp.example.com","port":587,"auth":{"user":"...","pass":"..."}}

AWS SES API (for hosts that block SMTP ports):

{"transport":"ses","region":"us-east-1"}

SES uses the standard AWS credential chain (environment variables or IAM role).

OIDC (Optional)

Add OIDC as a secondary login method:

Variable	Description
GRIST_OIDC_IDP_ISSUER	Provider issuer URL
GRIST_OIDC_CLIENT_ID	Client ID
GRIST_OIDC_CLIENT_SECRET	Client secret

OIDC users must already exist in the system (created via sharing).

User Management

Users cannot self-register. The flow:

1. Admin shares a document or workspace with an email address
2. User receives a password setup email
3. User sets their password and can log in

This ensures only invited users access the system.

Security

Passwords

• Hashed with Argon2id (64 MiB memory, 3 iterations)
• Strength validated with zxcvbn (minimum score 2)
• Minimum length: 8 characters

Protection

• Account lockout: 5 failed attempts triggers 15-minute lock
• Rate limiting: 10 login attempts per 15 min (per IP+email), 3 password resets per hour
• Reset tokens: SHA-256 hashed, 256-bit entropy, 24-hour expiry

Two-Factor Authentication

TOTP-based 2FA is enabled by default. Users can set it up at /auth/2fa/setup.

Setup flow:

1. User scans QR code with authenticator app (Google Authenticator, Authy, etc.)
2. User enters 6-digit code to verify
3. Future logins require password + TOTP code

To disable 2FA for a locked-out user, clear the totp_secret column in password_credentials.

Set GRIST_2FA_TOTP=false to disable 2FA system-wide.

Production Requirements

Set these for production deployments:

GRIST_SECURE_COOKIES=true
GRIST_COOKIE_SAMESITE=Lax

Notifications

Includes document and comment notifications from grist-ee:

• Document change notifications
• Comment notifications (all/mentions-only/none)
• User notification preferences

With REDIS_URL configured, notifications are batched to reduce email volume. Without Redis, notifications send immediately.

Documentation

• DEVELOPMENT.md - Local setup, building, testing
• SECURITY.md - Security implementation details
• CLAUDE.md - Architecture overview for contributors
• CORE_DEPENDENCIES.md - grist-core API compatibility

License

MIT