Single Sign On can be used to handle Discourse user authentication from a separate site. The Setup DiscourseConnect - Official Single-Sign-On for Discourse (sso) topic has details about how to implement DiscourseConnect.
The Problem
With DiscourseConnect, Discourse users will be created or updated when they login to Discourse from your external website. What it doesn’t handle is when you need to create or update Discourse users without having them login to your site. For sites that are using DiscourseConnect, these cases should be handled by making an authenticated POST
request to the sync_sso
route.
Note: if you are using the Discourse API gem, you can use the gem’s sync_sso
method instead of using the following code. See the examples directory for instructions on how to use the method.
As an example, we’ll take a case where a user is added to a group on the parent site, and they need to be added to a corresponding group on Discourse without having to first login with DiscourseConnect. The name of the group on both the website and the forum is ‘eurorack’. The external_id
of the user is 1
and their email is bob@example.com
. The following code is using PHP
. The basic idea can be applied to any programming language.
Setup your API credentials and SSO secret key
$api_key = '4fe83002bb5fba8c9a61a65e5b4b0a3cf8233b0e4ccafc85ebd6607abab4651a';
$api_username = 'system';
$discourse_connect_secret = 'jdhb19*Xh3!nu(#k';
Setup the sso parameters
To see what parameters are available, have a look at the ACCESSORS
section of discourse_connect_base.rb. The parameter that you must include to update an existing user is external_id
. If you are calling sync_sso
for a user who does not yet exist on Discourse, you must include the username
and email
parameters. Discourse will use the username
and email
to create a new user.
To add a user to a group, include the add_groups
parameter. To remove a user from a group, include the remove_groups
parameter. The value for either of these parameters needs to be set to a comma separated string of group names. Spaces are not allowed between the group names.
The require_activation
parameter is being included in the payload. This should be set to true
if the user’s email hasn’t been validated on the parent site. With PHP
the parameter needs to be set to the string ‘true’ to avoid it being converted to the number 1
. If you have validated the user’s email address, you do not need to include this parameter.
// Create an array of SSO parameters.
$sso_params = array(
'external_id' => 1,
'email' => 'bob@example.com',
'username' => 'bob',
'add_groups' => 'eurorack',
'require_activation' => 'true',
);
// Convert the SSO parameters into the SSO payload and generate the SSO signature.
$sso_payload = base64_encode( http_build_query( $sso_params ) );
$sig = hash_hmac( 'sha256', $sso_payload, $discourse_connect_secret );
Send the POST request
For this example I’ll use curl
, set the user_agent
to ‘WordPress/4.9.4’, and the forum URL to https://forum.example.com
$url = 'https://forum.example.com/admin/users/sync_sso';
$post_fields = array(
'sso' => $sso_payload,
'sig' => $sig,
);
$headers = array("Content-Type: multipart/form-data;","Api-Key: $api_key","Api-Username: $api_username",);
$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $url );
curl_setopt( $ch, CURLOPT_POST, 1 );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
curl_setopt( $ch, CURLOPT_HTTPHEADER, $headers );
curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $post_fields ) );
curl_setopt( $ch, CURLOPT_USERAGENT, 'WordPress/4.9.4' );
$result = curl_exec( $ch );
if ( curl_errno( $ch ) !== 0 ) {
// Handle error, call curl_close( $ch ) and return.
}
curl_close( $ch );
$discourse_user = json_decode( $result );
Updating existing users
Requests made to the sync_sso
route will update properties for existing users in the same way as would happen if the user logged into the site with DiscourseConnect. That means that the values of your site’s auth overrides
site settings will be respected for these requests. For example, to update the email address for existing users with requests to sync_sso
, the auth overrides email
setting needs to be enabled. Here are the relevant settings:
auth overrides email
auth overrides username
auth overrides name
Further Reading
To see what is going on, have a look at the sync_sso code, the SingleSignOn
parse method, and the DiscourseSingleSignOn
lookup_or_create_user method.
There is also a JavaScript edition of this guide for those using Node.js.
Last edited by @JammyDodger 2024-05-26T07:22:56Z
Check document
Perform check on document: