How to Integrate Keycloak SSO with Discourse (OIDC Complete Guide)

Cloud Services Support
1

keycloak_discourse_featured
keycloak_discourse_featured1200×630 12.9 KB

:locked_with_key: How to Integrate Keycloak SSO with Discourse (OIDC Complete Guide)

:rocket: Introduction

Single Sign-On (SSO) is no longer optional for modern platforms. If you’re running a Discourse forum, integrating it with Keycloak using OpenID Connect (OIDC) gives you centralized authentication, improved security, and seamless user experience.

In this guide, we walk through a complete, production-grade setup of Keycloak SSO with Discourse—including configuration, troubleshooting, and best practices.

:puzzle_piece: Architecture Overview

Your setup looks like this:

  • Discourse Forum: https://www.forum.nestict.com

  • Keycloak Identity Provider: https://www.authentication.nestict.africa

  • Realm: nestict

  • Client ID: forum

:link: Understanding the OIDC Authorization URL

Example:

https://www.authentication.nestict.africa/realms/nestict/protocol/openid-connect/auth
?client_id=forum
&redirect_uri=https://www.forum.nestict.com/auth/oidc/callback
&response_type=code
&scope=openid
&state=xyz
&nonce=abc

Key Parameters Explained

Parameter Purpose
client_id Identifies Discourse in Keycloak
redirect_uri Callback URL after login
response_type=code Uses secure Authorization Code Flow
scope=openid Enables OIDC authentication
state CSRF protection
nonce Prevents replay attacks

:gear: Step 1: Configure Keycloak

1. Create Client

Navigate:

Keycloak → Realm: nestict → Clients → Create

Set:

  • Client ID: forum
  • Client Protocol: openid-connect

2. Client Settings

Configure:

  • Access Type: public

  • Standard Flow Enabled: :white_check_mark:

  • Direct Access Grants: :cross_mark:

  • Root URL:

    https://www.forum.nestict.com

3. Valid Redirect URIs

https://www.forum.nestict.com/*

:warning: Critical: Any mismatch here causes:

Invalid parameter: redirect_uri

4. Web Origins

https://www.forum.nestict.com

:gear: Step 2: Configure Discourse (OIDC)

Go to:

Admin → Plugins → OpenID Connect

Required Settings

  • OIDC Enabled: :white_check_mark:
  • OIDC Discovery Document:
https://www.authentication.nestict.africa/realms/nestict/.well-known/openid-configuration
  • Client ID: forum
  • Client Secret: (leave empty if public client)

Callback URL (Important)

https://www.forum.nestict.com/auth/oidc/callback

Make sure this EXACT URL is in Keycloak.

:locked_with_key: Step 3: Discourse Environment Configuration

If using Docker / EasyPanel:

DISCOURSE_HOSTNAME=forum.nestict.com
DISCOURSE_FORCE_HTTPS=true
DISCOURSE_USE_X_FORWARDED_PROTO=true
DISCOURSE_TRUSTED_PROXIES=0.0.0.0/0

:globe_with_meridians: Reverse Proxy (Nginx / Cloudflare)

Ensure headers are passed correctly:

proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header Host $host;

Without this, login may fail or redirect incorrectly.

:counterclockwise_arrows_button: Authentication Flow

  1. User clicks Login on Discourse
  2. Redirect → Keycloak login page
  3. User authenticates
  4. Redirect back:
/auth/oidc/callback?code=XYZ
  1. Discourse exchanges code → tokens
  2. User is logged in :white_check_mark:

:warning: Common Errors & Fixes

:cross_mark: Invalid parameter: redirect_uri

Cause:

  • Mismatch in Keycloak redirect URI

Fix:

https://www.forum.nestict.com/*

:cross_mark: Infinite Redirect Loop

Cause:

  • HTTPS misconfiguration

Fix:

DISCOURSE_FORCE_HTTPS=true
DISCOURSE_USE_X_FORWARDED_PROTO=true

:cross_mark: Blank Page After Login

Cause:

  • Missing proxy headers

Fix:

X-Forwarded-Proto: https

:cross_mark: Login Works but Session Fails

Cause:

  • Cookie or domain mismatch

Fix:

  • Ensure both services use HTTPS
  • Same top-level domain preferred

:magnifying_glass_tilted_left: Testing Your Setup

Open this in browser:

https://www.authentication.nestict.africa/realms/nestict/protocol/openid-connect/auth?client_id=forum&redirect_uri=https://www.forum.nestict.com/auth/oidc/callback&response_type=code&scope=openid

Expected: :right_arrow: Keycloak login page loads

:shield: Security Best Practices

  • Always use HTTPS

  • Validate state and nonce

  • Restrict redirect URIs (avoid * in production)

  • Use reverse proxy with secure headers

  • Monitor logs in:

    • Keycloak
    • Discourse (/logs)

:chart_increasing: Benefits of Keycloak + Discourse

  • Centralized authentication
  • Multi-application SSO
  • OAuth2 / OIDC compliance
  • Scalable identity management
  • Role-based access control

:brain: Final Thoughts

Integrating Keycloak with Discourse via OIDC transforms your forum into a secure, enterprise-ready platform. While setup requires precision—especially around redirect URIs and proxy headers—once configured, it delivers a seamless login experience across your ecosystem.

:bookmark: Keywords (SEO)

  • Discourse Keycloak integration
  • Discourse OIDC setup
  • Keycloak SSO tutorial
  • OpenID Connect Discourse
  • Self-hosted SSO Kenya
  • Discourse authentication guide

:framed_picture: Featured Image Prompt (1200×630)

Use this in your design tool (Canva / Midjourney / DALL·E):

A modern cybersecurity themed illustration showing a central identity server (Keycloak) connecting securely to a community forum (Discourse), with lock icons, secure tokens, cloud infrastructure, and arrows representing authentication flow. Blue and dark theme, clean UI style, professional SaaS branding, 1200x630.