mirror of
https://github.com/lobehub/lobehub
synced 2026-04-21 09:37:28 +00:00
93 lines
3.6 KiB
Text
93 lines
3.6 KiB
Text
---
|
|
title: Configuring GitHub Authentication for LobeHub
|
|
description: >-
|
|
Learn how to configure GitHub SSO for LobeHub, including creating a GitHub
|
|
App, setting up environment variables, and deployment.
|
|
tags:
|
|
- GitHub
|
|
- Authentication
|
|
- LobeHub
|
|
- Single Sign-On
|
|
---
|
|
|
|
# Configuring GitHub Authentication
|
|
|
|
<Steps>
|
|
### Create a GitHub App
|
|
|
|
1. Go to [GitHub Developer Settings](https://github.com/settings/apps/new)
|
|
2. Fill in the **GitHub App name** and **Homepage URL**
|
|
|
|
<Image alt="Create a GitHub App" inStep src="https://github.com/lobehub/lobehub/assets/64475363/2f919f99-2aaa-4fa7-9938-169d3ed09db7" />
|
|
|
|
### Configure Callback URL
|
|
|
|
<Callout type={'info'}>
|
|
Callback URL format:
|
|
|
|
- Local development: `http://localhost:3210/api/auth/callback/github`
|
|
- Production: `https://your-domain.com/api/auth/callback/github`
|
|
</Callout>
|
|
|
|
Set the Webhook URL according to your needs (can be disabled if not used).
|
|
|
|
<Image alt="Fill in other fields" inStep src="https://github.com/lobehub/lobehub/assets/64475363/d7ef5ad1-b1a3-435e-b1bc-4436d2b6fecd" />
|
|
|
|
### Configure Permissions
|
|
|
|
Set permission to read user email addresses:
|
|
|
|
<Image alt="Set required permissions" inStep src="https://github.com/lobehub/lobehub/assets/64475363/23131ca1-9e84-4a89-a840-ef79c4bc0251" />
|
|
|
|
<Image alt="Set permission to read email addresses" inStep src="https://github.com/lobehub/lobehub/assets/64475363/358bca8d-3d82-4e76-9a5e-90d16a39efde" />
|
|
|
|
Set whether the app is publicly accessible or only accessible to yourself.
|
|
|
|
<Image alt="Set accessibility" inStep src="https://github.com/lobehub/lobehub/assets/64475363/995780cb-9096-4a36-ab17-d422703ab970" />
|
|
|
|
Click **Create GitHub App**.
|
|
|
|
### Generate Client Secret
|
|
|
|
After creation, click **Generate a new client secret**.
|
|
|
|
<Image alt="Create a new client secret" inStep src="https://github.com/lobehub/lobehub/assets/64475363/6d69bdca-7d18-4cbc-b3e0-220d8815cd29" />
|
|
|
|
Save the **Client ID** and **Client Secret**.
|
|
|
|
<Image alt="Save credentials" inStep src="https://github.com/lobehub/lobehub/assets/64475363/c6108133-a918-48b0-ab1a-e3fa607572a4" />
|
|
|
|
### Configure Environment Variables
|
|
|
|
| Environment Variable | Type | Description |
|
|
| -------------------- | -------- | --------------------------------------------------------------- |
|
|
| `AUTH_SECRET` | Required | Session encryption key, generate with `openssl rand -base64 32` |
|
|
| `AUTH_SSO_PROVIDERS` | Required | Set to `github` |
|
|
| `AUTH_GITHUB_ID` | Required | Client ID from the GitHub App |
|
|
| `AUTH_GITHUB_SECRET` | Required | Client Secret from the GitHub App |
|
|
|
|
<Callout type={'tip'}>
|
|
Go to [📘 Environment Variables](/docs/self-hosting/environment-variables/auth#github)
|
|
for detailed information.
|
|
</Callout>
|
|
</Steps>
|
|
|
|
<Callout type={'info'}>
|
|
After successful deployment, users will be able to authenticate with GitHub
|
|
and use LobeHub.
|
|
</Callout>
|
|
|
|
## Common Issues
|
|
|
|
### email\_not\_found Error
|
|
|
|
This usually happens when the GitHub App doesn't have email read permission. Go to your app settings, navigate to **Permissions & events** > **Account permissions** > **Email addresses** and set it to **Read-only**.
|
|
|
|
### No Refresh Token
|
|
|
|
GitHub OAuth does not issue refresh tokens. Access tokens remain valid until the user revokes access, the app revokes access, or the token hasn't been used for one year.
|
|
|
|
## Related Resources
|
|
|
|
- [GitHub Developer Settings](https://github.com/settings/developers)
|
|
- [GitHub Apps Documentation](https://docs.github.com/en/apps)
|