Elgato_dark/lobehub
1
0
Fork 0
mirror of https://github.com/lobehub/lobehub synced 2026-04-21 17:47:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 71
lobehub/docs/self-hosting/auth.mdx

185 lines
12 KiB
Text
Raw Blame History

---
title: LobeHub Authentication Service Configuration
description: >-
Learn how to configure external authentication services using Better Auth
for centralized user authorization management. Supported
authentication services include Auth0, Azure ID, etc.
tags:
- Authentication Service
- Better Auth
- SSO
---
# 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](https://www.better-auth.com) 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 Variable | Type | Description |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_SECRET` | Required | Key used to encrypt session tokens. Generate using: `openssl rand -base64 32` |
| `NEXT_PUBLIC_AUTH_URL` | Required | The 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_PROVIDERS` | Optional | Comma-separated list of enabled SSO providers, e.g., `google,github,microsoft` |
## Supported SSO Providers
| Provider | Value | Environment Variables |
| --------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Google | `google` | `AUTH_GOOGLE_ID`, `AUTH_GOOGLE_SECRET` |
| GitHub | `github` | `AUTH_GITHUB_ID`, `AUTH_GITHUB_SECRET` |
| Microsoft | `microsoft` | `AUTH_MICROSOFT_ID`, `AUTH_MICROSOFT_SECRET` |
| Apple | `apple` | `AUTH_APPLE_CLIENT_ID`, `AUTH_APPLE_CLIENT_SECRET` |
| AWS Cognito | `cognito` | `AUTH_COGNITO_ID`, `AUTH_COGNITO_SECRET`, `AUTH_COGNITO_DOMAIN`, `AUTH_COGNITO_REGION`, `AUTH_COGNITO_USERPOOL_ID` |
| Auth0 | `auth0` | `AUTH_AUTH0_ID`, `AUTH_AUTH0_SECRET`, `AUTH_AUTH0_ISSUER` |
| Authelia | `authelia` | `AUTH_AUTHELIA_ID`, `AUTH_AUTHELIA_SECRET`, `AUTH_AUTHELIA_ISSUER` |
| Authentik | `authentik` | `AUTH_AUTHENTIK_ID`, `AUTH_AUTHENTIK_SECRET`, `AUTH_AUTHENTIK_ISSUER` |
| Casdoor | `casdoor` | `AUTH_CASDOOR_ID`, `AUTH_CASDOOR_SECRET`, `AUTH_CASDOOR_ISSUER` |
| Cloudflare Zero Trust | `cloudflare-zero-trust` | `AUTH_CLOUDFLARE_ZERO_TRUST_ID`, `AUTH_CLOUDFLARE_ZERO_TRUST_SECRET`, `AUTH_CLOUDFLARE_ZERO_TRUST_ISSUER` |
| Keycloak | `keycloak` | `AUTH_KEYCLOAK_ID`, `AUTH_KEYCLOAK_SECRET`, `AUTH_KEYCLOAK_ISSUER` |
| Logto | `logto` | `AUTH_LOGTO_ID`, `AUTH_LOGTO_SECRET`, `AUTH_LOGTO_ISSUER` |
| Okta | `okta` | `AUTH_OKTA_ID`, `AUTH_OKTA_SECRET`, `AUTH_OKTA_ISSUER` |
| ZITADEL | `zitadel` | `AUTH_ZITADEL_ID`, `AUTH_ZITADEL_SECRET`, `AUTH_ZITADEL_ISSUER` |
| Generic OIDC | `generic-oidc` | `AUTH_GENERIC_OIDC_ID`, `AUTH_GENERIC_OIDC_SECRET`, `AUTH_GENERIC_OIDC_ISSUER` |
| Feishu | `feishu` | `AUTH_FEISHU_APP_ID`, `AUTH_FEISHU_APP_SECRET` |
| WeChat | `wechat` | `AUTH_WECHAT_ID`, `AUTH_WECHAT_SECRET` |
Click on a provider below for detailed configuration guides:
<Cards>
<Card href={'/docs/self-hosting/advanced/auth/providers/password'} title={'Email/Password'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/github'} title={'GitHub'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/google'} title={'Google'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/microsoft'} title={'Microsoft'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/apple'} title={'Apple'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/cognito'} title={'AWS Cognito'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/auth0'} title={'Auth0'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/authelia'} title={'Authelia'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/authentik'} title={'Authentik'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/casdoor'} title={'Casdoor'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/cloudflare-zero-trust'} title={'Cloudflare Zero Trust'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/keycloak'} title={'Keycloak'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/logto'} title={'Logto'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/okta'} title={'Okta'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/zitadel'} title={'ZITADEL'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/generic-oidc'} title={'Generic OIDC'} />
<Card href={'/docs/self-hosting/advanced/auth/providers/feishu'} title={'Feishu'} />
<Card href={'/docs/self-hosting/advanced/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 Service Configuration
Email service is used for email verification, password reset, and magic link delivery. For detailed configuration, see [Email Service Configuration](/docs/self-hosting/auth/email).
<Callout type={'tip'}>
Go to [Environment Variables](/docs/self-hosting/environment-variables/auth#better-auth) 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 Variable | Type | Description |
| -------------------- | -------- | ------------------------------------------------------------ |
| `REDIS_URL` | Optional | Redis connection URL, enables Redis session storage when set |
| `REDIS_PREFIX` | Optional | Redis 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](/docs/self-hosting/advanced/redis) 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,admin@other.com`
<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](/docs/self-hosting/auth/providers/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](https://www.better-auth.com/docs/concepts/oauth).
Reference in a new issue View git blame Copy permalink