New Authentication Provider Guide
LobeHub uses Better Auth as the external authentication service. Better Auth is an open-source authentication library that provides a simple way to implement authentication and authorization features. This document will introduce how to use Better Auth to implement a new authentication provider.
Architecture Overview
To add a new authentication provider in LobeHub (for example, adding GitLab), you need to follow the steps below:
| Type | Description | Examples |
|---|---|---|
builtin | Providers natively supported by Better Auth | Google, GitHub, Microsoft, Apple |
generic | Implemented via Generic OIDC/OAuth plugin | Auth0, Keycloak, Okta, etc. |
Adding a New SSO Provider
Using GitLab as an example (not yet implemented in the codebase), here's how to add a generic type provider.
Step 1: Create Provider Definition File
Create gitlab.ts in src/libs/better-auth/sso/providers/:
Step 2: Register the Provider
Import and register in src/libs/better-auth/sso/index.ts:
Step 3: Add Environment Variable Types
Add type declarations in packages/env/src/auth.ts:
Step 4: Update Documentation (Optional)
Add provider documentation in docs/self-hosting/auth.mdx and docs/self-hosting/auth.zh-CN.mdx.
Adding a Built-in Provider
For providers natively supported by Better Auth (e.g., Discord), the steps differ slightly:
Step 1: Create Provider Definition File
Step 2: Update Constants File
Add to src/libs/better-auth/constants.ts:
Callback URL Format
When configuring OAuth applications, use these callback URL formats:
- Built-in providers:
https://yourdomain.com/api/auth/callback/{providerId} - Generic OIDC:
https://yourdomain.com/api/auth/callback/{providerId}
Using the New Provider
After configuring environment variables, enable in AUTH_SSO_PROVIDERS:
Now, you can use GitLab as your provider to implement the authentication feature in LobeHub.