Skip to content

Commit aeeaa98

Browse files
mythzmythz
committed
update github auth docs
1 parent 144e3a1 commit aeeaa98

File tree

1 file changed

+118
-93
lines changed

1 file changed

+118
-93
lines changed

‎content/docs/deployment/github-oauth.mdx‎

Lines changed: 118 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,12 @@
22
title: GitHub OAuth Setup
33
description: Secure your llms.py deployment with GitHub OAuth authentication
44
---
5-
## Features
65

7-
Secure your llms.py deployment with GitHub OAuth authentication and optional user access restrictions.
6+
## Overview
7+
8+
The [github_auth](https://github.com/ServiceStack/llms/tree/main/llms/extensions/github_auth) built-in extension enables OAuth 2.0 authentication via GitHub for your llms application. When enabled, users must sign in with their GitHub account before accessing the application.
9+
10+
### Key Features
811

912
- ✅ GitHub OAuth 2.0 integration
1013
- ✅ Secure session management
@@ -14,19 +17,40 @@ Secure your llms.py deployment with GitHub OAuth authentication and optional use
1417
- ✅ Optional user access restrictions
1518
- ✅ Environment variable support
1619

17-
## Setup Instructions
20+
## Configuration
21+
22+
Create a config file at `~/.llms/users/default/github_auth/config.json`:
23+
24+
```json
25+
{
26+
"enabled": true,
27+
"client_id": "GITHUB_CLIENT_ID",
28+
"client_secret": "GITHUB_CLIENT_SECRET",
29+
"redirect_uri": "http://localhost:8000/auth/github/callback",
30+
"restrict_to": "GITHUB_USERS"
31+
}
32+
```
33+
34+
| Property | Description |
35+
|-----------------|-------------|
36+
| `client_id` | GitHub OAuth App client ID |
37+
| `client_secret` | GitHub OAuth App client secret |
38+
| `redirect_uri` | Callback URL registered with GitHub |
39+
| `restrict_to` | Optional comma/space-delimited list of allowed GitHub usernames |
40+
| `enabled` | Set to `false` to disable the extension |
41+
42+
Values prefixed with `$` are resolved from environment variables.
1843

19-
### 1. Create a GitHub OAuth App
44+
## Creating a GitHub OAuth App
2045

21-
1. Go to [GitHub Settings → Developer settings → OAuth Apps](https://github.com/settings/developers)
22-
2. Click "New OAuth App"
46+
1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
47+
2. Click **New OAuth App**
2348
3. Fill in the application details:
24-
- **Application name**: `llms.py` (or your preferred name)
25-
- **Homepage URL**: `http://localhost:8000`
26-
- **Authorization callback URL**: `http://localhost:8000/auth/github/callback`
27-
4. Click "Register application"
28-
5. Note down your **Client ID**
29-
6. Click "Generate a new client secret" and note down the **Client Secret**
49+
- **Application name**: Your app name
50+
- **Homepage URL**: Your app's homepage (e.g., `http://localhost:8000`)
51+
- **Authorization callback URL**: Must match your `redirect_uri` (e.g., `http://localhost:8000/auth/github/callback`)
52+
4. Click **Register application**
53+
5. Copy the **Client ID** and generate a **Client Secret**
3054

3155
For production deployments, use your actual domain instead of localhost.
3256

@@ -44,29 +68,7 @@ export GITHUB_USERS="octocat mythz"
4468

4569
For permanent configuration, add these to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.).
4670

47-
### 3. Configure llms.json
48-
49-
Enable OAuth in your `~/.llms/llms.json`:
50-
51-
```json
52-
{
53-
"auth": {
54-
"enabled": true,
55-
"github": {
56-
"client_id": "$GITHUB_CLIENT_ID",
57-
"client_secret": "$GITHUB_CLIENT_SECRET",
58-
"redirect_uri": "http://localhost:8000/auth/github/callback",
59-
"restrict_to": "$GITHUB_USERS"
60-
}
61-
}
62-
}
63-
```
64-
65-
**Note**: The `$` prefix indicates environment variables that will be automatically expanded at runtime.
66-
67-
**Optional**: The `restrict_to` field can be omitted to allow any GitHub user to authenticate.
68-
69-
### 4. Start the Server
71+
### 3. Start the Server
7072

7173
```bash
7274
llms --serve 8000
@@ -104,81 +106,53 @@ If `restrict_to` is configured, only specified GitHub users can access the appli
104106

105107
```json
106108
{
107-
"auth": {
108-
"github": {
109-
"restrict_to": "octocat mythz demisbellot"
110-
}
111-
}
109+
"restrict_to": "octocat mythz demisbellot"
112110
}
113111
```
114112

115-
Users not in the list will see an "Access Denied" message after authenticating.
116-
117-
## Configuration
118-
119-
### Full Configuration Example
120-
121-
```json
122-
{
123-
"auth": {
124-
"enabled": true,
125-
"github": {
126-
"client_id": "$GITHUB_CLIENT_ID",
127-
"client_secret": "$GITHUB_CLIENT_SECRET",
128-
"redirect_uri": "http://localhost:8000/auth/github/callback",
129-
"restrict_to": "$GITHUB_USERS"
130-
}
131-
},
132-
"providers": {
133-
...
134-
}
135-
}
136-
```
113+
Users not in this list receive a `403 Forbidden` response.
137114

138115
### Disable Authentication
139116

140-
To disable authentication:
117+
You can [disable the GitHub OAuth extension](/docs/configuration#disable-extensions) by setting `enabled` to `false`:
141118

142119
```json
143120
{
144-
"auth": {
145-
"enabled": false,
146-
"github": { ... }
147-
}
121+
"enabled": true,
122+
...
148123
}
149124
```
150125

151-
Or remove the entire `auth` section.
126+
Or remove the entire `~/.llms/users/default/github_auth/config.json` file.
152127

153128
### Production Configuration
154129

155130
For production, update the `redirect_uri`:
156131

157132
```json
158133
{
159-
"auth": {
160-
"github": {
161-
"client_id": "$GITHUB_CLIENT_ID",
162-
"client_secret": "$GITHUB_CLIENT_SECRET",
163-
"redirect_uri": "https://yourdomain.com/auth/github/callback",
164-
"restrict_to": "$GITHUB_USERS"
165-
}
166-
}
134+
"client_id": "$GITHUB_CLIENT_ID",
135+
"client_secret": "$GITHUB_CLIENT_SECRET",
136+
"redirect_uri": "https://yourdomain.com/auth/github/callback",
137+
"restrict_to": "$GITHUB_USERS"
167138
}
168139
```
169140

170141
Also update the callback URL in your GitHub OAuth App settings.
171142

172143
## Architecture
173144

174-
### Server Endpoints
145+
## API Endpoints
175146

176-
New authentication endpoints:
147+
The extension registers these routes:
177148

178-
- `GET /auth/github` - Initiates GitHub OAuth flow
179-
- `GET /auth/github/callback` - Handles OAuth callback
180-
- `GET /auth/session` - Validates session token
181-
- `POST /auth/logout` - Ends user session
149+
| Method | Endpoint | Description |
150+
|--------|-------------------------|-------------|
151+
| GET | `/auth` | Check authentication status |
152+
| GET | `/auth/github` | Initiate GitHub OAuth flow |
153+
| GET | `/auth/github/callback` | OAuth callback handler |
154+
| GET | `/auth/session` | Get current session info |
155+
| POST | `/auth/logout` | End the current session |
182156

183157
### Session Management
184158

@@ -187,18 +161,54 @@ New authentication endpoints:
187161
- Sessions expire after 24 hours
188162
- CSRF protection using state tokens (expire after 10 minutes)
189163

190-
### Authentication Flow
191164

192-
1. User clicks "Sign in with GitHub"
193-
2. Redirected to `/auth/github`
194-
3. Server redirects to GitHub OAuth authorization
195-
4. User authorizes on GitHub
196-
5. GitHub redirects to `/auth/github/callback` with code
197-
6. Server exchanges code for access token
198-
7. Server fetches user info from GitHub API
199-
8. Server creates session and redirects to `/?session=TOKEN`
200-
9. Client validates session and stores user info
201-
10. User is authenticated
165+
## OAuth Flow
166+
167+
```
168+
┌─────────┐ ┌─────────┐ ┌────────┐
169+
│ Browser │ │ llms │ │ GitHub │
170+
└────┬────┘ └────┬────┘ └───┬────┘
171+
│ │ │
172+
│ GET /auth/github │ │
173+
├───────────────────►│ │
174+
│ │ │
175+
│ 302 Redirect │ │
176+
│◄───────────────────┤ │
177+
│ │ │
178+
│ /login/oauth/authorize?... │
179+
├────────────────────────────────────────►
180+
│ │ │
181+
│ User grants access │
182+
│◄────────────────────────────────────────
183+
│ │ │
184+
│ GET /auth/github/callback?code=... │
185+
├───────────────────►│ │
186+
│ │ │
187+
│ │ POST /access_token │
188+
│ ├──────────────────►│
189+
│ │ │
190+
│ │ access_token │
191+
│ │◄──────────────────┤
192+
│ │ │
193+
│ │ GET /user │
194+
│ ├──────────────────►│
195+
│ │ │
196+
│ │ user info │
197+
│ │◄──────────────────┤
198+
│ │ │
199+
│ 302 /?session=... │ │
200+
│ Set-Cookie: token │ │
201+
│◄───────────────────┤ │
202+
│ │ │
203+
```
204+
205+
1. User clicks "Sign in with GitHub" → redirects to `/auth/github`
206+
2. Server generates CSRF state token and redirects to GitHub
207+
3. User authorizes the app on GitHub
208+
4. GitHub redirects back with authorization code
209+
5. Server exchanges code for access token
210+
6. Server fetches user info from GitHub API
211+
7. Server creates session and sets cookie
202212

203213
### Session Data Structure
204214

@@ -214,6 +224,21 @@ New authentication endpoints:
214224
}
215225
```
216226

227+
## UI Component
228+
229+
The [github_auth](https://github.com/ServiceStack/llms/tree/main/llms/extensions/github_auth) extension provides a custom `SignIn` component that displays a "Sign in with GitHub" button. This component automatically overrides the default sign-in UI when the extension is loaded.
230+
231+
```js
232+
export default {
233+
install(ctx) {
234+
// Override SignIn component
235+
ctx.components({
236+
SignIn,
237+
})
238+
}
239+
}
240+
```
241+
217242
## Security
218243

219244
### CSRF Protection

0 commit comments

Comments
 (0)