Discourse Single-Sign-On Forum

Discourse is a powerful forum system that is available as hosted platform or a self-hosted solution. In both cases, Doki and Discourse can be linked so your Doki users sign on via Doki to access your Discourse forums. This is is called Single-Sign-On (or SSO). In this case, Discourse will ask Doki to see if a user is logged in and then sign them into the Discourse forum. This allows you to add forum support to your Doki account.

Set up is rather complex, so read the following set up documentation thoroughly before enabling single sign on, and feel free to reach out to support if you have questions.

Doki will become the authority for signing into Discourse. Users who do not have a Doki account on your Doki site will not be able to sign on to your forums after you enable this. You can, however, create a user account for your existing Discourse users from the "Students" screen. If you have an large number of Discourse users, please contact support and we can arrange the creation of Doki accounts for your user list before you fully enable Discourse.

Step 1: Get Discourse

If you don't have a Discourse install yet, you should start by signing up on  discourse.org. You'll need to add a DNS record to host your account on your own domain, or you can use their temporary domains to start. You can also do this work on a self-hosted Discourse, but setting that up is outside the scope of our documentation as it requires a dedicated developer.

Your Discourse forum should be "Private". During set up, you can select this option on the screen:

If you've already set up your Discourse, you can switch it to private from the Admin settings (we'll discuss this shortly in Step 2).

Step 2: Initial Discourse Setup and Content Gathering

1. Gather your API Key and Username

  1. Sign into your Discourse as the admin user you used to set up initially.
  2. Click on the profile photo in the top right of the screen, then click on the "Gear" icon:

  3. From this screen, have a look at the email. Your admin account email on Discourse must match your admin account email on Doki for the connection to function properly. If you used a different email for your admin account on Discourse, change it to match your Doki admin account email before you continue.
  4. In the top right of the screen, click the "Admin" button. Remember this page! We'll spend most of our time here as this is where our configuration happens:

  5. From this screen, note down your "username". You can see below that my username is "ben":

  6. Important: Once Doki Discourse connection is made, you should not change your username as it is used to make the connection, so set it now and forget it.
  7. Scroll down to the "Permissions" section and click "Generate" next to the "API Key" entry if you don't yet have an API Key. Note down the API key for later. It's long and like a password, so you may want to copy it into a text document so you can copy and paste it later.

2. Set up Login

  1. From the Admin screen, click the "Settings" link in the toolbar.
  2. From the sidebar on the left, click the "Login" link.
  3. Ensure that "invite only: Public registration is disabled, all new users must be explicitly invited by staff." is checked.
  4. Ensure that "login required: Require authentication to read content on this site, disallow anonymous access." is checked.  These two settings make our Discourse private since we only want users who have Doki accounts to have access to the forums.
  5. Ensure that the "sso overrides email" setting is checked. This'll ensure that any chances to the user's email on Doki get copied into Discourse each time they sign in.

Keep this screen open and, in another tab, open up your Doki admin area and continue on to Step 3.

Step 3: Create Doki Integration

  1. Sign into your Doki account as an admin and head over to the Admin tools.
  2. Click on the "Business" link in the sidebar (hint, it's the Briefcase icon).
  3. Click on "Integrations" in the toolbar.
  4. Click on "Connect" next to Discourse integration.
  5. Fill in the information. 
    1. The Discourse URL is the full path to your Discourse website. So if you access your forums at https://community.example.com, put that full URL in there. NOTE:It must include the http or https part and the :// part!
    2. If you leave the "Grant access to forums" checkbox selected, all new users added to Doki will get access to the forums (and all existing users will get access). If you don't, you must manually select which users have access on their profile page.
    3. Copy & paste your API Key from Step 2 into the API Key field.
    4. Copy & paste your Discourse username from Step 2 into the API Username field.
  6. Click Save.

Step 4: Prepare Discourse SSO Login

Now that we've created the integration in Doki, click the newly changed "Configure" button next to the Discourse integration to reveal some new details that were created during the save. We've going to copy these details over to Discourse to finalize the connection. 

  1. In Discourse, head back to the Admin page and click on the Settings tab.
  2. Click on Login in the sidebar.
  3. Copy the "SSO URL" from Doki and paste in into the field labeled "sso url".
  4. Copy the "SSO Secret" from Doki and paste it into the field labeled "sso secret".
  5. Click on Users in the sidebar.
  6. Copy the "Sign Out URL" from Doki and paste it into the field labeled "logout redirect".

When overriding these options, be sure to click the green save button to finalize the entry.

Awesome, you're ready to activate single-sign-on with Discourse.

Step 5: Enable SSO

The final step is to turn on single-sign-on in Discourse. Then Discourse will look to Doki for user accounts instead of Discourse. 

It's important to remember that once this is activated, Discourse sign on will cease functioning. If you need to disable it or revert back, you may have to contact Discourse support, so be certain you're ready to turn this on before you continue. If you want to run your setup by us before you enable it, please open a support ticket and we'll help!

  1. Go to the Admin page in Discourse and click on the Settings tab.
  2. Click on Login in the sidebar. 
  3. Select the checkbox next to "enable sso" and click the green check button to save.

That's it. When you attempt to access your Discourse account now, if you're not signed in, it'll redirect you to Doki to sign in and then back to the forums once you've authenticated. Signing out of Doki or Discourse will automatically sign you out of the other.

User accounts on Discourse are not automatically created when a Doki account is created. They will be created the first time the user accesses the forums through Doki. So don't be alarmed if you don't see a matching account in Discourse yet! This just means the user hasn't accessed the forums for the first time yet.

Still need help? Contact Us Contact Us