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 86
lobehub/docs/self-hosting/advanced/auth.mdx
YuTengjing 7449b2913f
✨ feat: email provider support resend (#10557)
2025-12-02 19:05:08 +08:00

195 lines
16 KiB
Text
Raw Blame History

---
title: LobeChat Authentication Service Configuration
description: >-
Learn how to configure external authentication services using Better Auth, Clerk, or Next Auth for centralized user authorization management. Supported authentication services include Auth0, Azure ID, etc.
tags:
- Authentication Service
- Better Auth
- Next Auth
- SSO
- Clerk
---
# Authentication Service
LobeChat supports the configuration of external authentication services using Better Auth, Clerk, or Next Auth for internal use within enterprises/organizations to centrally manage user authorization.
## Clerk
Clerk is a comprehensive identity verification solution that has recently gained popularity. It provides a simple yet powerful API and services to handle user authentication and session management. Clerk's design philosophy is to offer a concise and modern authentication solution that enables developers to easily integrate and use it.
LobeChat has deeply integrated with Clerk to provide users with a more secure and convenient login and registration experience. It also relieves developers from the burden of managing authentication logic. Clerk's concise and modern design philosophy aligns perfectly with LobeChat's goals, making user management on the entire platform more efficient and reliable.
By setting the environment variables `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` in LobeChat's environment, you can enable and use Clerk.
## 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 LobeChat, set the following environment variables:
| Environment Variable | Type | Description |
| -------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_ENABLE_BETTER_AUTH` | Required | Set to `1` to enable Better Auth service |
| `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://lobechat.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` |
<Callout type={'error'}>
**Important**: Better Auth is currently only suitable for **fresh deployments**. If you are already using NextAuth or Clerk and have existing user data in your database, **do not switch to Better Auth yet**, otherwise existing users will not be able to log in.
We are developing user data migration tools from NextAuth/Clerk to Better Auth. Documentation will be updated once the migration solution is complete. For progress updates, please follow [GitHub Issue #10456](https://github.com/lobehub/lobe-chat/issues/10456).
</Callout>
<Callout type={'warning'}>
If you build/deploy with the official Docker image, the defaults keep **NextAuth enabled** and **Better
Auth disabled** (`NEXT_PUBLIC_ENABLE_NEXT_AUTH=1`, `NEXT_PUBLIC_ENABLE_BETTER_AUTH=0`) to avoid unexpected
login redirects. To switch to Better Auth, set both build args and runtime envs explicitly:
`NEXT_PUBLIC_ENABLE_BETTER_AUTH=1` and `NEXT_PUBLIC_ENABLE_NEXT_AUTH=0`, then rebuild the image.
</Callout>
### 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` |
| AWS Cognito | `cognito` | `AUTH_COGNITO_ID`, `AUTH_COGNITO_SECRET`, `AUTH_COGNITO_ISSUER` |
| 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` |
### 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
Used by email verification, password reset, and magic-link delivery. Choose a provider, then fill the matching variables:
| Environment Variable | Type | Description |
| ------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_AUTH_EMAIL_VERIFICATION` | Optional | Set to `1` to require email verification before users can sign in |
| `EMAIL_SERVICE_PROVIDER` | Optional | Email provider selector: `nodemailer` (default, SMTP) or `resend` |
| `SMTP_HOST` | Required | SMTP server hostname (e.g., `smtp.gmail.com`). Used when `EMAIL_SERVICE_PROVIDER=nodemailer` |
| `SMTP_PORT` | Required | SMTP server port (usually `587` for TLS, `465` for SSL). Used when `EMAIL_SERVICE_PROVIDER=nodemailer` |
| `SMTP_SECURE` | Optional | `true` for SSL (port 465), `false` for TLS (port 587). Used when `EMAIL_SERVICE_PROVIDER=nodemailer` |
| `SMTP_USER` | Required | SMTP auth username. Used when `EMAIL_SERVICE_PROVIDER=nodemailer` |
| `SMTP_PASS` | Required | SMTP auth password. Used when `EMAIL_SERVICE_PROVIDER=nodemailer` |
| `RESEND_API_KEY` | Required | Resend API key. Required when `EMAIL_SERVICE_PROVIDER=resend` |
| `RESEND_FROM` | Recommended | Default sender address (e.g., `noreply@your-verified-domain.com`). Must be a domain verified in Resend. Used when `EMAIL_SERVICE_PROVIDER=resend` |
### Magic Link (Passwordless) Login
Enable BetterAuth magic-link login (depends on a working email provider above):
| Environment Variable | Type | Description |
| ------------------------------- | -------- | -------------------------------------------------- |
| `NEXT_PUBLIC_ENABLE_MAGIC_LINK` | Optional | Set to `1` to enable passwordless magic-link login |
<Callout type={'tip'}>
For detailed provider configuration, refer to the [Next Auth provider documentation](/docs/self-hosting/advanced/auth/next-auth) as most configurations are compatible, or visit the official [Better Auth documentation](https://www.better-auth.com/docs/introduction).
</Callout>
<Callout type={'tip'}>
Go to [📘 Environment Variables](/docs/self-hosting/environment-variables/auth#better-auth) for detailed information on all Better Auth variables.
</Callout>
## Next Auth
Before using NextAuth, please set the following variables in LobeChat's environment variables:
| Environment Variable | Type | Description |
| -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NEXT_PUBLIC_ENABLE_NEXT_AUTH` | Required | This is used to enable the NextAuth service. Set it to `1` to enable it; changing this setting requires recompiling the application. Users deploying with the `lobehub/lobe-chat-database` image have this configuration added by default. |
| `AUTH_SECRET` | Required | The key used to encrypt Auth.js session tokens. You can use the following command: `openssl rand -base64 32`, or visit `https://generate-secret.vercel.app/32` to generate the key. |
| `AUTH_URL` | Required | This URL specifies the callback address for Auth.js when performing OAuth verification. Set this only if the default generated redirect address is incorrect. `https://example.com/api/auth` |
| `NEXT_AUTH_SSO_PROVIDERS` | Optional | This environment variable is used to enable multiple identity verification sources simultaneously, separated by commas, for example, `auth0,microsoft-entra-id,authentik`. |
| `NEXT_AUTH_SSO_SESSION_STRATEGY` | Optional | The session strategy for Auth.js. Options are `jwt` or `database`. Default is `jwt`. |
Currently supported identity verification services include:
<Cards>
<Card href={'/docs/self-hosting/advanced/auth/next-auth/auth0'} title={'Auth0'} />
<Card href={'/docs/self-hosting/advanced/auth/next-auth/microsoft-entra-id'} title={'Microsoft Entra ID'} />
<Card href={'/docs/self-hosting/advanced/auth/next-auth/authentik'} title={'Authentik'} />
<Card href={'/docs/self-hosting/advanced/auth/next-auth/github'} title={'Github'} />
<Card href={'/docs/self-hosting/advanced/auth/next-auth/zitadel'} title={'ZITADEL'} />
<Card href={'/docs/self-hosting/advanced/auth/next-auth/cloudflare-zero-trust'} title={'Cloudflare Zero Trust'} />
<Card href={'/docs/self-hosting/advanced/auth/next-auth/authelia'} title={'Authelia'} />
<Card href={'/docs/self-hosting/advanced/auth/next-auth/logto'} title={'Logto'} />
<Card href={'/docs/self-hosting/advanced/auth/next-auth/keycloak'} title={'Keycloak'} />
<Card href={'/docs/self-hosting/advanced/auth/next-auth/google'} title={'Google'} />
<Card href={'/docs/self-hosting/advanced/auth/next-auth/okta'} title={'Okta'} />
</Cards>
Click on the links to view the corresponding platform's configuration documentation.
## Advanced Configuration
To simultaneously enable multiple identity verification sources, please set the `NEXT_AUTH_SSO_PROVIDERS` environment variable, separating them with commas, for example, `auth0,microsoft-entra-id,authentik`.
The order corresponds to the display order of the SSO providers.
| SSO Provider | Value | Additional Features |
| --------------------- | ----------------------- | ------------------- |
| Auth0 | `auth0` | |
| Authenlia | `authenlia` | |
| Authentik | `authentik` | |
| Casdoor | `casdoor` | `Webhook` |
| Cloudflare Zero Trust | `cloudflare-zero-trust` | |
| Github | `github` | |
| Logto | `logto` | `Webhook` |
| Microsoft Entra ID | `microsoft-entra-id` | |
| ZITADEL | `zitadel` | |
| Keycloak | `keycloak` | |
| Google | `google` | |
| Okta | `okta` | |
## Additional Features
### Webhook Support
Allow LobeChat 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.
### Database Session
Allow the session store in database, see also the [Auth.js Session Documentation](https://authjs.dev/concepts/session-strategies#database-session).
## Other SSO Providers
Please refer to the [Auth.js](https://authjs.dev/getting-started/authentication/oauth) documentation and feel free to submit a Pull Request.
Reference in a new issue View git blame Copy permalink