All Collections
Developer
Integrating Single Sign-On
Integrating Single Sign-On
Disqus avatar
Written by Disqus
Updated this week

**Access to Single Sign-On (SSO) is currently available as an add-on for users with a Business level subscription. If you would like to subscribe, you can request information from one of our account managers here.

  • Configure your remote domain

  • Configure your application

  • Using HMAC-SHA1 to pass user data

  • Code samples

  • SSO Script

  • Adding your own SSO login and logout links

  • Handling User Deletions

Introduction

For the purpose of this document, we define "users" as visitors to a site that wish to leave comments or otherwise interact with Disqus Comments. "Site" refers to the site or blog using Disqus to power and manage comments. "Disqus" refers to the Disqus Comments service, serving from disqus.com.

Single sign-on (SSO) allows users to sign into a site and fully use Disqus Comments without again authenticating with Disqus. SSO will create a site-specific user profile on Disqus so as not to clash with existing users of Disqus.

Configure your remote domain

Please note that you'll want to create your API application and complete the Remote Domain steps while logged in with your Organization Owner account.
Before you start, you will first have to go to your SSO page to configure your remote domain. Once done, you'll be able to test the payload you create in the next part. Try to refrain from using any non-alphanumeric characters to prevent conflicts from happening. The name assigned to your remote domain is permanent and non-transferable.

The SSO "domain" isn't so much a domain as it is a store of your users on Disqus. It's attached to your Org Owner user account rather than a specific site, so there is no way to have multiple domains for a single Organization. If needed, you could namespace your IDs with a user group prefix of your choosing to avoid conflicts across multiple site user databases. So if you have a user with id '12345', you can use 'localhost-12345' and 'production-12345' to keep their entries separate.

If you require an additional remote domain, a new user account and Organization will be required.

Configure your application

In order for SSO to function properly you'll need to verify that you've setup the following items in your API application:

  • Domains - Enter each domain that will be using SSO.

  • SSO Domain - Select the remote domain previously setup.

  • Authentication - Use OAuth permissions as the authentication method

Note: If you are using the deprecated Inherit Permissions authentication you can safely update to OAuth permissions to use SSO. If you're making any API calls using this application, you can attach admin privileges to any API request by adding your access token and the appropriate scope parameters.

Using HMAC-SHA1 to pass user data

Using JSON-serialized user data and HMAC-SHA1, publishers can pass existing user data to provide users with a seamless authenticated session on Disqus. Messages are composed of the following three parts, separated with a single white space.

The message body (Base64-encoded)

The message body must include the following case sensitive properties unless noted otherwise:

  • id - any unique user ID associated with that account within your user database. This will be used to generate a unique username to reference in the Disqus system. IDs must be completely unique; if you're using multiple datastores locally, for example, make sure not to re-use IDs when passing them to Disqus as that will result in account conflicts. User ID will be publicly accessible through the Disqus API, so you'll want to ensure that the ID passed does not contain any personally identifiable information. 

  • username - The displayed name for that account

  • email - The registered email address for that account

  • avatar (optional) - A link to that user's avatar. Note: URL must be less than 200 characters.

  • url (optional) - A link to the user's website

  • profile_url (optional) - A link to the user's profile that exists on the site's own domain. This is only used if the SSO integration is linking out to user profiles that exist on the site's own domain, rather than the Disqus profile.

HMAC-SHA1 signature

Generated using HMAC->SHA1(secret_key, message + ' ' + timestamp)

Timestamp (NOT Base-64 encoded)

The timestamp when the message was generated, formatted as a Unix timestamp.
​ 
​ Note: SSO payloads expire after 2 hours.

The SSO script

Once your message has been generated, use the following script before the Disqus embed on your page:

var disqus_config = function () {
    // The generated payload which authenticates users with Disqus
    this.page.remote_auth_s3 = '  ';
    this.page.api_key = 'public_api_key';
}

You will need to ensure that the application key you are using is associated with the forum on which you using this packet as well.

Logging out

To log a user out of SSO, pass remote_auth_s3 as an encoded/signed empty JSON object ({}) as the message data.

Examples

SSO code examples
 PHP, Python, C#, Ruby, Java, Coldfusion, and React

Clone on Glitch to try our functional demo code for yourself.

Adding your own SSO login and logout links

You can configure Disqus to display your site's login button together with default options (Facebook, Twitter, etc.) and replace default logout URL. You will need to host a small (143x32) image that will act as a button. Continued from the above example, add the following to your existing SSO script:

var disqus_config = function () {
    // The generated payload which authenticates users with Disqus
    this.page.remote_auth_s3 = '  ';
    this.page.api_key = 'public_api_key';// This adds the custom login/logout functionality
    this.sso = {
          name:   "SampleNews",
          button:  "http://example.com/images/samplenews.gif",
          icon:     "http://example.com/favicon.png",
          url:        "http://example.com/login/",
          logout:  "http://example.com/logout/",
          width:   "800",
          height:  "400"
    };
};

Details:

  • name — Your site's name. We will display it in the Post As window.

  • button — Address of the image that acts as a button. Disqus 2012 users, see style guide below.

  • icon — Address of the image that appears on the login modal's SSO tab. Favicons work well here. (Not required in Disqus 2012.)

  • url — Address of your login page. The page will be opened in a new window and it must close itself after authentication is done. That's how we know when it is done and reload the page.

  • logout — Address of your logout page. This page must redirect user back to the original page after logout.

  • width — Width of the login popup window. Default is 800.

  • height — Height of the login popup window. Default is 400.

Note: All links must be the absolute URL. Because these are loaded within the disqus.com iframe, some browsers interpret relative links as coming from disqus.com

Create your own SSO login button

To keep your login button consistent with the Disqus embed's look and feel:

  1. Replace the "Replace this logo" layer with your logo.

  2. Change the button's color (the "Button" layer) to match your branding.

  3. Keep the shape's border radius so that it matches with the other service icons.

Tip: If the login window does not close automatically, you can use a Javascript snippet to close it. For more information, please visit: Window close() Method at MDN web docs.

Using the SSO debug tool

Disqus provides a tool to help you debug SSO messages. You may access the tool by visiting http://disqus.com/api/sso/.

Handling User Deletions

SSO is designed put your site in control of account creations and updates using the data your server provides. For this reason, your site should also trigger an SSO account deletion when someone wants to delete their account in your user management system. Here are some high-level guidelines for how to perform the deletion:

  1. Create a deletion method. If your site doesn't already provide an account deletion method, create a button or link that allows authenticated to initiate a deletion in your user management system (typically located in a Settings >  Account module).

  2. Overwrite SSO user data properties. After the account deletion is successfully confirmed on your end, update all of the Disqus user data properties (except for the unique user ID) with generic placeholder data to overwrite identifiable attributes like username and email. See Using HMAC-SHA1 to pass user data section above.

  3. Load embed.js with the updated SSO script. After updating the user data payload, you can load embed.js  "in the background" without displaying the #disqus_thread element. Include the updated remote_auth_s3  object within the disqus_config  function, and the overwrite update will be sent to Disqus.

Did this answer your question?