Configure single sign-on (SSO) with WP Discourse and DiscourseConnect

The WP Discourse plugin lets you set up DiscourseConnect in Wordpress so your users can use their Wordpress account to log into Discourse, or their Discourse account to log into Wordpress. Before you can set up DiscourseConnect you first have to install the WP Discourse plugin on Wordpress and Connect it to your Discourse. If you’re ready to get started, start by watching this short video, or follow the instructions below.

Next Step

Once you’ve set up DiscourseConnect, you may want to check out the following topics


Instructions

Setting a Secret Key

Whether you’re setting up WP Discourse as the DiscourseConnect Provider or Client, you need to set a secret key. Go to the “DiscourseConnect Secret Key” tab and enter a string of text (numbers, letters, and symbols are all allowed), at least 10 characters long. Use the same rules for creating this as you would to create a strong password. Make sure you save it when you’re done.

Then, open your Discourse Site Settings (in the Admin panel), and search for “discourse connect”. One of the settings near the top will be discourse connect secret. Paste the secret key you set in WP Discourse in there and click the green tick.

Logging into Discourse with Wordpress (DiscourseConnect Provider)

Make sure you’re WP Discourse is connected to your Discourse and your secret key is set ( :point_up: ) before following these instructions

To let your users log into Discourse using their Wordpress account details, you need to setup WP Discourse as the DiscourseConnect Provider. Go to the DiscourseConnect Provider tab in the WP Discourse settings, select the Enable DiscourseConnect Provider checkbox and save your settings.

Next, go to your Discourse Site Settings and enter “discourse connect” into the search box to see all your Discourse DiscourseConnect settings. First, set the discourse connect url to the URL of our Wordpress. The final step is to select enable discourse connect. Make sure you’re ready to go before you select this as once you do, your users will only be able to log in to Discourse using Wordpress.

Once you’ve enabled discourse connect in Discourse, to make sure that it is setup correctly open an incognito window in your browser. Keep your normal (non-incognito) browser window logged in to an admin account (just in case something goes wrong and you need to change the settings back). In the incognito window you’ll notice that the Discourse ‘Sign Up’ button no longer appears. Click on the ‘Log In’ button. You should see a Wordpress login screen. Enter your Wordpress credentials to log in. You should then be redirected back to Discourse and be logged in.

If something goes wrong, or you notice something is not quite right, go back to your normal browser window and disable enable discourse connect to let your users log into Discourse normally. If you’re no longer logged in to your admin account in your normal browser window for some reason, check out the “Disable DiscourseConnect Through the Discourse Console” section in Troubleshooting below to regain access to your Discourse.

Email Verification

Discourse expects all user’s email addresses to be verified and WordPress doesn’t force users to verify their email address. In a default WordPress setup it is fairly easy to verify a user’s email address during the registration process, but if a site is using a plugin that creates a front end registration form - for example, the registration form that can be added with WooCommerce - the WP Discourse plugin isn’t able to verify the user’s email.

In users’ emails aren’t being verified in Wordpress, before a WordPress user will be able to login to the forum, they will need to respond to an email verification notice that is sent out by Discourse. The plugin has a couple of filters that can be used to override this behaviour. Take a look at the code, starting here, for details.

Remove the require_activation flag

If you’re sure that WordPress is authenticating email addresses, you can tell Discourse that it doesn’t need to. To completely remove the require_activation flag, add something like this to your Wordpress (e.g. in your theme’s functions.php file):

// Replace 'my_prefix' with your site prefix.

add_filter( 'discourse_email_verification', 'my_prefix_discourse_email_verification' );
function my_prefix_discourse_email_verification( $require_activation ) {
    return false;
}

To remove the require_activation flag for specific users, use something like this:

// Replace 'my_prefix' with your site prefix.

add_filter( 'discourse_email_verification', 'my_prefix_discourse_email_verification', 10, 2 );
function my_prefix_discourse_email_verification( $require_activation, $user_id ) {
    $user = get_userdata( $user_id );
    if ( /* some condition tested against $user */ ) {

        return true;
    }

    return false;
}

Userdata Webhook

This Webhook exists for historical reasons - having the Discourse Name field automatically filled in can now be accomplished by using the Create or Sync Discourse Users on Login DiscourseConnect Provider option.

The Update Userdata webhook (in the “Webhooks” settings panel) can be used when WordPress is the DiscourseConnect Provider for your Discourse. The webhook automatically fills in the user’s Discourse Name field on WordPress.

Creating an DiscourseConnect Login Link

If you have the DiscourseConnect Provider option enabled, you can add a DiscourseConnect login link to your WordPress site by creating a link with the following structure:

<a href="https://discourse.example.com/session/sso?return_path=/">Community</a>

Set the value of return_path to the page on your forum you would like the user to end up on. You can add an SSO login link to a WordPress menu by adding a URL with this structure as a Custom Link in the Menus section of the WordPress dashboard.

Logging in to WordPress with Discourse (DiscourseConnect Client)

To enable your site to function as an DiscourseConnect Client for Discourse, click on the DiscourseConnect Client tab. On that page, select the Enable DiscourseConnect Client and Add Login Link options.

Now go to your Discourse Admin / Settings page and search for ‘discourse connect’ to see all your DiscourseConnect options.

  • select the ‘enable discourse connect provider’ setting
  • copy your DiscourseConnect Secret Key from WordPress to the ‘secret’ field of the Discourse ‘discourse connect provider secrets’ setting. In that setting’s ‘domain’ field enter your WordPress site’s domain. Then click the green checkmark to save your settings.

When complete, the ‘discourse connect provider secrets’ setting on Discourse should look like this (with the domain set to your WordPress domain):

Discourse should now be functioning as a DiscourseConnect provider for your WordPress site.

Open your Wordpress site in an incognito window in your browser. When you now go to your login page, you should see a ‘Log in with Discourse’ link underneath the login form. Click it and you’ll be taken to the Discourse login form. Login there, and you’ll be redirected back to the WordPress login page with a notice saying that you need to sync your account with Discourse. Follow the instructions in the notice to link your accounts, and you should now be able to log into your WordPress site through Discourse.

Note: this behaviour only affects users who have existing accounts on both WordPress and Discourse. New WordPress accounts that are created through Discourse DiscourseConnect will be able to login freely to WordPress the first time the click the ‘Log in with Discourse’ link. To make it easier for users with existing accounts on both your WordPress site and your Discourse forum to login through Discourse, select the Sync Existing Users by Email checkbox on the DiscourseConnect Client options tab.

Syncing Discourse Logout

When DiscourseConnect is enabled, logout from Discourse can be synced with your WordPress site by adding your site’s home_url with the query parameter request=logout to the Discourse Site Setting logout redirect. The setting is in the Discourse settings section at /admin/site_settings/category/users. Here’s an example ‘logout redirect’ URL:

http://example.com/?request=logout

Troubleshooting

If you’re having issues with using WordPress as the DiscourseConnect provider for your forum, the first things to check are:

  • that the DiscourseConnect Secret keys set on WordPress and Discourse are the same
  • make sure that you have selected Enable DiscourseConnect Provider on your WordPress site
  • make sure you have entered the correct discourse connect url on Discourse.

“Login Error” when using DiscourseConnect

If users are getting a “Login Error” message when they attempt to login to Discourse, please see

Debug and fixing common DiscourseConnect issues.

Disabling DiscourseConnect

If DiscourseConnect isn’t working for you, you can turn it off by disabling the enable discourse connect site setting. If you’re not still logged into an admin account somewhere to turn it off, don’t worry, there’s a few ways you can get back in to turn it off.

Login via /users/admin-login

Open a new browser window and enter your forum URL in the URL bar followed by /users/admin-login, e.g.

https://community.mysite.com/users/admin-login

You should see an input asking you for your admin email. After you submit your email, you’ll receive an email with a link that will allow you to log-in directly to your admin account. You can then go to your site settings and disable enable discourse connect to turn DiscourseConnect off.

If this doesn’t work for some reason, don’t worry, you can still turn DiscourseConnect off via your server’s console (:point_down:)

Turn off DiscourseConnect through the server console

If you don’t know what the server console is, or you don’t have access to it, reach out to your hosting provider for help. After you’ve SSH’d into your server, the commands you need to run are as follows:

cd /var/discourse
./launcher enter app
rails c
SiteSetting.enable_discourse_connect=false
exit
exit
6 Likes