ContextQMD
Back to Lobehub

Configuring GitHub Authentication for LobeHub

docs/self-hosting/auth/providers/github.mdx

2.1.563.4 KB
Original Source

Configuring GitHub Authentication

<Steps> ### Create a GitHub App
  1. Go to GitHub Developer Settings
  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 VariableTypeDescription
AUTH_SECRETRequiredSession encryption key, generate with openssl rand -base64 32
AUTH_SSO_PROVIDERSRequiredSet to github
AUTH_GITHUB_IDRequiredClient ID from the GitHub App
AUTH_GITHUB_SECRETRequiredClient Secret from the GitHub App

<Callout type={'tip'}> Go to 📘 Environment Variables 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.