Skip to content

Your favorite shift management application!

8.8 KB
Raw Blame

Authentication Setup Guide

This guide covers how to configure the authentication system in BetterShift, including local credentials, OAuth providers, and custom OIDC integration.

Table of Contents

  1. Overview
  2. Basic Configuration
  3. Email and Password Authentication
  4. OAuth Providers
  5. Custom OIDC Provider
  6. Session Management
  7. Rate Limiting
  8. Troubleshooting

Overview

BetterShift uses Better Auth for authentication. The system supports:

  • Email/password authentication
  • OAuth providers (Google, GitHub, Discord)
  • Custom OIDC providers (Keycloak, Authentik, Authelia, etc.)
  • Session-based authentication with secure cookies
  • Role-based access control (user, admin, superadmin)

Authentication is enabled by default for security. You can disable it by setting AUTH_ENABLED=false for single-user deployments.


Basic Configuration

Required Environment Variables

# Enable/disable authentication (default: true)
AUTH_ENABLED=true

# Required when auth is enabled - generate with: npx @better-auth/cli secret
BETTER_AUTH_SECRET=your-secret-here

# Your application URL (used for OAuth callbacks)
BETTER_AUTH_URL=http://localhost:3000

Access Control

# Allow new user registration (default: true)
ALLOW_USER_REGISTRATION=true

Guest access (viewing calendars without login) is not an environment variable — it's a live toggle in the admin panel under System Settings, off by default.

First User Setup

The first user to register becomes the superadmin with full system access. This happens automatically - no manual configuration required.


Email and Password Authentication

Email/password authentication is enabled by default when auth is active. Users can:

  • Register with email and password
  • Login with credentials
  • Change password from profile settings
  • Reset password (admin can reset via admin panel)

Password Requirements

Passwords are hashed using BCrypt. There are no specific complexity requirements enforced by default, but you can implement custom validation in your deployment.


OAuth Providers

BetterShift supports three built-in OAuth providers. Configure any combination based on your needs.

Google OAuth

  1. Go to Google Cloud Console
  2. Create a new project or select existing
  3. Navigate to APIs & Services > Credentials
  4. Create an OAuth 2.0 Client ID (Web application)
  5. Add authorized redirect URI: {BETTER_AUTH_URL}/api/auth/callback/google
  6. Configure environment variables:
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

GitHub OAuth

  1. Go to GitHub Developer Settings
  2. Click New OAuth App
  3. Set Authorization callback URL: {BETTER_AUTH_URL}/api/auth/callback/github
  4. Configure environment variables:
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

Discord OAuth

  1. Go to Discord Developer Portal
  2. Create a new application
  3. Navigate to OAuth2 > General
  4. Add redirect URI: {BETTER_AUTH_URL}/api/auth/callback/discord
  5. Configure environment variables:
DISCORD_CLIENT_ID=your-client-id
DISCORD_CLIENT_SECRET=your-client-secret

Custom OIDC Provider

For enterprise SSO or self-hosted identity providers, BetterShift supports generic OIDC configuration.

Supported Providers

Any OIDC-compliant provider works, including:

  • Keycloak
  • Authentik
  • Authelia
  • Okta
  • Azure AD
  • Auth0

Configuration

# Enable custom OIDC
CUSTOM_OIDC_ENABLED=true

# Display name shown on login button
CUSTOM_OIDC_NAME=Company SSO

# OAuth credentials
CUSTOM_OIDC_CLIENT_ID=bettershift
CUSTOM_OIDC_CLIENT_SECRET=your-client-secret

# OIDC Discovery URL (must include /.well-known/openid-configuration)
CUSTOM_OIDC_ISSUER=https://sso.example.com/.well-known/openid-configuration

# Scopes to request (space-separated)
CUSTOM_OIDC_SCOPES=openid profile email

Callback URL

Configure your OIDC provider with this callback URL:

{BETTER_AUTH_URL}/api/auth/oauth2/callback/custom-oidc

Keycloak Example

  1. Create a new client in your Keycloak realm
  2. Set Client Protocol to openid-connect
  3. Set Access Type to confidential
  4. Add Valid Redirect URI: https://bettershift.example.com/api/auth/oauth2/callback/custom-oidc
  5. Copy Client ID and Client Secret
  6. Configure BetterShift:
CUSTOM_OIDC_ENABLED=true
CUSTOM_OIDC_NAME=Keycloak
CUSTOM_OIDC_CLIENT_ID=bettershift
CUSTOM_OIDC_CLIENT_SECRET=your-keycloak-secret
CUSTOM_OIDC_ISSUER=https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration

Authentik Example

  1. Create a new OAuth2/OpenID Provider in Authentik
  2. Create an Application linked to the provider
  3. Set Redirect URI: https://bettershift.example.com/api/auth/oauth2/callback/custom-oidc
  4. Configure BetterShift:
CUSTOM_OIDC_ENABLED=true
CUSTOM_OIDC_NAME=Authentik
CUSTOM_OIDC_CLIENT_ID=your-authentik-client-id
CUSTOM_OIDC_CLIENT_SECRET=your-authentik-secret
CUSTOM_OIDC_ISSUER=https://authentik.example.com/application/o/bettershift/.well-known/openid-configuration

Session Management

Session Configuration

# Session lifetime in seconds (default: 7 days)
SESSION_MAX_AGE=604800

# Session refresh interval in seconds (default: 1 day)
SESSION_UPDATE_AGE=86400

User Session Control

Users can manage their sessions from the profile page:

  • View all active sessions (device, browser, IP, last activity)
  • Revoke all other sessions (keeps current session active)

Admin Session Control

Admins can revoke user sessions through the admin panel when banning users.


Rate Limiting

BetterShift includes built-in rate limiting to prevent abuse. All limits are configurable via environment variables.

Authentication Limits

# Login attempts: 5 per minute per IP
RATE_LIMIT_AUTH_REQUESTS=5
RATE_LIMIT_AUTH_WINDOW=60

# Registration: 3 per 10 minutes per IP
RATE_LIMIT_REGISTER_REQUESTS=3
RATE_LIMIT_REGISTER_WINDOW=600

# Password change: 3 per hour per user
RATE_LIMIT_PASSWORD_CHANGE_REQUESTS=3
RATE_LIMIT_PASSWORD_CHANGE_WINDOW=3600

Response Headers

Rate-limited endpoints return these headers:

  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Requests remaining in window
  • X-RateLimit-Reset: Unix timestamp when limit resets

Behind a Reverse Proxy

Login and registration limits are keyed by IP address. Behind Cloudflare, Caddy, nginx, or any other reverse proxy, set TRUSTED_PROXY_HEADER so the real visitor IP is used instead of your proxy's own address — otherwise every visitor is lumped into the same bucket, which defeats the limit entirely.

TRUSTED_PROXY_HEADER=CF-Connecting-IP  # behind Cloudflare
TRUSTED_PROXY_HEADER=X-Real-IP         # behind Caddy/nginx/Traefik on their own

See .env.example (section "Reverse Proxy") for the full set of options.


Troubleshooting

OAuth Callback Errors

Problem: OAuth login fails with "invalid_redirect_uri"

Solution: Ensure the callback URL in your provider matches exactly:

  • Google: {BETTER_AUTH_URL}/api/auth/callback/google
  • GitHub: {BETTER_AUTH_URL}/api/auth/callback/github
  • Discord: {BETTER_AUTH_URL}/api/auth/callback/discord
  • Custom OIDC: {BETTER_AUTH_URL}/api/auth/oauth2/callback/custom-oidc

OIDC Discovery Fails

Problem: Custom OIDC login shows "discovery failed"

Solution: Verify the issuer URL ends with /.well-known/openid-configuration and is accessible from your server.

Session Not Persisting

Problem: Users are logged out unexpectedly

Solution:

  1. Check BETTER_AUTH_SECRET is set and consistent across restarts
  2. Verify cookies are not blocked by browser or proxy
  3. Check BETTER_AUTH_TRUSTED_ORIGINS includes your domain

Registration Disabled for OIDC Users

Problem: New OIDC users cannot login when ALLOW_USER_REGISTRATION=false

Solution: This is expected behavior. When registration is disabled, only existing users can login via OIDC. Create user accounts first via the admin panel, then users can link their OIDC accounts.


Security Recommendations

  1. Use HTTPS in production - Set BETTER_AUTH_URL to your HTTPS URL
  2. Set trusted origins - Configure BETTER_AUTH_TRUSTED_ORIGINS for CORS protection
  3. Rotate secrets periodically - Change BETTER_AUTH_SECRET and regenerate sessions
  4. Monitor failed logins - Check audit logs for suspicious activity
  5. Use strong passwords - Educate users about password security
  6. Enable MFA (future feature) - When available, enable for admin accounts