​

Discourse Integration Guide

​

Overview

​

Architecture

User clicks "Login" on Discourse (community.cfosilvia.com)
    ↓
Discourse redirects to: https://www.cfosilvia.com/api/discourse/sso?sso=[payload]&sig=[signature]
    ↓
Silvia verifies signature and checks if user is logged in
    ↓
If not logged in: redirect to /sign-in
If logged in: build response with user data
    ↓
Silvia signs response and redirects back to Discourse
    ↓
Discourse verifies signature and creates/updates user account
    ↓
User is logged in to Discourse (community.cfosilvia.com)

​

Setup Instructions

​

1. Generate SSO Secret

openssl rand -hex 32

​

2. Configure Environment Variables

# Discourse SSO Integration
DISCOURSE_SSO_SECRET=your_generated_secret_here
DISCOURSE_URL=https://community.cfosilvia.com

​

3. Configure Discourse Settings

• ✅ enable discourse connect - Enable this to activate SSO
• discourse connect url - Set to: https://www.cfosilvia.com/api/discourse/sso
• discourse connect secret - Use the same secret from step 1

• ✅ discourse connect overrides email - Silvia email takes precedence
• ✅ discourse connect overrides username - Silvia username takes precedence
• ✅ discourse connect overrides name - Silvia name takes precedence
• ✅ discourse connect overrides avatar - Silvia avatar takes precedence

• ✅ invite only - Require users to have a Silvia account
• ✅ verbose discourse connect logging - Enable during testing for detailed SSO logs
• discourse connect allows all return paths - Allow redirects to any Discourse path
• logout redirect - Set to https://www.cfosilvia.com/api/discourse/logout for logout sync

​

4. Deploy to Production

1. Go to Vercel Dashboard → Your Project → Settings → Environment Variables
2. Add:
   • DISCOURSE_SSO_SECRET = Your generated secret
   • DISCOURSE_URL = https://community.cfosilvia.com
3. Redeploy your application

​

5. Test the Integration

1. Log out of both Silvia and Discourse
2. Navigate to your Discourse forum: https://community.cfosilvia.com
3. Click “Login” - you’ll be redirected to the custom community sign-in page at /community-signin
4. Sign in with your credentials (or create an account)
5. Verify you’re automatically redirected back to Discourse and logged in

• Custom welcome message and community branding
• List of community benefits
• Clerk authentication component
• Seamless redirect back to the forum after login

​

6. Verify User Data Sync

• ✅ Email address
• ✅ Username
• ✅ Full name
• ✅ Avatar/profile picture
• ✅ User is created on first login
• ✅ User data updates on subsequent logins

​

User Data Mapping

​

Security Considerations

​

HTTPS Required

​

Secret Management

• Store the SSO secret in environment variables (never commit to git)
• Use the same secret in both Silvia and Discourse
• Rotate the secret periodically (requires updating both systems)

​

Signature Verification

• Silvia verifies Discourse’s signature before processing requests
• Discourse verifies Silvia’s signature before logging in users
• Invalid signatures are rejected with a 403 error

​

Return URL Validation

​

Troubleshooting

​

”Invalid signature” Error

1. Verify DISCOURSE_SSO_SECRET in your .env matches the discourse connect secret in Discourse settings
2. Ensure there are no extra spaces or newlines in either secret
3. Restart your Silvia server after changing the secret

​

”Missing SSO parameters” Error

1. Verify the discourse connect url in Discourse settings is correct
2. Check that Discourse is actually sending the SSO request (check Discourse logs)

​

Users Not Being Created in Discourse

1. Check the Silvia server logs for the SSO response payload
2. Verify the user has a valid email address in Clerk
3. Check Discourse logs for any errors processing the SSO response

​

Redirect Loop

1. Ensure the /api/discourse/sso route checks for Clerk authentication correctly
2. Verify that the redirect_url parameter doesn’t create a loop
3. Check browser cookies are enabled (required for Clerk authentication)

​

Avatar Not Syncing

1. Enable download remote images to local in Discourse settings
2. Verify discourse connect overrides avatar is enabled
3. Check that the avatar URL is publicly accessible

​

Advanced Configuration

​

Custom User Fields

1. Create custom user fields in Discourse (Admin → Customize → User Fields)
2. Add the field mappings to the SSO response in /app/api/discourse/sso/route.ts:

const responsePayload = new URLSearchParams({
  // ... existing fields ...
  'custom.user_field_1': user.unsafeMetadata?.phoneNumber || '',
  'custom.user_field_2': user.unsafeMetadata?.country || '',
});

​

Group Membership

// In /app/api/discourse/sso/route.ts

// Fetch user's subscription from database
const subscription = await getSubscriptionForUser(userId);

const responsePayload = new URLSearchParams({
  // ... existing fields ...
  add_groups: subscription?.tier === 'pro' ? 'pro_members' : 'free_members',
});

​

Logout Sync

1. Enable logout redirect in Discourse settings
2. Set it to: https://www.cfosilvia.com/api/discourse/logout
3. Modify /app/api/discourse/logout/route.ts to redirect to /sign-out

​

Monitoring

​

Success Metrics to Track

• Number of successful SSO logins per day
• Average time to complete SSO flow
• Failed SSO attempts (invalid signatures, missing users, etc.)
• New vs. returning users via SSO

​

Logging

• ✅ Successful SSO completions
• ❌ Invalid signatures
• ❌ Missing parameters
• ❌ User not found errors

✅ Discourse SSO successful for user: user_2abc123xyz
❌ Invalid Discourse SSO signature

​

API Endpoints

​

GET /api/discourse/sso

• sso - Base64-encoded payload from Discourse
• sig - HMAC-SHA256 signature of the sso parameter

• Redirect to Discourse with signed user data
• Or redirect to /sign-in if user not authenticated

​

GET /api/discourse/logout

• sso - Base64-encoded payload from Discourse
• sig - HMAC-SHA256 signature

• JSON success response
• Or redirect to /sign-out to log out of Silvia

​

References

• Discourse Connect (SSO) Official Documentation
• Clerk Authentication Documentation
• HMAC-SHA256 Signing Reference