Skip to content

Commit 07c061d

Browse files
mythzmythz
committed
Create README.md
1 parent 4402700 commit 07c061d

File tree

1 file changed

+169
-0
lines changed

1 file changed

+169
-0
lines changed

‎llms/extensions/github_auth/README.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# GitHub Auth Extension
2+
3+
The GitHub Auth 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.
4+
5+
## Features
6+
7+
- **GitHub OAuth 2.0** - Standard OAuth flow with CSRF protection
8+
- **User Restrictions** - Optionally restrict access to specific GitHub users
9+
- **Session Management** - Automatic session handling with 24-hour expiry
10+
- **Environment Variables** - Credentials can use env vars for secure deployment
11+
12+
## Configuration
13+
14+
Create a config file at `~/.llms/users/default/github_auth/config.json`:
15+
16+
```json
17+
{
18+
"enabled": true,
19+
"client_id": "$GITHUB_CLIENT_ID",
20+
"client_secret": "$GITHUB_CLIENT_SECRET",
21+
"redirect_uri": "http://localhost:8000/auth/github/callback",
22+
"restrict_to": "$GITHUB_USERS"
23+
}
24+
```
25+
26+
| Property | Description |
27+
|-----------------|-------------|
28+
| `client_id` | GitHub OAuth App client ID |
29+
| `client_secret` | GitHub OAuth App client secret |
30+
| `redirect_uri` | Callback URL registered with GitHub |
31+
| `restrict_to` | Optional comma/space-delimited list of allowed GitHub usernames |
32+
| `enabled` | Set to `false` to disable the extension |
33+
34+
Values prefixed with `$` are resolved from environment variables.
35+
36+
## Creating a GitHub OAuth App
37+
38+
1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
39+
2. Click **New OAuth App**
40+
3. Fill in the application details:
41+
- **Application name**: Your app name
42+
- **Homepage URL**: Your app's homepage (e.g., `http://localhost:8000`)
43+
- **Authorization callback URL**: Must match your `redirect_uri` (e.g., `http://localhost:8000/auth/github/callback`)
44+
4. Click **Register application**
45+
5. Copy the **Client ID** and generate a **Client Secret**
46+
47+
## API Endpoints
48+
49+
The extension registers these routes:
50+
51+
| Method | Endpoint | Description |
52+
|--------|-------------------------|-------------|
53+
| GET | `/auth` | Check authentication status |
54+
| GET | `/auth/github` | Initiate GitHub OAuth flow |
55+
| GET | `/auth/github/callback` | OAuth callback handler |
56+
| GET | `/auth/session` | Get current session info |
57+
| POST | `/auth/logout` | End the current session |
58+
59+
### GET /auth
60+
61+
Returns the authenticated user's info or a 401 error:
62+
63+
```json
64+
{
65+
"userId": "12345",
66+
"userName": "octocat",
67+
"displayName": "The Octocat",
68+
"profileUrl": "https://avatars.githubusercontent.com/u/12345",
69+
"authProvider": "github"
70+
}
71+
```
72+
73+
### GET /auth/session
74+
75+
Returns full session details including the session token:
76+
77+
```json
78+
{
79+
"userId": "12345",
80+
"userName": "octocat",
81+
"displayName": "The Octocat",
82+
"profileUrl": "https://avatars.githubusercontent.com/u/12345",
83+
"email": "octocat@github.com",
84+
"created": 1706600000.123,
85+
"sessionToken": "..."
86+
}
87+
```
88+
89+
## OAuth Flow
90+
91+
```
92+
┌─────────┐ ┌─────────┐ ┌────────┐
93+
│ Browser │ │ llms │ │ GitHub │
94+
└────┬────┘ └────┬────┘ └───┬────┘
95+
│ │ │
96+
│ GET /auth/github │ │
97+
├───────────────────►│ │
98+
│ │ │
99+
│ 302 Redirect │ │
100+
│◄───────────────────┤ │
101+
│ │ │
102+
│ /login/oauth/authorize?... │
103+
├────────────────────────────────────────►
104+
│ │ │
105+
│ User grants access │
106+
│◄────────────────────────────────────────
107+
│ │ │
108+
│ GET /auth/github/callback?code=... │
109+
├───────────────────►│ │
110+
│ │ │
111+
│ │ POST /access_token │
112+
│ ├──────────────────►│
113+
│ │ │
114+
│ │ access_token │
115+
│ │◄──────────────────┤
116+
│ │ │
117+
│ │ GET /user │
118+
│ ├──────────────────►│
119+
│ │ │
120+
│ │ user info │
121+
│ │◄──────────────────┤
122+
│ │ │
123+
│ 302 /?session=... │ │
124+
│ Set-Cookie: token │ │
125+
│◄───────────────────┤ │
126+
│ │ │
127+
```
128+
129+
1. User clicks "Sign in with GitHub" → redirects to `/auth/github`
130+
2. Server generates CSRF state token and redirects to GitHub
131+
3. User authorizes the app on GitHub
132+
4. GitHub redirects back with authorization code
133+
5. Server exchanges code for access token
134+
6. Server fetches user info from GitHub API
135+
7. Server creates session and sets cookie
136+
137+
## Restricting Access
138+
139+
To limit access to specific GitHub users, set `restrict_to` in your config:
140+
141+
```json
142+
{
143+
"client_id": "...",
144+
"client_secret": "...",
145+
"redirect_uri": "...",
146+
"restrict_to": "alice bob charlie"
147+
}
148+
```
149+
150+
Users not in this list receive a `403 Forbidden` response.
151+
152+
## UI Component
153+
154+
The 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.
155+
156+
## Session Storage
157+
158+
Sessions are stored in memory with:
159+
- **Token**: Cryptographically secure random string
160+
- **User data**: GitHub user ID, username, display name, avatar URL, email
161+
- **Expiry**: Automatic cleanup after 24 hours
162+
- **Cookie**: `llms-token` with `httponly` flag for security
163+
164+
## Security Notes
165+
166+
- **CSRF Protection**: OAuth state tokens prevent cross-site request forgery
167+
- **State Cleanup**: Expired state tokens (>10 min) are automatically removed
168+
- **Session Cleanup**: Sessions older than 24 hours are pruned
169+
- **HttpOnly Cookie**: Session token is not accessible via JavaScript

0 commit comments

Comments
 (0)