SSO / OIDC

Configure Single Sign-On with OpenID Connect providers.

Overview

DBackup supports SSO authentication via OIDC (OpenID Connect):

• Centralized authentication
• Enterprise identity providers
• Automatic user provisioning
• Domain-based routing

Supported Providers

Provider	Type	Adapter
Authelia	Self-hosted	Pre-configured
Authentik	Self-hosted	Pre-configured
Keycloak	Self-hosted	Pre-configured
PocketID	Self-hosted	Pre-configured
Generic	Any OIDC	Manual configuration

Pre-configured adapters automatically generate endpoints from a base URL or discovery.

Adding an SSO Provider

Step 1: Configure Your Identity Provider

Create an OIDC application in your identity provider:

Required settings:

• Redirect URI: https://your-dbackup-url/api/auth/sso/callback/{provider-id}
• Grant type: Authorization Code
• Scopes: openid, profile, email

Obtain:

• Client ID
• Client Secret

Step 2: Add Provider in DBackup

1. Go to Settings → SSO Providers
2. Click Add Provider
3. Select adapter type (Authelia, Authentik, PocketID, Keycloak or Generic)
4. Fill in configuration
5. Click Test to verify
6. Save

Provider Configuration

Authelia

Authelia is a self-hosted authentication and authorization server.

Configuration:

Field	Description	Example
Name	Display name	"Authelia"
Authelia URL	Authelia instance URL	https://auth.example.com
Client ID	From your Authelia client	dbackup
Client Secret	The plaintext secret	secret-key

Endpoints are discovered via {baseUrl}/.well-known/openid-configuration.

The client secret is stored hashed in Authelia

Since Authelia 4.38 the client_secret in configuration.yml has to be a hash, while DBackup needs the plaintext value. Generate a pair with:

authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72

Put the Digest in Authelia's config and the Random Password into DBackup. Pasting the hash into DBackup produces an invalid_client error at sign-in.

Client registration in Authelia's configuration.yml:

identity_providers:
  oidc:
    clients:
      - client_id: dbackup
        client_name: DBackup
        client_secret: '$pbkdf2-sha512$...'  # the Digest, not the plaintext
        redirect_uris:
          - 'https://dbackup.example.com/api/auth/sso/callback/{provider-id}'
        scopes: [openid, profile, email]

Replace {provider-id} with the provider ID DBackup shows on the provider card.

Authentik

Authentik is a popular self-hosted identity provider.

Configuration:

Field	Description	Example
Name	Display name	"Corporate Login"
Base URL	Authentik instance URL	https://auth.example.com
Client ID	From Authentik app	dbackup-client
Client Secret	From Authentik app	secret-key

Endpoints are auto-generated:

Authorization: {baseUrl}/application/o/authorize/
Token: {baseUrl}/application/o/token/
UserInfo: {baseUrl}/application/o/userinfo/

Keycloak

Keycloak is an enterprise-grade open-source identity and access management solution.

Configuration:

Field	Description	Example
Name	Display name	"Company SSO"
Keycloak URL	Keycloak instance base URL	https://auth.company.com
Realm Name	Authentication realm	master
Client ID	From Keycloak client	dbackup-client
Client Secret	From Keycloak client	secret-key

Notes:

• Endpoints discovered via OIDC Discovery (.well-known/openid-configuration)
• Supports both modern (Quarkus) and legacy versions
• For Keycloak < 18: Include /auth in base URL (e.g., https://auth.company.com/auth)

PocketID

PocketID is a lightweight OIDC provider.

Configuration:

Field	Description	Example
Name	Display name	"PocketID"
Base URL	PocketID instance URL	https://pocketid.example.com
Client ID	From PocketID	client-id
Client Secret	From PocketID	secret

Generic OIDC

For any OIDC-compliant provider (Keycloak, Okta, Azure AD, etc.).

Configuration:

Field	Description
Name	Display name
Issuer	OIDC issuer URL
Authorization URL	OAuth authorize endpoint
Token URL	OAuth token endpoint
UserInfo URL	OIDC userinfo endpoint
Client ID	Application client ID
Client Secret	Application client secret

User Flow

New Users (Auto-Provisioning)

When SSO user first logs in:

1. Redirect to identity provider
2. User authenticates
3. Returns to DBackup with tokens
4. New user account created
5. No permissions by default (must be assigned to group)

Existing Users (Account Linking)

If email matches existing account:

1. Accounts are linked
2. User can login via SSO or password
3. Permissions are preserved

Domain Mapping

Route users to specific SSO provider by email domain:

1. Edit SSO provider
2. Set Email Domain: company.com
3. Users with @company.com email see this provider

Multiple domains: separate with commas

company.com, subsidiary.com

Login Page Behavior

When SSO providers are configured:

• "Sign in with [Provider]" buttons appear
• Users can choose SSO or password login
• Domain-matched users may auto-redirect

Two environment variables change this. Both are set on the container rather than in the UI, because either one can lock you out and the lever has to work without signing in.

Switching off password login

DISABLE_EMAIL_LOGIN=true removes the email and password form. Only SSO and passkeys remain, and the endpoints are rejected server-side rather than just hidden. Administrators keep creating users and resetting passwords under Users, since an account often has to exist before it can link to an SSO identity.

Passkey login has its own switch under Settings → General and needs no environment variable.

Order matters on a new instance

Create the first administrator and configure your provider before setting this. There is no bootstrap exception - on an empty instance it leaves no way to sign in and no way to create an account.

Skipping the login page entirely

OIDC_AUTO_REDIRECT takes a provider ID and sends visitors straight to that provider:

OIDC_AUTO_REDIRECT=authentik-742

The ID is shown on the provider card in this tab and is the same one in its callback URL.

The redirect is skipped after a failed sign-in, so the error is readable instead of looping, and on the page load right after signing out, so signing out actually works. An ID matching no enabled provider logs an error at startup and leaves the redirect off rather than stopping the application.

No way past it from the browser

While this is set, nothing in the URL reaches the login form. If the provider is unreachable or misconfigured, remove the variable and restart.

Security Considerations

Token Storage

• Access tokens stored in session
• Refresh handled automatically
• No tokens stored in database

Permissions

SSO users follow same permission model:

• Assigned to groups
• Inherit group permissions
• No special SSO permissions

Credential Encryption

Client secrets are encrypted:

• Stored encrypted in database
• Uses ENCRYPTION_KEY
• Never exposed in logs

Best Practices

Provider Setup

1. Use dedicated OAuth app for DBackup
2. Limit scopes to minimum needed
3. Set appropriate token lifetimes
4. Configure redirect URIs exactly

User Management

1. Default group for new SSO users
2. Regular access reviews
3. Disable unused providers
4. Document domain mappings

High Availability

1. Provider availability affects login
2. Keep password fallback for admins
3. Monitor SSO health

Troubleshooting

Login Fails with "Invalid Callback"

Cause: Redirect URI mismatch

Solution:

1. Check redirect URI in identity provider
2. Must exactly match: https://your-domain/api/auth/sso/callback/{provider-id}
3. Include trailing slash if configured

"User Not Found" After SSO

Cause: Auto-provisioning issue

Check:

1. Email claim is returned
2. User created in database
3. Group assignment

Token Expired Errors

Cause: Session or refresh token expired

Solution:

1. Re-authenticate
2. Check token lifetimes in IdP
3. Verify clock sync

Can't Connect to Provider

Check:

1. Network connectivity
2. DNS resolution
3. Firewall rules
4. SSL certificates

Provider-Specific Guides

Keycloak Setup (Pre-configured Adapter)

If using the Keycloak adapter (recommended):

1. In Keycloak admin console, select your realm
2. Go to Clients → Create client
3. Configure:
   • Client type: OpenID Connect
   • Client ID: dbackup
   • Client authentication: On
4. Set Valid redirect URIs: https://dbackup.example.com/*
5. Save and go to Credentials tab
6. Copy Client secret
7. In DBackup:
   • Select Keycloak adapter
   • Base URL: https://auth.company.com (or https://auth.company.com/auth for legacy versions)
   • Realm: Your realm name (e.g., master)
   • Client ID & Secret from Keycloak

Keycloak Setup (Generic Adapter)

If you prefer manual configuration:

1. Create realm or use existing
2. Create client:
   • Client type: OpenID Connect
   • Client authentication: On
   • Valid redirect URIs: https://dbackup.example.com/*
3. Note client ID and secret
4. Use Generic adapter with:

   Issuer: https://keycloak.example.com/realms/your-realm
   Auth URL: {issuer}/protocol/openid-connect/auth
   Token URL: {issuer}/protocol/openid-connect/token
   UserInfo: {issuer}/protocol/openid-connect/userinfo

Azure AD Setup

1. Register application in Azure Portal
2. Configure:
   • Redirect URI: https://dbackup.example.com/api/auth/sso/callback/azure
   • Implicit grant: ID tokens
3. Create client secret
4. Use Generic adapter with:

   Issuer: https://login.microsoftonline.com/{tenant-id}/v2.0

Google Workspace

1. Create OAuth 2.0 credentials in Google Cloud
2. Configure consent screen
3. Add redirect URI
4. Use Generic adapter

Next Steps

• User Management - Manage user accounts
• Groups & Permissions - Configure access