mirror of
https://github.com/lobehub/lobehub
synced 2026-04-21 09:37:28 +00:00
3dfc86fd0f
* feat: Redesign doc
* chore: uopdate site
* chore: uopdate site
* chore: uopdate site
* chore: uopdate site
* chore: uopdate site
* feat: Uopdate content
* chore: New doc
* chore: Update content
* chore: Update content
* chore: add images
* chore: add images
* chore: add images
* chore: add images
* feat: Add more images
* feat: Add more images
* fix: Cannot reach end
* chore: Update content
* chore: Update content
* chore: Update content
* chore: Update content
* chore: Update content
* Revise README content and structure
Updated README to reflect changes in project description and removed outdated notes.
* Revise 'Getting Started' and TOC in README
Updated the 'Getting Started' section and modified the table of contents.
* chore: Update content
* Revise README structure and content
Updated the Getting Started section and removed the Table of Contents. Adjusted the Local Development instructions.
* Remove custom themes section from README
Removed section about custom themes from README.
* Update README.md
* Refine introduction and highlight cloud version
Updated wording for clarity and added recommendation for cloud version.
* chore: Update content
* chore: Update content
* chore: Update content
* chore: Update content
* chore: Update content
* chore: Update content
* chore: Update content
* fix: add missing translation
* 🔀 chore: Move README changes to feat/readme branch
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix: add missing translation
* chore: update cdn
* docs: add migration guide from v1.x local database to v2.x and update help sections
Signed-off-by: Innei <tukon479@gmail.com>
* fix: add missing translation
* fix: add missing images
* fix: add missing changelogs
* fix: add missing changelogs
* fix: add missing changelogs
* fix: add missing changelogs
* fix: add missing changelogs
* style: update cdn
---------
Signed-off-by: Innei <tukon479@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: canisminor1990 <i@canisminor.cc>
Co-authored-by: Innei <tukon479@gmail.com>
215 lines
15 KiB
Text
215 lines
15 KiB
Text
---
|
|
title: LobeHub 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
|
|
- SSO
|
|
---
|
|
|
|
# Authentication Service
|
|
|
|
LobeHub 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.
|
|
|
|
<Callout type={'info'}>
|
|
Looking for legacy authentication methods? See [Legacy Authentication](/docs/self-hosting/advanced/auth/legacy) for NextAuth and Clerk documentation.
|
|
</Callout>
|
|
|
|
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.
|
|
|
|
LobeHub 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 LobeHub'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 LobeHub'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 LobeHub, 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://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/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
|
|
|
|
Used by email verification, password reset, and magic-link delivery. Two providers are supported:
|
|
|
|
### Option 1: Nodemailer (SMTP)
|
|
|
|
Send emails via SMTP protocol, suitable for users with existing email services. See [Nodemailer SMTP docs](https://nodemailer.com/smtp/).
|
|
|
|
| Environment Variable | Type | Description | Example |
|
|
| ------------------------ | -------- | -------------------------------------------------------------- | --------------------- |
|
|
| `EMAIL_SERVICE_PROVIDER` | Optional | Set to `nodemailer` (default) | `nodemailer` |
|
|
| `SMTP_HOST` | Required | SMTP server hostname | `smtp.gmail.com` |
|
|
| `SMTP_PORT` | Required | SMTP server port (`587` for TLS, `465` for SSL) | `587` |
|
|
| `SMTP_SECURE` | Optional | `true` for SSL (port 465), `false` for TLS (port 587) | `false` |
|
|
| `SMTP_USER` | Required | SMTP auth username | `user@gmail.com` |
|
|
| `SMTP_PASS` | Required | SMTP auth password | `your-app-password` |
|
|
| `SMTP_FROM` | Optional | Sender address (required for AWS SES), defaults to `SMTP_USER` | `noreply@example.com` |
|
|
|
|
<Callout type={'warning'}>
|
|
When using Gmail, you must use an App Password instead of your account password. Generate one at [Google App Passwords](https://myaccount.google.com/apppasswords).
|
|
</Callout>
|
|
|
|
### Option 2: Resend
|
|
|
|
[Resend](https://resend.com/) is a modern email API service with simple setup, recommended for new users.
|
|
|
|
| Environment Variable | Type | Description | Example |
|
|
| ------------------------ | ----------- | ----------------------------------------- | --------------------------- |
|
|
| `EMAIL_SERVICE_PROVIDER` | Required | Set to `resend` | `resend` |
|
|
| `RESEND_API_KEY` | Required | Resend API Key | `re_xxxxxxxxxxxxxxxxxxxxxx` |
|
|
| `RESEND_FROM` | Recommended | Sender address, must be a verified domain | `noreply@your-domain.com` |
|
|
|
|
<Callout type={'info'}>
|
|
Before using Resend, you need to [verify your sending domain](https://resend.com/docs/dashboard/domains/introduction), otherwise emails can only be sent to your own address.
|
|
</Callout>
|
|
|
|
### Common Configuration
|
|
|
|
Before using NextAuth, please set the following variables in LobeHub's environment variables:
|
|
|
|
## Magic Link (Passwordless) Login
|
|
|
|
Enable magic-link login (depends on a working email provider above, off by default):
|
|
|
|
| Environment Variable | Type | Description |
|
|
| ------------------------ | -------- | ------------------------------------------------------------------- |
|
|
| `AUTH_ENABLE_MAGIC_LINK` | Optional | Set to `1` to enable passwordless magic-link login (off by default) |
|
|
|
|
<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.
|
|
|
|
### 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`
|
|
|
|
## 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.
|
|
|
|
### 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.
|