Add README
This commit is contained in:
root
parent
a8442250e0
commit
c22c1537ff
1 changed files with 180 additions and 0 deletions
180
README.md
Normal file
180
README.md
Normal file
|
|
@ -0,0 +1,180 @@
|
||||||
|
# discourse-oauth2-bridge
|
||||||
|
|
||||||
|
A lightweight Node.js bridge that allows [Authentik](https://goauthentik.io/) (and other OIDC-compatible identity providers) to use [Discourse](https://discourse.org/) as its authentication backend via [DiscourseConnect](https://meta.discourse.org/t/discourseconnect-official-sso-solution-for-discourse/13045).
|
||||||
|
|
||||||
|
## The problem it solves
|
||||||
|
|
||||||
|
Discourse has a built-in SSO provider called DiscourseConnect, which lets other apps authenticate against it. However, most modern apps (Nextcloud, Outline, Invoice Ninja, etc.) expect **OIDC or OAuth2**, not DiscourseConnect. This bridge sits between Authentik and Discourse, translating DiscourseConnect into a standard OAuth2/OIDC interface that Authentik can consume.
|
||||||
|
|
||||||
|
```
|
||||||
|
App (e.g. Nextcloud, Outline)
|
||||||
|
│
|
||||||
|
│ OIDC
|
||||||
|
▼
|
||||||
|
Authentik
|
||||||
|
│
|
||||||
|
│ OAuth2 (via this bridge)
|
||||||
|
▼
|
||||||
|
discourse-oauth2-bridge ←── this repo
|
||||||
|
│
|
||||||
|
│ DiscourseConnect
|
||||||
|
▼
|
||||||
|
Discourse ←── source of truth: users, groups, permissions
|
||||||
|
```
|
||||||
|
|
||||||
|
User accounts, group memberships and permissions are all managed in Discourse. Any app connected via Authentik inherits them automatically.
|
||||||
|
|
||||||
|
## How it works
|
||||||
|
|
||||||
|
The bridge implements a minimal OAuth2 authorization code flow:
|
||||||
|
|
||||||
|
1. **`/authorize`** — receives an OAuth2 authorization request from Authentik, generates a DiscourseConnect SSO request, and redirects the user to Discourse to log in
|
||||||
|
2. **`/callback`** — Discourse redirects back here after login; the bridge validates the signature, extracts user info (username, email, groups, admin status), and issues a short-lived authorization code
|
||||||
|
3. **`/token`** — exchanges the authorization code for an access token
|
||||||
|
4. **`/userinfo`** — returns the authenticated user's profile to Authentik in OIDC-compatible format
|
||||||
|
5. **`/.well-known/openid-configuration`** — OIDC discovery endpoint so Authentik can auto-configure itself
|
||||||
|
6. **`/health`** — health check endpoint used by Docker
|
||||||
|
|
||||||
|
Tokens and auth codes are stored in memory and expire after 10 minutes. The bridge is stateless beyond that — no database required.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- A running Discourse instance with **DiscourseConnect provider** enabled (`/admin/site_settings` → search `sso provider`)
|
||||||
|
- A running [Authentik](https://goauthentik.io/) instance
|
||||||
|
- Docker (recommended) or Node.js 20+
|
||||||
|
|
||||||
|
## Setup
|
||||||
|
|
||||||
|
### 1. Configure Discourse
|
||||||
|
|
||||||
|
In your Discourse admin settings:
|
||||||
|
|
||||||
|
- Enable `enable sso provider`
|
||||||
|
- Set `sso secret` — this becomes your `DISCOURSE_SECRET`
|
||||||
|
- Enable `verbose sso logging` while testing (optional but helpful)
|
||||||
|
|
||||||
|
### 2. Configure the bridge
|
||||||
|
|
||||||
|
Copy `.env.example` to `.env` and fill in your values:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
nano .env
|
||||||
|
```
|
||||||
|
|
||||||
|
```env
|
||||||
|
# Port the bridge listens on inside Docker
|
||||||
|
PORT=3000
|
||||||
|
|
||||||
|
# Your Discourse instance
|
||||||
|
DISCOURSE_URL=https://discourse.example.com
|
||||||
|
DISCOURSE_SECRET=CHANGE_ME
|
||||||
|
|
||||||
|
# The URL this bridge is accessible at (used in redirects)
|
||||||
|
BRIDGE_URL=https://auth-bridge.example.com
|
||||||
|
|
||||||
|
# OAuth2 credentials — you will set these in Authentik (step 3)
|
||||||
|
OAUTH2_CLIENT_ID=CHANGE_ME
|
||||||
|
OAUTH2_CLIENT_SECRET=CHANGE_ME
|
||||||
|
```
|
||||||
|
|
||||||
|
Generate a strong secret for `OAUTH2_CLIENT_SECRET`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
openssl rand -hex 32
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Configure Authentik
|
||||||
|
|
||||||
|
In Authentik, create a new **Generic OAuth2 / OIDC provider**:
|
||||||
|
|
||||||
|
| Setting | Value |
|
||||||
|
|---|---|
|
||||||
|
| Authorization URL | `https://auth-bridge.example.com/authorize` |
|
||||||
|
| Token URL | `https://auth-bridge.example.com/token` |
|
||||||
|
| Userinfo URL | `https://auth-bridge.example.com/userinfo` |
|
||||||
|
| Client ID | your chosen `OAUTH2_CLIENT_ID` |
|
||||||
|
| Client Secret | your chosen `OAUTH2_CLIENT_SECRET` |
|
||||||
|
|
||||||
|
Or use the OIDC discovery URL and let Authentik configure itself:
|
||||||
|
|
||||||
|
```
|
||||||
|
https://auth-bridge.example.com/.well-known/openid-configuration
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Run with Docker
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker build -t discourse-oauth2-bridge .
|
||||||
|
docker run -d \
|
||||||
|
--name discourse-oauth2-bridge \
|
||||||
|
--env-file .env \
|
||||||
|
-p 3000:3000 \
|
||||||
|
discourse-oauth2-bridge
|
||||||
|
```
|
||||||
|
|
||||||
|
Or with Docker Compose — see the example below.
|
||||||
|
|
||||||
|
### 5. Verify
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl https://auth-bridge.example.com/health
|
||||||
|
# → {"status":"ok"}
|
||||||
|
|
||||||
|
curl https://auth-bridge.example.com/.well-known/openid-configuration
|
||||||
|
# → OIDC discovery document
|
||||||
|
```
|
||||||
|
|
||||||
|
## Docker Compose example
|
||||||
|
|
||||||
|
This is the configuration used on [tobiaseigen.org](https://tobiaseigen.org), where the bridge runs alongside Authentik on a mailcow server, sharing the mailcow Docker network:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
discourse-bridge:
|
||||||
|
build: .
|
||||||
|
container_name: authentik-discourse-bridge-1
|
||||||
|
restart: unless-stopped
|
||||||
|
env_file: .env
|
||||||
|
networks:
|
||||||
|
mailcow-network:
|
||||||
|
ipv4_address: 172.22.1.247 # adjust to a free IP on your network
|
||||||
|
|
||||||
|
networks:
|
||||||
|
mailcow-network:
|
||||||
|
external: true
|
||||||
|
name: mailcowdockerized_mailcow-network
|
||||||
|
```
|
||||||
|
|
||||||
|
## User info claims
|
||||||
|
|
||||||
|
The `/userinfo` endpoint returns the following claims:
|
||||||
|
|
||||||
|
| Claim | Source |
|
||||||
|
|---|---|
|
||||||
|
| `sub` | Discourse `external_id` |
|
||||||
|
| `preferred_username` | Discourse username |
|
||||||
|
| `name` | Discourse full name |
|
||||||
|
| `email` | Discourse email |
|
||||||
|
| `picture` | Discourse avatar URL |
|
||||||
|
| `groups` | Discourse group memberships (comma-separated list) |
|
||||||
|
| `discourse_admin` | `true` if Discourse admin |
|
||||||
|
| `discourse_moderator` | `true` if Discourse moderator |
|
||||||
|
|
||||||
|
Authentik can use `groups` claims to map Discourse group membership to Authentik groups, which downstream apps can then use for access control.
|
||||||
|
|
||||||
|
## Security notes
|
||||||
|
|
||||||
|
- Auth codes, access tokens and pending auth state are stored **in memory only** — they do not survive a container restart
|
||||||
|
- All tokens expire after **10 minutes**
|
||||||
|
- The bridge validates Discourse's HMAC-SHA256 signature on every callback before trusting any user data
|
||||||
|
- The container runs as a non-root user (`bridge`)
|
||||||
|
- Keep your `.env` file private — it contains secrets. It is excluded from this repo via `.gitignore`
|
||||||
|
|
||||||
|
## Background
|
||||||
|
|
||||||
|
This bridge was developed for the [Digitally Sovereign](https://discourse.tobiaseigen.org) self-hosting project, where Discourse is used as the single source of truth for user identity and access control across a suite of self-hosted tools. See the forum for background and discussion.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
Loading…
Reference in a new issue