ContextQMD
Back to Lobehub

LobeHub Authentication Service Configuration

docs/self-hosting/auth.mdx

2.1.5613.4 KB
Original Source

Authentication Service

LobeHub supports the configuration of external authentication services using Better Auth for internal use within enterprises/organizations to centrally manage user authorization.

Better Auth

Better Auth is a modern, framework-agnostic authentication library designed to provide comprehensive, secure, and flexible authentication solutions. It supports various authentication methods including email/password, magic links, and multiple OAuth/SSO providers.

Key Features

  • Email/Password Authentication: Built-in support for traditional email and password login with secure password hashing
  • Email Verification: Optional email verification flow with customizable email templates
  • Magic Link Login: Passwordless authentication via email magic links
  • OAuth/SSO Support: Integration with popular identity providers including Google, GitHub, Microsoft, AWS Cognito, and more
  • Generic OIDC/OAuth: Support for any OpenID Connect or OAuth 2.0 compliant provider

Getting Started

To enable Better Auth in LobeHub, set the following environment variables:

Environment VariableTypeDescription
AUTH_SECRETRequiredKey used to encrypt session tokens. Generate using: openssl rand -base64 32
NEXT_PUBLIC_AUTH_URLRequiredThe browser-accessible base URL for Better Auth (e.g., http://localhost:3010, https://LobeHub.com). Optional for Vercel deployments (auto-detected from VERCEL_URL)
AUTH_SSO_PROVIDERSOptionalComma-separated list of enabled SSO providers, e.g., google,github,microsoft

Supported SSO Providers

ProviderValueEnvironment Variables
GooglegoogleAUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET
GitHubgithubAUTH_GITHUB_ID, AUTH_GITHUB_SECRET
MicrosoftmicrosoftAUTH_MICROSOFT_ID, AUTH_MICROSOFT_SECRET, AUTH_MICROSOFT_AUTHORITY_URL, AUTH_MICROSOFT_TENANT_ID
AppleappleAUTH_APPLE_CLIENT_ID, AUTH_APPLE_CLIENT_SECRET
AWS CognitocognitoAUTH_COGNITO_ID, AUTH_COGNITO_SECRET, AUTH_COGNITO_DOMAIN, AUTH_COGNITO_REGION, AUTH_COGNITO_USERPOOL_ID
Auth0auth0AUTH_AUTH0_ID, AUTH_AUTH0_SECRET, AUTH_AUTH0_ISSUER
AutheliaautheliaAUTH_AUTHELIA_ID, AUTH_AUTHELIA_SECRET, AUTH_AUTHELIA_ISSUER
AuthentikauthentikAUTH_AUTHENTIK_ID, AUTH_AUTHENTIK_SECRET, AUTH_AUTHENTIK_ISSUER
CasdoorcasdoorAUTH_CASDOOR_ID, AUTH_CASDOOR_SECRET, AUTH_CASDOOR_ISSUER
Cloudflare Zero Trustcloudflare-zero-trustAUTH_CLOUDFLARE_ZERO_TRUST_ID, AUTH_CLOUDFLARE_ZERO_TRUST_SECRET, AUTH_CLOUDFLARE_ZERO_TRUST_ISSUER
KeycloakkeycloakAUTH_KEYCLOAK_ID, AUTH_KEYCLOAK_SECRET, AUTH_KEYCLOAK_ISSUER
LogtologtoAUTH_LOGTO_ID, AUTH_LOGTO_SECRET, AUTH_LOGTO_ISSUER
OktaoktaAUTH_OKTA_ID, AUTH_OKTA_SECRET, AUTH_OKTA_ISSUER
ZITADELzitadelAUTH_ZITADEL_ID, AUTH_ZITADEL_SECRET, AUTH_ZITADEL_ISSUER
Generic OIDCgeneric-oidcAUTH_GENERIC_OIDC_ID, AUTH_GENERIC_OIDC_SECRET, AUTH_GENERIC_OIDC_ISSUER
FeishufeishuAUTH_FEISHU_APP_ID, AUTH_FEISHU_APP_SECRET
WeChatwechatAUTH_WECHAT_ID, AUTH_WECHAT_SECRET

Click on a provider below for detailed configuration guides:

<Cards> <Card href={'/docs/self-hosting/auth/providers/password'} title={'Email/Password'} />

<Card href={'/docs/self-hosting/auth/providers/github'} title={'GitHub'} />

<Card href={'/docs/self-hosting/auth/providers/google'} title={'Google'} />

<Card href={'/docs/self-hosting/auth/providers/microsoft'} title={'Microsoft'} />

<Card href={'/docs/self-hosting/auth/providers/apple'} title={'Apple'} />

<Card href={'/docs/self-hosting/auth/providers/cognito'} title={'AWS Cognito'} />

<Card href={'/docs/self-hosting/auth/providers/auth0'} title={'Auth0'} />

<Card href={'/docs/self-hosting/auth/providers/authelia'} title={'Authelia'} />

<Card href={'/docs/self-hosting/auth/providers/authentik'} title={'Authentik'} />

<Card href={'/docs/self-hosting/auth/providers/casdoor'} title={'Casdoor'} />

<Card href={'/docs/self-hosting/auth/providers/cloudflare-zero-trust'} title={'Cloudflare Zero Trust'} />

<Card href={'/docs/self-hosting/auth/providers/keycloak'} title={'Keycloak'} />

<Card href={'/docs/self-hosting/auth/providers/logto'} title={'Logto'} />

<Card href={'/docs/self-hosting/auth/providers/okta'} title={'Okta'} />

<Card href={'/docs/self-hosting/auth/providers/zitadel'} title={'ZITADEL'} />

<Card href={'/docs/self-hosting/auth/providers/generic-oidc'} title={'Generic OIDC'} />

<Card href={'/docs/self-hosting/auth/providers/feishu'} title={'Feishu'} />

<Card href={'/docs/self-hosting/auth/providers/wechat'} title={'WeChat'} /> </Cards>

Callback URL Format

When configuring OAuth providers, use the following callback URL format:

  • Development: http://localhost:3210/api/auth/callback/{provider}
  • Production: https://yourdomain.com/api/auth/callback/{provider}

Email/Password Options

Disable email/password login (SSO-only mode):

Set AUTH_DISABLE_EMAIL_PASSWORD=1 to hide the email input on the login page and redirect the signup page to login. Users can only sign in via configured SSO providers. Ensure at least one SSO provider is configured before enabling this.

Restrict registration to specific emails or domains:

Set AUTH_ALLOWED_EMAILS with a comma-separated list:

bash
# Allow only @example.com emails
AUTH_ALLOWED_EMAILS=example.com

# Allow multiple domains and specific addresses
AUTH_ALLOWED_EMAILS=example.com,company.org,[email protected]

<Callout type={'info'}> AUTH_ALLOWED_EMAILS restricts which emails can register, but does not verify email ownership. Combine with AUTH_EMAIL_VERIFICATION=1 to ensure users own the email they register with. </Callout>

Quick OAuth Setup Examples

Google OAuth:

  1. Create credentials at Google Cloud Console
  2. Set authorized redirect URI: https://yourdomain.com/api/auth/callback/google
  3. Configure environment variables:
bash
AUTH_SSO_PROVIDERS=google
AUTH_GOOGLE_ID=xxxxx.apps.googleusercontent.com
AUTH_GOOGLE_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxx

GitHub OAuth:

  1. Create OAuth App at GitHub Developer Settings
  2. Set callback URL: https://yourdomain.com/api/auth/callback/github
  3. Configure environment variables:
bash
AUTH_SSO_PROVIDERS=github
AUTH_GITHUB_ID=Ov23xxxxxxxxxxxxx
AUTH_GITHUB_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Email Service Configuration

Email service is required for email verification, password reset, and magic link delivery.

SMTP configuration:

bash
SMTP_HOST=smtp.gmail.com      # SMTP server hostname
SMTP_PORT=587                 # 587 for TLS (recommended), 465 for SSL
SMTP_SECURE=false             # true for port 465, false for port 587
[email protected]
SMTP_PASS=your-app-specific-password  # For Gmail, use an app-specific password
[email protected]      # Optional, defaults to SMTP_USER

For detailed configuration, see Email Service Configuration.

<Callout type={'tip'}> Go to Environment Variables for detailed information on all Better Auth variables. </Callout>

Session Storage Configuration (Optional)

By default, Better Auth uses the database to store session data. You can configure Redis as secondary storage for better performance and cross-instance session sharing.

Environment VariableTypeDescription
REDIS_URLOptionalRedis connection URL, enables Redis session storage when set
REDIS_PREFIXOptionalRedis key prefix, defaults to lobechat

<Callout type={'info'}> When Redis is configured, authentication session data will be stored in Redis, enabling session sharing across multiple service instances and faster session validation. See Redis Cache Service for detailed configuration. </Callout>

FAQ

What SSO providers does Better Auth support?

Better Auth supports built-in providers (Google, GitHub, Microsoft, Apple, AWS Cognito) and Generic OIDC providers (Auth0, Authelia, Authentik, Casdoor, Cloudflare Zero Trust, Keycloak, Logto, Okta, ZITADEL, Generic OIDC, Feishu, WeChat).

How do I enable multiple SSO providers?

Set the AUTH_SSO_PROVIDERS environment variable with a comma-separated list, e.g., google,github,microsoft. The order determines the display order on the login page.

What if Casdoor users only have username without email?

The current authentication system requires email. Please configure a valid email address for users in Casdoor. Using a real, valid email is strongly recommended, otherwise features like password reset and magic link login will not work.

Can I use fake or random email addresses?

Strongly not recommended. You should always use valid, real email addresses. Using fake emails will cause the following issues:

  • Password reset functionality will not work
  • Magic link login will not work
  • Email verification will fail
  • You may lose access to your account if you forget your password

This applies to all authentication methods, including SSO providers like Casdoor. Always ensure users have valid email addresses configured.

How do I enable SSO-only mode (disable email/password login)?

Set AUTH_DISABLE_EMAIL_PASSWORD=1 to disable email/password authentication. When enabled:

  • The email input will be hidden on the login page, only SSO buttons are displayed
  • The signup page will redirect to the login page
  • Users can only log in via configured SSO providers

Make sure you have at least one SSO provider configured via AUTH_SSO_PROVIDERS before enabling this option.

How do I restrict registration to specific emails or domains?

Set the AUTH_ALLOWED_EMAILS environment variable with a comma-separated list of allowed emails or domains. For example:

  • Allow only example.com domain: AUTH_ALLOWED_EMAILS=example.com
  • Allow multiple domains and specific emails: AUTH_ALLOWED_EMAILS=example.com,company.org,[email protected]

<Callout type={'info'}> Note: AUTH_ALLOWED_EMAILS only restricts which email addresses can register, but does not verify email ownership. If you need to ensure users actually own the email address they register with, set AUTH_EMAIL_VERIFICATION=1 to require email verification. This requires configuring an email service (SMTP). </Callout>

Additional Features

Webhook Support

Allow LobeHub to receive notifications when user information is updated in the identity provider. Supported providers include Casdoor and Logto. Please refer to the specific provider documentation for configuration details.

Other SSO Providers

If you need to use an SSO provider not included in the list above, you can use Generic OIDC to configure any OpenID Connect or OAuth 2.0 compliant provider.

Feel free to submit a Pull Request to add more built-in SSO provider support. For details, see the Better Auth documentation.