So you want to use Discourse as an identity provider for your own web app? Great! Let’s get started.
Enable DiscourseConnect provider setting
Under Discourse admin site settings (/admin/site_settings) enable setting enable discourse connect provider
and add a secret string to discourse connect provider secrets
(used to hash SSO payloads).
Implement DiscourseConnect in your web app:
-
Generate a random nonce. Save it temporarily so that you can verify it with returned nonce value
-
Create a new payload with nonce and return url (where the Discourse will redirect user after verification). Payload should look like:
nonce=NONCE&return_sso_url=RETURN_URL
-
Base64 encode the above raw payload. Let’s call this payload as
BASE64_PAYLOAD
-
URL encode the above
BASE64_PAYLOAD
. Let’s call this payload asURL_ENCODED_PAYLOAD
-
Generate a HMAC-SHA256 signature from
BASE64_PAYLOAD
using your sso provider secret as the key, then create a lower case hex string from this. Let’s call this signature asHEX_SIGNATURE
Send auth request to Discourse
Redirect the user to DISCOURSE_ROOT_URL/session/sso_provider?sso=URL_ENCODED_PAYLOAD&sig=HEX_SIGNATURE
Get response from Discourse:
If the above steps are done correctly Discourse will redirect logged in user to the provided RETURN_URL
. You will get query string parameters with sig
and sso
along with some user info. Now follow below steps:
-
Compute the HMAC-SHA256 of
sso
using sso provider secret as your key. -
Convert
sig
from it’s hex string representation back into bytes. -
Make sure the above two values are equal.
-
Base64 decode
sso
, you’ll get the passed embedded query string. This will have a key callednonce
whose value should match the nonce passed originally. Make sure that this is the case, and be sure to delete thenonce
from your system. -
You’ll find this query string will also contain a bunch of user information, use as you see fit.
That’s it. By now you should have set up your web app to use Discourse as SSO provider!
Discourse official “Using Discourse as identity provider” implementations:
- An http proxy (using golang) that uses Discourse SSO to authenticate users (only Admins): GitHub - discourse/discourse-auth-proxy: An http proxy that uses the DiscourseConnect protocol to authenticate users (made by @sam)
Community contributed “Using Discourse as SSO provider” implementations:
-
A PHP script that implements Discourse as SSO provider: Discourse sso provider login · GitHub (made by @paxmanchris)
-
Node.js:
GitHub - edhemphill/passport-discourse: A Passport strategy for authenticating using a Discourse forum
GitHub - ArmedGuy/discourse_sso_node: npm package for Discourse SSO login features. -
ASP.NET Core (only requires configuration):
GitHub - Biarity/DiscourseSso: Easy, configurable Discourse SSO: GET /auth/login -> recieve a JWT with user data -
MediaWiki extension (PHP):
DiscourseSsoConsumer, a SSO extension for MediaWiki (made by @mdoggydog)