DiscourseConnect (SSO)¶

Discourse is the identity provider. SAE Books is the consumer (relying party). When a user clicks "Log in with Discourse" on the SAE Books login page, their browser is sent to Discourse's /session/sso_provider endpoint, where Discourse authenticates them and signs a response redirecting them back to SAE Books.

How the flow works¶

Endpoints (saebooks-web)¶

GET https://app.saebooks.com.au/auth/discourse/login

Initiates the flow. Generates a nonce, stores it in an HMAC-signed cookie (sae_discourse_nonce, TTL 10 minutes), and redirects the browser to Discourse's sso_provider endpoint.

GET https://app.saebooks.com.au/auth/discourse/callback?sso=<payload>&sig=<hmac>

Handles the Discourse callback. Both are handled by saebooks_web/discourse_sso.py. Neither is an API endpoint — both are browser redirect handlers.

Payload — inbound (Discourse → SAE Books callback)¶

Discourse builds and signs this payload before redirecting the user back.

The raw payload is nonce=…&external_id=…&email=…&…, base64-encoded and HMAC-SHA256 signed with the shared secret.

Payload — outbound (SAE Books → Discourse login request)¶

SAE Books builds and signs this payload before redirecting the user to Discourse.

Shared secret¶

Both sides hold the same HMAC-SHA256 secret. On Discourse it is the discourse_connect_secret site setting. On SAE Books it is the DISCOURSE_SSO_SECRET environment variable (set on saebooks-web).

Rotate the secret by updating both sides simultaneously and restarting saebooks-web. Any in-flight login attempt during rotation will fail cleanly (the user gets an error page and can retry).

Session handoff to saebooks-api¶

After verifying the Discourse payload, saebooks-web does not create a session directly. Instead it calls the internal oauth-handoff endpoint:

POST /api/v1/auth/oauth-handoff
X-OAuth-Handoff-Secret: <SAEBOOKS_OAUTH_HANDOFF_SECRET>

{
  "provider": "discourse",
  "provider_user_id": "<discourse external_id>",
  "email": "<user email>",
  "display_name": "<name or username>"
}

On success the API returns {"access_token": "<bearer>"}. The web layer stores this in the session cookie (session["api_token"]) and fetches /api/v1/auth/me to populate session["username"] and session["user_role"].

Both DISCOURSE_SSO_SECRET and SAEBOOKS_OAUTH_HANDOFF_SECRET must be set on saebooks-web. Missing either disables the flow or causes a 500 error with a clear message logged.

Discourse settings¶

These site settings are set via the Discourse admin panel and held in the database (not in the compose env vars):

openid_connect_enabled must be false — it and DiscourseConnect are mutually exclusive. Setting the DISCOURSE_OPENID_CONNECT_* env vars in the Discourse compose file forces OIDC on at startup and overrides the database setting; those env vars must be absent.

Environment variables (saebooks-web)¶

Discourse login is disabled (button hidden) when DISCOURSE_SSO_SECRET is unset or empty.

SAE staff flag¶

After a successful Discourse login, the session's is_sae_staff flag is set based on the SAE_STAFF_USERNAMES env var (comma-separated list of usernames or emails). This gate controls access to internal tooling routes (e.g. /admin/inspect, agent routes) and is distinct from the user's role field on the account.

Testing locally¶

Set DISCOURSE_SSO_SECRET to any 32+ char value and exercise the callback endpoint directly by building a test payload:

import base64, hashlib, hmac, urllib.parse, time, secrets

secret = b"your-test-secret"
nonce = secrets.token_urlsafe(16)
# Build the payload Discourse would return
payload = urllib.parse.urlencode({
    "nonce": nonce,
    "external_id": "42",
    "email": "[email protected]",
    "username": "testuser",
    "name": "Test User",
})
b64 = base64.b64encode(payload.encode()).decode()
sig = hmac.new(secret, b64.encode(), hashlib.sha256).hexdigest()
print(f"http://localhost:8043/auth/discourse/callback?sso={urllib.parse.quote(b64)}&sig={sig}")

Navigate to the printed URL (you will need a valid nonce cookie, which the /auth/discourse/login endpoint sets — run that first, then substitute the nonce from the cookie into the payload above).