lobe-chat/docs/self-hosting/advanced/auth.mdx

---
title: LobeChat Authentication Service Configuration
description: >-
  Learn how to configure Better Auth for centralized user authorization
  management. Supported SSO providers include Google, GitHub, Microsoft, and
  more.
tags:
  - Authentication Service
  - Better Auth
  - SSO
---

# Authentication Service

LobeChat uses [Better Auth](https://www.better-auth.com) as its authentication solution, providing comprehensive, secure, and flexible identity verification for self-hosted deployments.

<Callout type={'info'}>
  Looking for legacy authentication methods? See [Legacy Authentication](/docs/self-hosting/advanced/auth/legacy) for NextAuth and Clerk documentation.
</Callout>

## 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                                                                    |
| -------------------- | -------- | ------------------------------------------------------------------------------ |
| `AUTH_SECRET`        | Required | Key used to encrypt session tokens. Generate using: `openssl rand -base64 32`  |
| `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

| Environment Variable      | Type     | Description                                               | Example |
| ------------------------- | -------- | --------------------------------------------------------- | ------- |
| `AUTH_EMAIL_VERIFICATION` | Optional | Set to `1` to require email verification (off by default) | `1`     |

## Magic Link (Passwordless) Login

Enable magic-link login (depends on a working email provider above, off by default):

| Environment Variable | Type     | Description                                                         |
| -------------------- | -------- | ------------------------------------------------------------------- |
| `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`

Leave empty to allow all emails. This restriction applies to both email registration and SSO login.