Skip to main content
Zipline supports multiple authentication methods including local authentication, OAuth providers, TOTP-based 2FA, and passkeys.

​
User Registration

​
FEATURES_USER_REGISTRATION
boolean
default:"false"
Allow users to create new accounts via the registration page.
FEATURES_USER_REGISTRATION=true
​
FEATURES_OAUTH_REGISTRATION
boolean
default:"false"
Allow users to register using OAuth providers.
FEATURES_OAUTH_REGISTRATION=true
When both registration options are disabled, new users can only be created via invites or by administrators.

​
OAuth Configuration

Zipline supports OAuth authentication with Discord, GitHub, Google, and generic OIDC providers.

​
OAuth Settings

​
OAUTH_BYPASS_LOCAL_LOGIN
boolean
default:"false"
Hide the local login form and only show OAuth buttons on the login page.
OAUTH_BYPASS_LOCAL_LOGIN=true
​
OAUTH_LOGIN_ONLY
boolean
default:"false"
Disable OAuth registration, only allow existing users to login via OAuth.
OAUTH_LOGIN_ONLY=true

​
Discord OAuth

​
OAUTH_DISCORD_CLIENT_ID
string
Discord application client ID.
OAUTH_DISCORD_CLIENT_ID=123456789012345678
​
OAUTH_DISCORD_CLIENT_SECRET
string
Discord application client secret.
OAUTH_DISCORD_CLIENT_SECRET=your-discord-client-secret
​
OAUTH_DISCORD_REDIRECT_URI
string
default:"null"
Discord OAuth redirect URI. If not set, Zipline will auto-generate based on the request URL.
OAUTH_DISCORD_REDIRECT_URI=https://zipline.example.com/api/auth/oauth/discord
​
OAUTH_DISCORD_ALLOWED_IDS
string[]
default:"[]"
Comma-separated list of Discord user IDs that are allowed to authenticate. If empty, all users are allowed.
OAUTH_DISCORD_ALLOWED_IDS=123456789012345678,987654321098765432
​
OAUTH_DISCORD_DENIED_IDS
string[]
default:"[]"
Comma-separated list of Discord user IDs that are explicitly denied authentication.
OAUTH_DISCORD_DENIED_IDS=111111111111111111,222222222222222222

​
Discord Setup

  1. Go to Discord Developer Portal
  2. Create a new application
  3. Navigate to OAuth2 settings
  4. Add redirect URL: https://your-domain.com/api/auth/oauth/discord
  5. Copy Client ID and Client Secret
  6. Set the environment variables

​
GitHub OAuth

​
OAUTH_GITHUB_CLIENT_ID
string
GitHub OAuth application client ID.
OAUTH_GITHUB_CLIENT_ID=Iv1.abcdef1234567890
​
OAUTH_GITHUB_CLIENT_SECRET
string
GitHub OAuth application client secret.
OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret
​
OAUTH_GITHUB_REDIRECT_URI
string
default:"null"
GitHub OAuth redirect URI. If not set, auto-generated.
OAUTH_GITHUB_REDIRECT_URI=https://zipline.example.com/api/auth/oauth/github

​
GitHub Setup

  1. Go to GitHub Developer Settings
  2. Create a new OAuth App
  3. Set Homepage URL to your Zipline instance
  4. Set Authorization callback URL: https://your-domain.com/api/auth/oauth/github
  5. Copy Client ID and generate a Client Secret
  6. Set the environment variables

​
Google OAuth

​
OAUTH_GOOGLE_CLIENT_ID
string
Google OAuth 2.0 client ID.
OAUTH_GOOGLE_CLIENT_ID=123456789012-abcdefghijklmnop.apps.googleusercontent.com
​
OAUTH_GOOGLE_CLIENT_SECRET
string
Google OAuth 2.0 client secret.
OAUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret
​
OAUTH_GOOGLE_REDIRECT_URI
string
default:"null"
Google OAuth redirect URI. If not set, auto-generated.
OAUTH_GOOGLE_REDIRECT_URI=https://zipline.example.com/api/auth/oauth/google

​
Google Setup

  1. Go to Google Cloud Console
  2. Create a new project or select existing
  3. Enable Google+ API
  4. Go to Credentials → Create OAuth 2.0 Client ID
  5. Set application type to “Web application”
  6. Add authorized redirect URI: https://your-domain.com/api/auth/oauth/google
  7. Copy Client ID and Client Secret
  8. Set the environment variables

​
Generic OIDC Provider

For custom OpenID Connect providers (Keycloak, Auth0, Okta, etc.).
​
OAUTH_OIDC_CLIENT_ID
string
OIDC client ID.
OAUTH_OIDC_CLIENT_ID=zipline-client
​
OAUTH_OIDC_CLIENT_SECRET
string
OIDC client secret.
OAUTH_OIDC_CLIENT_SECRET=your-oidc-client-secret
​
OAUTH_OIDC_AUTHORIZE_URL
string
OIDC authorization endpoint URL.
OAUTH_OIDC_AUTHORIZE_URL=https://auth.example.com/realms/master/protocol/openid-connect/auth
​
OAUTH_OIDC_TOKEN_URL
string
OIDC token endpoint URL.
OAUTH_OIDC_TOKEN_URL=https://auth.example.com/realms/master/protocol/openid-connect/token
​
OAUTH_OIDC_USERINFO_URL
string
OIDC userinfo endpoint URL.
OAUTH_OIDC_USERINFO_URL=https://auth.example.com/realms/master/protocol/openid-connect/userinfo
​
OAUTH_OIDC_REDIRECT_URI
string
default:"null"
OIDC redirect URI. If not set, auto-generated.
OAUTH_OIDC_REDIRECT_URI=https://zipline.example.com/api/auth/oauth/oidc

​
OIDC Setup Examples

OAUTH_OIDC_CLIENT_ID=zipline
OAUTH_OIDC_CLIENT_SECRET=your-client-secret
OAUTH_OIDC_AUTHORIZE_URL=https://keycloak.example.com/realms/myrealm/protocol/openid-connect/auth
OAUTH_OIDC_TOKEN_URL=https://keycloak.example.com/realms/myrealm/protocol/openid-connect/token
OAUTH_OIDC_USERINFO_URL=https://keycloak.example.com/realms/myrealm/protocol/openid-connect/userinfo

OAUTH_OIDC_CLIENT_ID=your-auth0-client-id
OAUTH_OIDC_CLIENT_SECRET=your-auth0-client-secret
OAUTH_OIDC_AUTHORIZE_URL=https://your-tenant.auth0.com/authorize
OAUTH_OIDC_TOKEN_URL=https://your-tenant.auth0.com/oauth/token
OAUTH_OIDC_USERINFO_URL=https://your-tenant.auth0.com/userinfo

OAUTH_OIDC_CLIENT_ID=zipline
OAUTH_OIDC_CLIENT_SECRET=your-client-secret
OAUTH_OIDC_AUTHORIZE_URL=https://authentik.example.com/application/o/authorize/
OAUTH_OIDC_TOKEN_URL=https://authentik.example.com/application/o/token/
OAUTH_OIDC_USERINFO_URL=https://authentik.example.com/application/o/userinfo/

​
Multi-Factor Authentication (MFA)

Zipline supports two types of MFA: TOTP (Time-based One-Time Password) and Passkeys (WebAuthn).

​
TOTP (2FA)

​
MFA_TOTP_ENABLED
boolean
default:"false"
Enable TOTP-based two-factor authentication.
MFA_TOTP_ENABLED=true
​
MFA_TOTP_ISSUER
string
default:"Zipline"
Issuer name displayed in authenticator apps.
MFA_TOTP_ISSUER=MyZipline
When enabled, users can:
  1. Navigate to their account settings
  2. Enable two-factor authentication
  3. Scan the QR code with an authenticator app (Google Authenticator, Authy, etc.)
  4. Enter the 6-digit code to confirm setup
TOTP codes are generated using the standard TOTP algorithm (RFC 6238) and are compatible with all major authenticator apps.

​
Passkeys (WebAuthn)

​
MFA_PASSKEYS_ENABLED
boolean
default:"false"
Enable passkey authentication using WebAuthn.
MFA_PASSKEYS_ENABLED=true
​
MFA_PASSKEYS_RP_ID
string
default:"null"
Relying Party ID for WebAuthn. Should be your domain name.
MFA_PASSKEYS_RP_ID=zipline.example.com
​
MFA_PASSKEYS_ORIGIN
string
default:"null"
Origin URL for WebAuthn. Must match the URL users access Zipline from.
MFA_PASSKEYS_ORIGIN=https://zipline.example.com
Both MFA_PASSKEYS_RP_ID and MFA_PASSKEYS_ORIGIN must be set correctly for passkeys to work. The RP ID must be a valid domain that matches the origin.

​
Passkey Setup Example

MFA_PASSKEYS_ENABLED=true
MFA_PASSKEYS_RP_ID=files.example.com
MFA_PASSKEYS_ORIGIN=https://files.example.com
Supported authenticators:
  • Hardware security keys (YubiKey, etc.)
  • Platform authenticators (Windows Hello, Touch ID, Face ID)
  • Mobile device biometrics

​
Invite System

When user registration is disabled, the invite system controls access.
​
INVITES_ENABLED
boolean
default:"true"
Enable the invite system.
INVITES_ENABLED=true
​
INVITES_LENGTH
number
default:"6"
Length of generated invite codes.
INVITES_LENGTH=8
Administrators can create invites with:
  • Custom expiration dates
  • Maximum use limits
  • Single-use or multi-use codes

​
Security Best Practices

  • Always use HTTPS for production deployments
  • Keep client secrets secure (use environment variables, not config files)
  • Regularly rotate OAuth client secrets
  • Use OAUTH_DISCORD_ALLOWED_IDS to restrict access when needed
  • Set specific redirect URIs in provider settings (don’t use wildcards)
  • Enable at least one MFA method for administrators
  • Encourage users to enable 2FA on their accounts
  • Keep backup codes secure
  • Test passkey configuration in multiple browsers
  • Disable public registration for private instances
  • Use invite system for controlled access
  • Enable OAUTH_LOGIN_ONLY to prevent OAuth-based registration
  • Monitor new user registrations

​
Troubleshooting

​
OAuth Issues

Error: “redirect_uri_mismatch”
  • Ensure redirect URI in provider settings matches exactly
  • Check for trailing slashes
  • Verify HTTPS vs HTTP
Error: “invalid_client”
  • Client ID or secret is incorrect
  • Client may be disabled in provider settings
Users can’t register via OAuth
  • Check FEATURES_OAUTH_REGISTRATION=true
  • Verify OAUTH_LOGIN_ONLY=false

​
MFA Issues

TOTP codes not working
  • Ensure server time is synchronized (use NTP)
  • Check that user’s device time is correct
  • Verify the issuer name matches
Passkeys not appearing
  • Verify MFA_PASSKEYS_ENABLED=true
  • Check MFA_PASSKEYS_RP_ID matches your domain
  • Ensure MFA_PASSKEYS_ORIGIN includes protocol (https://)
  • Browser must support WebAuthn

​
Next Steps

Security Configuration

Rate limiting and security settings

Customization

Website branding and themes

Build docs developers (and LLMs) love

Get started for freeTalk to us