mirror of
https://github.com/lobehub/lobehub.git
synced 2026-03-27 13:29:15 +07:00
43578a9bcc
* 🔖 chore(release): release version v2.1.34 [skip ci] * 📝 docs: Polish documents * 📝 docs: Fix typo * 📝 docs: Update start * 📝 docs: Fix style * 📝 docs: Update start * 📝 docs: Update layout * 📝 docs: Fix typo * 📝 docs: Fix typo --------- Co-authored-by: lobehubbot <i@lobehub.com>
248 lines
14 KiB
Plaintext
248 lines
14 KiB
Plaintext
---
|
|
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`, `AUTH_MICROSOFT_AUTHORITY_URL`, `AUTH_MICROSOFT_TENANT_ID` |
|
|
| 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/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,admin@other.com
|
|
```
|
|
|
|
<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](https://console.cloud.google.com/apis/credentials)
|
|
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](https://github.com/settings/developers)
|
|
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
|
|
SMTP_USER=your-email@gmail.com
|
|
SMTP_PASS=your-app-specific-password # For Gmail, use an app-specific password
|
|
SMTP_FROM=noreply@yourdomain.com # Optional, defaults to SMTP_USER
|
|
```
|
|
|
|
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).
|