Skip to content

Authentication

Jump to bottom
homelabforge edited this page Jul 3, 2026 · 6 revisions

Authentication

Configure user authentication and access control for MyGarage. Choose between no authentication, local JWT authentication, or OIDC/SSO integration.

Authentication Modes

MyGarage supports three authentication modes:

Mode Use Case Security Level Setup Complexity
None Local, testing, single-user behind firewall ⚠️ Low Easy
Local Single-user or family deployments, traditional login ✅ High Easy
OIDC Multi-user, enterprise SSO, centralized authentication ✅ Very High Medium

No Authentication Mode (Default)

Overview

  • Default mode on first install
  • No login required - anyone with URL can access
  • ⚠️ NOT RECOMMENDED for public-facing deployments
  • Best for local testing or behind trusted reverse proxy with external auth

Security Warnings

When running in none mode, MyGarage displays:

  • Red banner: "⚠️ Authentication disabled - anyone can access this instance"
  • Startup logs: "WARNING: Running without authentication"

When to Use

✅ Appropriate:

  • Local development (localhost only)
  • Single-user homelab behind firewall
  • Behind reverse proxy with authentication (Authelia, oauth2-proxy)
  • Testing/demo environments

❌ Never Use When:

  • Exposed to public internet
  • Contains sensitive data (loan docs, insurance)
  • Multiple users accessing

Configuration

After MyGarage is running, set the authentication mode in the web UI:

  1. Visit Settings → System
  2. Change Authentication Mode to None
  3. Save settings (takes effect immediately)

Local Authentication Mode

Overview

  • Traditional username/password authentication
  • JWT-based sessions with HttpOnly cookies
  • Argon2id password hashing (100MB memory cost, time cost 2)
  • Multi-user support with role-based access control
  • Recommended for most self-hosted deployments

Security Features

  • ✅ Argon2id Hashing - Industry-leading password hashing
  • ✅ JWT Tokens - Stateless session management
  • ✅ HttpOnly Cookies - Prevent XSS attacks
  • ✅ SameSite Protection - CSRF mitigation
  • ✅ Rate Limiting - 5 login attempts per minute
  • ✅ Secure Flag - Auto-enabled in production (HTTPS)

Enabling Local Auth

Via Web UI:

  1. Visit Settings → System
  2. Change Authentication Mode to Local
  3. Save settings (takes effect immediately)
  4. Visit the web interface — you'll see the registration page

JWT Secret: Auto-generated and saved to /data/secret.key on first startup. Back up this file — losing it invalidates all existing login sessions.

Optional Environment Variable (Advanced):

JWT_COOKIE_SECURE=auto  # auto (default), true (HTTPS only), false (HTTP allowed)

First User Registration

After enabling local auth:

  1. Restart MyGarage
  2. Visit web interface
  3. You'll see registration page: "Create First User"
  4. Fill in:
    • Email - Your email address (used for login)
    • Password - Strong password (min 8 chars)
    • Confirm Password
  5. Click "Create Account"
  6. First user automatically becomes admin

Password Requirements

  • Minimum length: 8 characters
  • Recommended: 12+ characters with mix of:
    • Uppercase letters
    • Lowercase letters
    • Numbers
    • Special characters

Weak passwords rejected:

  • ❌ "password", "12345678", "qwerty"
  • ❌ Common dictionary words
  • ❌ Repeated characters ("aaaaaaaa")

User Management

Adding Users (Admin Only)

  1. Login as admin
  2. Go to Settings → Users
  3. Click "Add User"
  4. Fill in:
    • Email - User's email address
    • Password - Temporary password (user should change)
    • Role - Admin or Standard User
    • Assigned Vehicles - Which vehicles user can access (optional)
  5. Click "Create User"
  6. Share credentials with new user (securely!)

User Roles

Admin:

  • ✅ Access all vehicles
  • ✅ Manage users (add, edit, delete)
  • ✅ Configure system settings
  • ✅ View all service records and documents
  • ✅ Export all data

Standard User:

  • ✅ Access assigned vehicles only
  • ✅ Add/edit service records for assigned vehicles
  • ✅ Upload documents for assigned vehicles
  • ❌ Cannot manage users
  • ❌ Cannot change system settings
  • ❌ Cannot access other users' vehicles

Shared Vehicles

Vehicles can be assigned to multiple users:

  1. Go to vehicle detail page
  2. Click "Settings" → "Sharing"
  3. Select users to share with
  4. Click "Save"

All assigned users can view/edit:

  • Vehicle info
  • Service records
  • Fuel logs
  • Documents

Password Reset (Admin)

If user forgets password:

  1. Login as admin
  2. Go to Settings → Users
  3. Click user → "Reset Password"
  4. Enter new temporary password
  5. Click "Save"
  6. User must change password on next login

Password Change (User)

Users can change their own password:

  1. Login
  2. Click profile icon (top-right)
  3. "Change Password"
  4. Enter:
    • Current password
    • New password
    • Confirm new password
  5. Click "Update Password"

OIDC/SSO Authentication

Overview

  • Integrate with external identity providers
  • Centralized user management
  • Single Sign-On (SSO) across services
  • Enterprise-grade security
  • Supports: Authentik, Keycloak, Google, Azure AD, Okta, and any standards-compliant OIDC provider

Supported OIDC Providers

Provider Tested Configuration Complexity
Authentik ✅ Yes Medium
Keycloak ✅ Yes Medium
Google Workspace ✅ Yes Easy
Azure AD (Entra ID) ✅ Yes Medium
Okta ⚠️ Should work Medium
Auth0 ⚠️ Should work Easy
Generic OIDC ✅ Yes Varies

OIDC Requirements

Your OIDC provider must support:

  • OpenID Connect (OIDC) protocol
  • Authorization Code Flow
  • ID tokens with email claim
  • HTTPS (HTTP not supported for OIDC)

Self-Hosted Provider on a Private IP

MyGarage refuses to fetch OIDC metadata from an issuer that resolves to a private/internal IP (SSRF protection). If your provider is self-hosted and its public hostname resolves to a private/LAN address on your network (split-horizon DNS), allow-list that hostname:

MYGARAGE_TRUSTED_HOSTS=auth.example.com  # comma-separated hostnames, IPs, or CIDRs

This relaxes the private-IP check for the listed hosts only; all other SSRF protections remain in effect.

Enabling OIDC Auth

Via Web UI:

  1. Visit Settings → System
  2. Change Authentication Mode to OIDC
  3. Configure OIDC settings:
    • Provider Name - Display name (e.g., "Authentik")
    • Issuer URL - Your OIDC provider's issuer endpoint
    • Client ID - From your identity provider
    • Client Secret - From your identity provider
    • Redirect URI - Auto-generated (copy this to your provider)
    • Scopes - Required scopes (default: openid profile email)
  4. Click "Test Connection" to verify configuration
  5. Save settings (takes effect immediately)
  6. Visit the web interface → click "Login with SSO"

Configuration Examples

Authentik

  1. Create an application + provider in Authentik:

    • Applications → Applications → Create; Name: MyGarage, Slug: mygarage
    • Add a new OAuth2/OIDC provider, Client Type: Confidential
    • Redirect URI: copy the Redirect URI shown in MyGarage's OIDC settings

  2. MyGarage UI Configuration (Settings → System → OIDC):

    • Provider Name: Authentik
    • Issuer URL: https://auth.example.com/application/o/mygarage/
    • Client ID / Client Secret: from the Authentik provider
    • Scopes: openid profile email

Keycloak

  1. Create Client in Keycloak:

    • Go to Clients → Create Client
    • Client ID: mygarage
    • Client Protocol: openid-connect
    • Access Type: Confidential

  2. Configure Client:

    • Valid Redirect URIs: Copy from MyGarage UI after configuration
    • Web Origins: https://mygarage.example.com
    • Get client secret from Credentials tab (copy this!)

  3. MyGarage UI Configuration (Settings → System → OIDC):

    • Provider Name: Keycloak
    • Issuer URL: https://keycloak.example.com/realms/myrealm
    • Client ID: mygarage
    • Client Secret: Paste from Keycloak
    • Scopes: openid profile email
    • Copy Redirect URI and add to Keycloak client

Google Workspace

  1. Create OAuth 2.0 Client in Google Cloud Console:

  2. Copy Client ID and Secret (shown after creation)

  3. MyGarage UI Configuration (Settings → System → OIDC):

    • Provider Name: Google
    • Issuer URL: https://accounts.google.com
    • Client ID: Paste from Google (e.g., 123456.apps.googleusercontent.com)
    • Client Secret: Paste from Google
    • Scopes: openid profile email
    • Copy Redirect URI and add to Google Cloud Console

Azure AD (Entra ID)

  1. Register Application in Azure Portal:

    • Go to Azure Active Directory → App registrations
    • Click "New registration"
    • Name: MyGarage
    • Redirect URI: Copy from MyGarage UI after configuration

  2. Configure Application:

    • Copy Application (client) ID
    • Copy Directory (tenant) ID
    • Go to Certificates & secrets → Create new client secret
    • Copy secret value (shown only once!)

  3. MyGarage UI Configuration (Settings → System → OIDC):

    • Provider Name: Azure AD
    • Issuer URL: https://login.microsoftonline.com/<tenant-id>/v2.0 (replace <tenant-id>)
    • Client ID: Paste Application (client) ID
    • Client Secret: Paste client secret value
    • Scopes: openid profile email
    • Copy Redirect URI and add to Azure app registration

OIDC User Management

Automatic User Creation

When a user logs in via OIDC for the first time:

  • MyGarage creates user account automatically
  • Email from OIDC email claim is used
  • First user becomes admin
  • Subsequent users are standard users

Role Assignment

Option 1: Manual (in MyGarage):

  • Admin logs in
  • Goes to Settings → Users
  • Edits user role (Admin or Standard)

Option 2: OIDC Admin Group: In Settings → System → OIDC, set Admin Group to a group name from your provider's groups claim. Users in that group get admin; everyone else is a standard user.

OIDC Troubleshooting

"Invalid redirect URI" Error

Cause: Redirect URI mismatch between OIDC provider and MyGarage

Fix: In Settings → System → OIDC, copy the exact Redirect URI MyGarage shows into your provider. Match protocol (https://), domain, and the /api/auth/oidc/callback path; watch trailing slashes.

"Invalid client secret" Error

Cause: Client secret incorrect or expired

Fix: Regenerate the secret in your provider, paste it into Settings → System → OIDC, and save.

"Email claim not found" Error

Cause: OIDC provider not returning email in ID token

Fix:

  1. Ensure email scope is requested
  2. Configure OIDC provider to include email claim in ID token
  3. Some providers require explicit consent for email scope

Switching Authentication Modes

From None → Local

  1. Visit Settings → System
  2. Change Authentication Mode to Local
  3. Save settings (takes effect immediately)
  4. Visit web interface → Register first user

From None → OIDC

  1. Configure OIDC provider (create client - see examples above)
  2. Visit Settings → System
  3. Change Authentication Mode to OIDC
  4. Configure OIDC settings (provider, client ID, secret, etc.)
  5. Save settings (takes effect immediately)
  6. Visit web interface → Click "Login with SSO"

From Local → OIDC

⚠️ WARNING: Existing local users will be orphaned!

Migration Steps:

  1. Export data (backup)
  2. Switch to OIDC mode
  3. Have users login via OIDC (new accounts created)
  4. Admin reassigns vehicles to new OIDC users
  5. Delete orphaned local users

Recommendation: Plan migration carefully to avoid data loss.

Session Management

JWT Token Expiration

  • Default lifetime: 2 hours
  • Sessions expire after this window; users must re-authenticate.

Logout

Users can manually logout:

  1. Click profile icon (top-right)
  2. "Logout"
  3. JWT cookie deleted
  4. Redirected to login page

Session Timeout

If inactive for longer than JWT expiration:

  • Session expires
  • User redirected to login
  • Must re-authenticate

Security Best Practices

JWT Secret

  • Auto-generated and stored at /data/secret.key — no manual setup needed.
  • Back up /data/secret.key: losing it invalidates all existing login sessions.
  • Unique per instance. Only set MYGARAGE_SECRET_KEY if you must share one secret across replicas.

HTTPS (Required for Production)

  • ✅ Always use HTTPS - JWT cookies require secure flag
  • ✅ Use reverse proxy - Traefik, Nginx, Caddy with Let's Encrypt
  • ❌ Never use HTTP in production - Session hijacking risk

Password Policies

  • ✅ Enforce strong passwords - Min 12 characters, complexity
  • ✅ Educate users - No password reuse, use password manager
  • ✅ Require password changes - After security incidents
  • ❌ Don't share accounts - Each user gets own account

Rate Limiting

Built-in rate limits (per IP):

  • Auth endpoints (login, registration, password change/reset): 5 requests per minute

Exceeding the limit returns HTTP 429 until the window passes.

Multi-User Scenarios

Family Deployment

  • Mode: Local authentication
  • Users: 2-4 users (family members)
  • Vehicles: Shared (all family members see all vehicles)
  • Setup: Each family member has own account, all vehicles shared

Small Business Garage

  • Mode: Local or OIDC authentication
  • Users: 5-20 employees
  • Vehicles: Assigned (drivers see only their vehicles)
  • Setup: Admin assigns vehicles to each driver

Enterprise SSO

  • Mode: OIDC with Okta/Azure AD
  • Users: 50+ employees
  • Vehicles: Role-based access (garage admins see all, users see assigned)
  • Setup: OIDC groups mapped to admin/user roles

Need Help?

Next: Configure Database or set up Reverse Proxy.

Clone this wiki locally