DiscourseConnect SSO — Working Flask + Express Provider with HMAC Done Right

Discourse renamed "Discourse SSO" to DiscourseConnect in 2021, but every other blog post on the internet still calls it the old name — and the signing flow is delicate enough that a single base64 encoding mistake gives you the dreaded "Bad signature for payload" screen. This guide is a working reference: a Flask provider, an Express provider, an ASCII sequence diagram, and a field-by-field debug map for the four errors you will actually hit.

forum.example.com/session/sso_login

⚠ Bad signature for payload

Discourse received sso=bm9uY2U9YWJj... and computed HMAC-SHA256, but the sig did not match. Verify discourse_connect_secret matches your provider and that you signed the base64 string, not the decoded payload.

DiscourseConnect · Provider: auth.example.com · sig length: 64 hex chars

community.example.com

LatestCategoriesYou

✓ SSO login successful · external_id=42

Welcome back, [email protected]

Comment×

DiscourseConnect signature verification fails — fix the HMAC encoding|

Fix it ⟳ ✓ Done

SimpleReview PRO

waiting for selection…

Detected

ErrorBad signature

Filesso_provider.py

Fix plan

Sign base64(payload) not raw payload · use hmac.new(secret, b64, sha256)

Result

HMAC matches. /session/sso_login redirect succeeds.

✓ Fix ready

fix: sign base64 payload in DiscourseConnect
sso_provider.py · 3 lines

Click SimpleReview → select "Bad signature" → Fix it → HMAC encoding patched, login succeeds

DiscourseConnect vs Discourse SSO — Same Thing

If you searched "discourse sso", "sso discourse", or "discourse single sign on" and ended up here while half the documentation calls it "DiscourseConnect": both are the same protocol. Discourse renamed it in August 2021 to avoid confusion with industry-standard SAML/OAuth SSO. The name change touched:

• sso_secret → discourse_connect_secret
• sso_url → discourse_connect_url
• enable_sso → enable_discourse_connect
• enable_sso_provider → enable_discourse_connect_provider

The endpoints (/session/sso, /session/sso_login, /session/sso_provider), the payload format, and the signing algorithm are unchanged. The Ruby implementation file is still lib/single_sign_on.rb. Old admin settings names continue to work as aliases. So when a 2018 blog post tells you to set sso_secret, that's the same thing as the 2026 admin field discourse_connect_secret.

Two Directions: Discourse as RP vs Discourse as IdP

Before writing any code, decide who owns the user accounts. DiscourseConnect supports both roles:

Most teams want RP. The rest of this article focuses on writing a provider (the RP case — your app issues the identity) and then briefly covers IdP at the end.

The Signing Protocol

Both directions use the same wire format:

1. Build a query-string payload:
     [email protected]&external_id=42

2. Base64-encode the bytes of that string:
     bm9uY2U9Y2I2ODI1MWVlZmI1MjExZTU4YzAwZmYxMzk1ZjBjMGImZW1haWw9...

3. Compute HMAC-SHA256 over the BASE64 STRING (not the decoded payload),
   using the shared secret as the key. Take the hex digest:
     2828aa29899722b35a2f191d34ef9b3ce695e0e6eeec47deb46d588d70c7cb56

4. URL-encode and ship as two query params:
     ?sso=bm9uY2U9Y2I2ODI1...&sig=2828aa29899722b35a2f...

The verifier runs steps 2–3 in reverse on the received sso value and compares the computed sig against the received sig. If they match, the payload is trusted. Then it base64-decodes sso, parses the URL-encoded fields, and uses them.

Required and optional payload fields

The Redirect Dance — ASCII Sequence Diagram

The full flow has six round trips. The user always thinks they "clicked Login on Discourse" but the actual path is:

Notice the nonce travels in both directions: Discourse generates it, includes it in the outbound payload, and the provider must echo it back unchanged in the response. If the provider strips, regenerates, or forgets the nonce, Discourse rejects with "Nonce mismatch".

Provider Implementation: Flask (Python)

Here is a complete working Flask provider. Drop it in app.py, set DISCOURSE_SECRET and DISCOURSE_URL as env vars, and run with flask run. Replace the stub authenticate_user() with your real auth logic.

import os
import hmac
import hashlib
import base64
from urllib.parse import parse_qs, urlencode

from flask import Flask, request, redirect, session, render_template_string, abort

app = Flask(__name__)
app.secret_key = os.environ["FLASK_SECRET"]

DISCOURSE_SECRET = os.environ["DISCOURSE_SECRET"].encode("utf-8")
DISCOURSE_URL    = os.environ["DISCOURSE_URL"]   # e.g. https://forum.example.com


def sign(payload_b64: bytes) -> str:
    """HMAC-SHA256 of the base64 payload bytes, hex digest."""
    return hmac.new(DISCOURSE_SECRET, payload_b64, hashlib.sha256).hexdigest()


@app.route("/sso", methods=["GET"])
def sso_entry():
    sso  = request.args.get("sso", "")
    sig  = request.args.get("sig", "")

    # 1. Verify Discourse signed this request with our shared secret.
    expected = sign(sso.encode("utf-8"))
    if not hmac.compare_digest(expected, sig):
        abort(403, "Bad signature on inbound request")

    # 2. Decode the payload and extract the nonce + return_sso_url.
    decoded = base64.b64decode(sso).decode("utf-8")
    fields  = {k: v[0] for k, v in parse_qs(decoded).items()}
    session["sso_nonce"]      = fields["nonce"]
    session["sso_return_url"] = fields["return_sso_url"]

    # 3. If user is already logged in, finish immediately. Else show login.
    if "user_id" in session:
        return _redirect_back_to_discourse(session["user_id"])
    return render_template_string(LOGIN_FORM)


@app.route("/login", methods=["POST"])
def do_login():
    user = authenticate_user(request.form["email"], request.form["password"])
    if not user:
        abort(401)
    session["user_id"] = user["id"]
    return _redirect_back_to_discourse(user["id"])


def _redirect_back_to_discourse(user_id: int):
    user = lookup_user(user_id)
    payload = {
        "nonce":       session["sso_nonce"],     # echo back unchanged
        "email":       user["email"],
        "external_id": str(user["id"]),
        "username":    user["username"],
        "name":        user["full_name"],
        "avatar_url":  user.get("avatar_url", ""),
    }
    encoded   = urlencode(payload).encode("utf-8")
    sso_b64   = base64.b64encode(encoded)
    sig       = sign(sso_b64)
    return redirect(
        f"{session['sso_return_url']}?sso={sso_b64.decode()}&sig={sig}"
    )


# ── Stubs — replace with your auth + user lookup ──────────────────
def authenticate_user(email, password):
    # query DB, verify bcrypt hash, etc.
    return {"id": 42, "email": email, "username": "jane", "full_name": "Jane Doe"}

def lookup_user(user_id):
    return {"id": user_id, "email": "[email protected]", "username": "jane",
            "full_name": "Jane Doe", "avatar_url": "https://cdn.example.com/jane.png"}


LOGIN_FORM = """
<form method=post action=/login>
  <input name=email type=email placeholder=Email required>
  <input name=password type=password placeholder=Password required>
  <button>Sign in</button>
</form>
"""

if __name__ == "__main__":
    app.run(port=5000, debug=True)

Then in Discourse admin → Login:

• enable_discourse_connect = ON
• discourse_connect_url = https://auth.example.com/sso
• discourse_connect_secret = same value as DISCOURSE_SECRET env var (must be ≥ 10 chars)

Provider Implementation: Express (Node.js)

The same flow in Node, using only the standard library plus express and express-session:

const express = require("express");
const session = require("express-session");
const crypto  = require("crypto");
const querystring = require("querystring");

const DISCOURSE_SECRET = process.env.DISCOURSE_SECRET;
const DISCOURSE_URL    = process.env.DISCOURSE_URL;

const app = express();
app.use(express.urlencoded({ extended: false }));
app.use(session({
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: true,
  cookie: { secure: true, httpOnly: true, sameSite: "lax" },
}));

function sign(b64) {
  return crypto.createHmac("sha256", DISCOURSE_SECRET).update(b64).digest("hex");
}

app.get("/sso", (req, res) => {
  const { sso, sig } = req.query;
  if (!sso || !sig) return res.sendStatus(400);

  // 1. Verify inbound HMAC.
  const expected = sign(sso);
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
    return res.status(403).send("Bad signature on inbound request");
  }

  // 2. Decode payload — extract nonce + return URL.
  const decoded = Buffer.from(sso, "base64").toString("utf-8");
  const fields  = querystring.parse(decoded);
  req.session.ssoNonce     = fields.nonce;
  req.session.ssoReturnUrl = fields.return_sso_url;

  // 3. If already logged in, redirect immediately.
  if (req.session.userId) return finishSso(req, res, req.session.userId);
  res.send(LOGIN_FORM);
});

app.post("/login", async (req, res) => {
  const user = await authenticateUser(req.body.email, req.body.password);
  if (!user) return res.sendStatus(401);
  req.session.userId = user.id;
  return finishSso(req, res, user.id);
});

async function finishSso(req, res, userId) {
  const user = await lookupUser(userId);
  const payload = {
    nonce:       req.session.ssoNonce,
    email:       user.email,
    external_id: String(user.id),
    username:    user.username,
    name:        user.fullName,
    avatar_url:  user.avatarUrl || "",
  };
  const encoded = querystring.stringify(payload);
  const ssoB64  = Buffer.from(encoded, "utf-8").toString("base64");
  const sig     = sign(ssoB64);
  res.redirect(
    `${req.session.ssoReturnUrl}?sso=${encodeURIComponent(ssoB64)}&sig=${sig}`
  );
}

// Stubs
async function authenticateUser(email, password) {
  return { id: 42, email, username: "jane", fullName: "Jane Doe" };
}
async function lookupUser(id) {
  return { id, email: "[email protected]", username: "jane",
           fullName: "Jane Doe", avatarUrl: "https://cdn.example.com/jane.png" };
}

const LOGIN_FORM = `
<form method=post action=/login>
  <input name=email type=email placeholder=Email required>
  <input name=password type=password placeholder=Password required>
  <button>Sign in</button>
</form>`;

app.listen(5000);

Two production gotchas with the Node version:

• Use crypto.timingSafeEqual, not ===, for HMAC comparison. String compare leaks timing info that lets attackers brute-force the signature byte-by-byte. The Python version above uses hmac.compare_digest for the same reason.
• The buffers must be the same length. If you accidentally pass a Buffer with different length to timingSafeEqual, Node throws synchronously. Wrap in try/catch or pre-check lengths.

Common Errors and Fixes

Field-by-field debug map for the four errors you'll actually see:

The five-minute debug routine

1. On the provider, log the inbound sso and sig verbatim and the computed expected sig. Compare them character by character. A single trailing newline in your secret env var corrupts every HMAC.
2. Base64-decode the inbound sso on the command line: echo "<sso_value>" | base64 -d. You should see nonce=...&return_sso_url=.... If not, the value got URL-encoded twice somewhere.
3. On the response side, before you redirect, print the response payload, the base64, and the sig. Verify Discourse-side using the same echo | base64 -d trick on the value you're about to ship.
4. In a Discourse rails console: DiscourseConnect.parse(sso, sig).lookup_or_create_user(...) — this is what Discourse runs internally, and it gives a clearer error than the web UI.
5. If Discourse logs are accessible: tail -f /var/discourse/shared/standalone/log/rails/production.log. The exact failure line is logged with the constructed expected sig.

Discourse as IdP — The Reverse Direction

If your forum predates the rest of your product, you can flip the script: Discourse becomes the identity provider, and a satellite app (knowledge base, internal tool, marketplace) consumes Discourse identities.

In Discourse admin → Login:

• enable_discourse_connect_provider = ON
• discourse_connect_provider_secrets: one entry per consumer, format https://kb.example.com|secret_for_kb, one per line.

The flow is the same protocol in mirror image. Your consumer app generates the nonce, Discourse authenticates the user, Discourse signs the response. Skeleton consumer code in Python:

import secrets, base64, hmac, hashlib
from urllib.parse import urlencode, parse_qs

DISCOURSE_URL = "https://forum.example.com"
SECRET        = b"secret_for_kb"

def start_login(return_url):
    nonce   = secrets.token_hex(16)
    payload = urlencode({"nonce": nonce, "return_sso_url": return_url}).encode()
    sso     = base64.b64encode(payload)
    sig     = hmac.new(SECRET, sso, hashlib.sha256).hexdigest()
    # Save nonce in your session for later verification
    return f"{DISCOURSE_URL}/session/sso_provider?sso={sso.decode()}&sig={sig}", nonce

def verify_callback(sso, sig, expected_nonce):
    if hmac.new(SECRET, sso.encode(), hashlib.sha256).hexdigest() != sig:
        raise ValueError("Bad signature")
    fields = {k: v[0] for k, v in parse_qs(base64.b64decode(sso).decode()).items()}
    if fields["nonce"] != expected_nonce:
        raise ValueError("Nonce mismatch")
    return fields  # {email, external_id, username, ...}

The endpoint is /session/sso_provider on Discourse (not /session/sso). The response payload contains the same fields as before, plus Discourse-specific extras like admin, moderator, groups, and profile_background_url.

Sync vs JIT Provisioning: When to Use override_X

By default Discourse uses Just-In-Time provisioning: on first login, fields like username, name, and avatar_url are taken from your payload, but on subsequent logins the user can edit them inside Discourse and your provider's values are ignored. This is usually what you want.

Set override_X=true when:

• override_username — your app is the source of truth for usernames (e.g. employee directory). Otherwise leave off so users can pick a forum-specific handle.
• override_name — names change on the provider side (marriage, legal change) and you want them mirrored.
• override_avatar — you have a Gravatar-like centralized avatar. Note: every login fetches the URL, which adds latency.
• override_email — only when your provider is authoritative for email. Discourse will update the user's email and require re-verification.

Group Sync

The add_groups and remove_groups fields let you synchronize Discourse group membership from your app. Send the comma-separated list of group names (not IDs):

# In your provider response:
payload = {
    "nonce":         nonce,
    "email":         user.email,
    "external_id":   str(user.id),
    "add_groups":    "customers,early_access",
    "remove_groups": "trial",
}

This is how teams gate Discourse categories by their own subscription tiers — your billing system tracks who's a Pro customer, the SSO payload says add_groups=pro_customers, and Discourse grants access to the Pro-only category.

Logout Flow

Single sign-out is opt-in. To log a user out from Discourse when they log out of your app:

1. In admin, set logout_redirect to your app's logout URL.
2. When your app logs the user out, also call the Discourse Admin API: POST /admin/users/:id/log_out (requires API key).
3. Alternatively, send logout=true in an SSO payload — Discourse will log the user out and not re-authenticate.

When to Hand It Off to AI

HMAC bugs are the worst kind: silent, deterministic, and the error message ("Bad signature for payload") only tells you the comparison failed, not why. Half the time it's a base64-vs-raw mistake; the other half it's a one-character secret diff between admin and env var.

SimpleReview diffs your provider implementation against the canonical Ruby SingleSignOn class, runs an HMAC against a known-good fixture, and prepares a fix with the fix. Useful when you're staring at the bad-signature screen and have already triple-checked the secret.

Frequently Asked Questions

Related Discourse Guides

Sources

• meta.discourse.org — DiscourseConnect: Official Single Sign On (rebrand thread)
• github.com/discourse — lib/single_sign_on.rb (canonical signing implementation)
• meta.discourse.org — Setting up DiscourseConnect as an SSO Provider (Discourse-as-IdP)
• meta.discourse.org — Support category: SSO troubleshooting threads
• meta.discourse.org — sync_sso admin API for backfilling external_id