Your favorite shift management application!
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
- Overview
- Basic Configuration
- Email and Password Authentication
- OAuth Providers
- Custom OIDC Provider
- Session Management
- Rate Limiting
- 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
- Go to Google Cloud Console
- Create a new project or select existing
- Navigate to APIs & Services > Credentials
- Create an OAuth 2.0 Client ID (Web application)
- Add authorized redirect URI:
{BETTER_AUTH_URL}/api/auth/callback/google - Configure environment variables:
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GitHub OAuth
- Go to GitHub Developer Settings
- Click New OAuth App
- Set Authorization callback URL:
{BETTER_AUTH_URL}/api/auth/callback/github - Configure environment variables:
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
Discord OAuth
- Go to Discord Developer Portal
- Create a new application
- Navigate to OAuth2 > General
- Add redirect URI:
{BETTER_AUTH_URL}/api/auth/callback/discord - 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
- Create a new client in your Keycloak realm
- Set Client Protocol to
openid-connect - Set Access Type to
confidential - Add Valid Redirect URI:
https://bettershift.example.com/api/auth/oauth2/callback/custom-oidc - Copy Client ID and Client Secret
- 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
- Create a new OAuth2/OpenID Provider in Authentik
- Create an Application linked to the provider
- Set Redirect URI:
https://bettershift.example.com/api/auth/oauth2/callback/custom-oidc - 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 allowedX-RateLimit-Remaining: Requests remaining in windowX-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:
- Check
BETTER_AUTH_SECRETis set and consistent across restarts - Verify cookies are not blocked by browser or proxy
- Check
BETTER_AUTH_TRUSTED_ORIGINSincludes 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
- Use HTTPS in production - Set
BETTER_AUTH_URLto your HTTPS URL - Set trusted origins - Configure
BETTER_AUTH_TRUSTED_ORIGINSfor CORS protection - Rotate secrets periodically - Change
BETTER_AUTH_SECRETand regenerate sessions - Monitor failed logins - Check audit logs for suspicious activity
- Use strong passwords - Educate users about password security
- Enable MFA (future feature) - When available, enable for admin accounts