185 lines
6.6 KiB
Markdown
185 lines
6.6 KiB
Markdown
# Gitea OAuth2 Authentication — Design Spec
|
|
|
|
Date: 2026-05-08
|
|
|
|
## Overview
|
|
|
|
Add Gitea as an OAuth2 login provider alongside the existing username/password
|
|
authentication. Any user on the configured Gitea instance can sign in; their
|
|
local account is auto-provisioned on first login as a regular (non-admin) user.
|
|
Password login continues to work unchanged.
|
|
|
|
---
|
|
|
|
## Config
|
|
|
|
A new optional `oauth.gitea` block in `~/.hb.yaml`. OAuth is disabled when the
|
|
block is absent or any of the three required keys is missing.
|
|
|
|
```yaml
|
|
oauth:
|
|
gitea:
|
|
url: https://git.example.com # Gitea base URL, no trailing slash
|
|
client_id: <gitea-app-client-id>
|
|
client_secret: <gitea-app-client-secret>
|
|
```
|
|
|
|
**Gitea setup:** Create an OAuth2 application in Gitea under
|
|
*Settings → Applications → OAuth2*. Set the redirect URI to
|
|
`https://<hbd-host>/login/oauth/gitea/callback`.
|
|
|
|
`config.py` default:
|
|
|
|
```python
|
|
"oauth": {},
|
|
```
|
|
|
|
---
|
|
|
|
## New module: `hbd/server/oauth.py`
|
|
|
|
Owns all OAuth2 logic. No new dependencies — uses `aiohttp.ClientSession`
|
|
already present in the codebase.
|
|
|
|
### CSRF state store
|
|
|
|
```python
|
|
# state -> expires (float)
|
|
_states: dict[str, float] = {}
|
|
STATE_TTL = 600 # 10 minutes
|
|
```
|
|
|
|
`_states` is an in-memory dict. Entries are created on redirect and deleted on
|
|
use or expiry. A purge runs on every new state generation.
|
|
|
|
### Public API
|
|
|
|
| Function | Description |
|
|
|---|---|
|
|
| `is_enabled(config)` | Returns `True` when url, client_id, and client_secret are all set |
|
|
| `make_state()` | Generates a random state token, stores it with TTL, returns it |
|
|
| `validate_state(state)` | Returns `True` and removes the state if valid and unexpired |
|
|
| `authorization_url(config, state, redirect_uri)` | Builds the Gitea `/login/oauth/authorize` redirect URL with `client_id`, `redirect_uri`, `scope=user:email`, `state` |
|
|
| `exchange_code(config, code, redirect_uri)` async | POSTs to Gitea `/login/oauth/access_token` with code and redirect_uri, returns the access token string or raises `OAuthError` |
|
|
| `fetch_user(config, token)` async | GETs Gitea `/api/v1/user` with Bearer token, returns `{"login", "full_name", "avatar_url"}` or raises `OAuthError` |
|
|
|
|
### Error handling
|
|
|
|
`OAuthError(message)` is a module-level exception. The callback route catches it
|
|
and renders the login page with an error message — identical to an invalid
|
|
password error in UX terms.
|
|
|
|
Network timeouts use a 10-second `aiohttp` timeout. Any non-2xx response from
|
|
Gitea raises `OAuthError`.
|
|
|
|
---
|
|
|
|
## Change: `hbd/server/users.py`
|
|
|
|
One new function added to the public API:
|
|
|
|
```python
|
|
def provision_oauth_user(username: str, full_name: str, avatar: str) -> User:
|
|
```
|
|
|
|
- If the username does not exist in the live `users` dict, creates a `User`
|
|
with no `password_hash` (so password login is impossible for this account)
|
|
and inserts it.
|
|
- If the username already exists (e.g. was defined in config with a password),
|
|
updates `full_name` and `avatar` from the OAuth profile and returns the
|
|
existing user unchanged in all other respects (preserving admin flag,
|
|
notification channels, etc.).
|
|
- Logs a one-line INFO message on first provision.
|
|
|
|
---
|
|
|
|
## Changes: `hbd/server/http.py`
|
|
|
|
### Two new route handlers
|
|
|
|
**`GET /login/oauth/gitea`**
|
|
|
|
1. Checks `oauth.is_enabled(config)` — returns 404 if not.
|
|
2. Calls `oauth.make_state()`.
|
|
3. Constructs `redirect_uri` as `{request.url.origin()}/login/oauth/gitea/callback` using aiohttp's `request.url.origin()`.
|
|
4. Redirects the browser to `oauth.authorization_url(config, state, redirect_uri)`.
|
|
|
|
**`GET /login/oauth/gitea/callback`**
|
|
|
|
1. Reads `code` and `state` query params; returns 400 if either is missing.
|
|
2. Calls `oauth.validate_state(state)` — redirects to `/login` with error if
|
|
invalid (CSRF or replay protection).
|
|
3. Reconstructs the same `redirect_uri` as the redirect handler (required by OAuth2 spec for token exchange).
|
|
4. Calls `await oauth.exchange_code(config, code, redirect_uri)` to get the access token.
|
|
4. Calls `await oauth.fetch_user(config, token)` to get the Gitea user profile.
|
|
5. Calls `users_mod.provision_oauth_user(login, full_name, avatar_url)`.
|
|
6. Calls `users_mod.create_session(username)` to get a session token.
|
|
7. Sets `hbd_session` cookie (same flags as password login: httponly, Lax,
|
|
24h TTL).
|
|
8. Redirects to `/`.
|
|
9. Any `OAuthError` re-renders the login page with a generic error message.
|
|
|
|
### Login page change
|
|
|
|
When `oauth.is_enabled(config)` is `True`, the existing login form gains a
|
|
separator and a "Sign in with Gitea" link button pointing to
|
|
`/login/oauth/gitea`. The password form is always rendered regardless.
|
|
|
|
### Route registration
|
|
|
|
```python
|
|
web.get("/login/oauth/gitea", oauth_redirect),
|
|
web.get("/login/oauth/gitea/callback", oauth_callback),
|
|
```
|
|
|
|
Added alongside the existing `/login` and `/logout` routes.
|
|
|
|
---
|
|
|
|
## Data flow
|
|
|
|
```
|
|
Browser hbd Gitea
|
|
| | |
|
|
|-- GET /login ----------->| |
|
|
|<- login page (+ button) -| |
|
|
| | |
|
|
|-- GET /login/oauth/gitea>| |
|
|
|<- 302 Gitea /authorize --| |
|
|
| | |
|
|
|-- GET /login/oauth/authorize ----------------------->|
|
|
|<- 302 /login/oauth/gitea/callback?code=..&state=.. --|
|
|
| | |
|
|
|-- GET /callback -------->| |
|
|
| |-- POST /access_token ---->|
|
|
| |<- {access_token} ---------|
|
|
| |-- GET /api/v1/user ------>|
|
|
| |<- {login, name, avatar} --|
|
|
| | provision_oauth_user() |
|
|
| | create_session() |
|
|
|<- 302 / (set cookie) ----| |
|
|
```
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
- `test_oauth_state`: `make_state` + `validate_state` happy path; expired state
|
|
returns False; replay (double-use) returns False.
|
|
- `test_provision_oauth_user_new`: new username creates User with no password.
|
|
- `test_provision_oauth_user_existing`: existing config user updates name/avatar,
|
|
preserves admin flag and notification_channels.
|
|
- `test_oauth_callback_invalid_state`: callback with bad state redirects to login.
|
|
- Integration: mock Gitea endpoints with `aiohttp_client` fixture; full
|
|
redirect → callback → session cookie flow.
|
|
|
|
---
|
|
|
|
## Out of scope
|
|
|
|
- Restricting login to specific Gitea organisations or teams.
|
|
- Making OAuth users admin automatically.
|
|
- Multiple OAuth providers.
|
|
- Token refresh (Gitea access tokens are long-lived; the hbd session TTL governs
|
|
re-authentication).
|