OAuth / OIDC

Since v3.2.0, BorgWarehouse supports OAuth and OpenID Connect (OIDC) sign-in. You can allow users to log in with GitHub, Google, Microsoft, GitLab, or any OIDC-compatible provider (Authentik, Keycloak, Zitadel…).

borgbackup borgwarehouse oauth

How it works

When one or more OAuth providers are configured, a sign-in button for each provider appears on the login page. Users can also link and unlink OAuth accounts from their account settings, allowing them to sign in with either their password or their linked OAuth identity.

borgwarehouse oauth

Supported providers

GitHub

  1. Go to GitHub Developer Settings → OAuth Apps → New OAuth App.
  2. Set the Authorization callback URL to: https://your-borgwarehouse-url/api/auth/callback/github
  3. Copy the Client ID and generate a Client Secret.
  4. Add to your .env:
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

Google

  1. Go to Google Cloud Console → APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID.
  2. Set the Authorized redirect URI to: https://your-borgwarehouse-url/api/auth/callback/google
  3. Add to your .env:
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

Microsoft (Azure AD / Entra ID)

  1. Go to Azure Portal → Azure Active Directory → App registrations → New registration.
  2. Set the Redirect URI to: https://your-borgwarehouse-url/api/auth/callback/microsoft
  3. Copy the Application (client) ID and create a Client Secret under Certificates & secrets.
  4. Add to your .env:
MICROSOFT_CLIENT_ID=your-client-id
MICROSOFT_CLIENT_SECRET=your-client-secret
# Optional: restrict to a specific tenant (defaults to "common" - all Microsoft accounts)
MICROSOFT_TENANT_ID=your-tenant-id

GitLab

  1. Go to your GitLab instance → User Settings → Applications → Add new application.
  2. Set the Redirect URI to: https://your-borgwarehouse-url/api/auth/callback/gitlab
  3. Select the read_user scope.
  4. Add to your .env:
GITLAB_CLIENT_ID=your-client-id
GITLAB_CLIENT_SECRET=your-client-secret

Generic OIDC (Authentik, Keycloak, Zitadel, etc.)

Any OIDC-compliant provider is supported via the generic OIDC integration.

  1. In your provider, create a new OAuth2 / OIDC application.
  2. Set the Redirect URI to: https://your-borgwarehouse-url/api/auth/callback/oidc
  3. Ensure the application exposes the openid, email, and profile scopes.
  4. Add to your .env:
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_ISSUER_URL=https://your-provider.example.com/application/o/borgwarehouse
# Optional: customize the button label on the login page (default: "SSO")
OIDC_PROVIDER_NAME=Authentik

Disable password login (OAuth-only mode)

If you want to enforce OAuth-only sign-in and disable username/password login entirely:

DISABLE_PASSWORD_LOGIN=true

Sessions

Session lifetime

Sessions are stored in a SQLite database (config/better_auth.sqlite). The default session lifetime is 1 hour. You can change it with:

# Duration in seconds. Examples:
SESSION_EXPIRY_SECONDS=3600    # 1 hour (default)
SESSION_EXPIRY_SECONDS=28800   # 8 hours
SESSION_EXPIRY_SECONDS=86400   # 24 hours

Session revocation

Session revocation is done via a CLI script that revokes all active sessions at once, forcing every user to log in again. This is useful after a security incident, a password change, or a suspected compromise.

Baremetal:

pnpm revoke:sessions

Docker:

docker exec borgwarehouse pnpm --dir /home/borgwarehouse/app revoke:sessions

Trusted origins

If BorgWarehouse is served behind a reverse proxy or from multiple domains, you may need to declare trusted origins to avoid CSRF rejections:

BETTER_AUTH_TRUSTED_ORIGINS=https://borgwarehouse.example.com,https://bw.local

Account linking

Users can link multiple OAuth providers to the same BorgWarehouse account. Go to Account Settings → Linked accounts to link or unlink providers.

← FAQ
Release notes →