Better Auth is the recommended authentication solution for LobeHub. It offers simpler configuration, more SSO providers, and better self-hosting support.
- This guide is intended for users with development experience; not recommended for users without technical background
- If you have any questions, feel free to ask in our [Discord](https://discord.com/invite/AYFPHvv2jT) community or [GitHub Issue](https://github.com/lobehub/lobe-chat/issues)
</Callout>
## Choose Your Migration Path
| Method | Best For | User Impact | Data Preserved |
| [Simple Migration](#simple-migration) | Small deployments (≤ 10 users) | Users need to re-login | Chat history, settings |
| [Full Migration](#full-migration) | Large deployments | Seamless for users | Everything including SSO connections |
<Callout type={'info'}>
**Note**: NextAuth never supported email/password login, so there are no password hashes to migrate. The main benefit of full migration is preserving SSO connections (Google, GitHub, etc.).
**Note**: Microsoft Entra ID provider name changed from `microsoft-entra-id` to `microsoft`, and the environment variable prefix changed from `AUTH_MICROSOFT_ENTRA_ID_` to `AUTH_MICROSOFT_`.
</Callout>
### New Feature Variables
Better Auth supports additional features with these new environment variables:
Inform users to log in again with their previous SSO account. Chat history and settings will be preserved since user IDs remain the same.
<Callout type={'tip'}>
This method is quick and requires minimal setup. Users just need to re-login with their existing SSO provider.
</Callout>
## Full Migration
For larger deployments or when you need to preserve SSO connections, use the migration script. This migrates data from the `nextauth_accounts` table to the Better Auth `accounts` table.
<Callout type={'error'}>
**Important Notice**:
- **Always backup your database first!** For Neon users, create a backup via [Fork Branch](https://neon.tech/docs/manage/branches#create-a-branch)
- Migration scripts must be **run locally after cloning the repository**, not in the deployment environment
- Due to the high-risk nature of user data migration, **we do not provide automatic migration during deployment**
- Always use dry-run mode first to verify the script runs successfully before executing
- Always verify in a test environment before operating on production database
- Change `NEXTAUTH_TO_BETTERAUTH_DRY_RUN` back to `1`
2. Run the script:
```bash
# Run migration (dry-run mode to verify)
npx tsx scripts/nextauth-to-betterauth/index.ts
```
Review the output logs, confirm no issues, then proceed to the next step.
### Step 5: Execute Migration and Verify (Production Environment)
Update `.env` to set `NEXTAUTH_TO_BETTERAUTH_DRY_RUN` to `0`, then execute:
```bash
# Execute migration
npx tsx scripts/nextauth-to-betterauth/index.ts
# Verify the migration
npx tsx scripts/nextauth-to-betterauth/verify.ts
```
### Step 6: Configure Better Auth and Redeploy
After migration is complete, follow [Simple Migration - Step 1](#steps) to configure Better Auth environment variables and redeploy.
<Callout type={'tip'}>
For complete Better Auth configuration, see [Authentication Service Configuration](/docs/self-hosting/advanced/auth), including all supported SSO providers and email service configuration.
**Important**: Better Auth currently **requires user email** for authentication. All SSO providers must be configured to return email information, otherwise users cannot log in.
</Callout>
Common causes:
**Cause 1: SSO connection not requesting email permission**
When configuring SSO connections (e.g., GitHub in Auth0), make sure to enable **Email Address** permission in the Attributes section. LobeHub requires user email for authentication.
**Note for Casdoor Users**: Casdoor does not require users to have an email configured, but LobeHub strongly depends on email for authentication. If you find migration difficult due to many users without email addresses, we recommend staying on [v2.0.0-next.344](https://github.com/lobehub/lobe-chat/releases/tag/v2.0.0-next.344) for now. We plan to provide a self-service migration feature in the future, where users without email will be redirected to a bind-email page when they log in.
