Integrating Single Sign-On

Access to Single Sign-On (SSO) is currently available as a free add-on for your Disqus account. Please contact our support team via this contact form and ask them to enable it for your account.  Once enabled, you can refer to this documentation on how to implement single sign-on with your site and Disqus.

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

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.

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.
  • 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

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.

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 = '<message> <hmac> <timestamp>';
    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 and Coldfusion

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 = '<message> <hmac> <timestamp>';
    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. Download the SSO login button style guide.
  2. Replace the "Replace this logo" layer with your logo.
  3. Change the button's color (the "Button" layer) to match your branding.
  4. 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 W3 Schools.

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/.

Contact us

We welcome all questions, feedback and bug reports. If you're having an issue, we usually need the following information:

  • A brief description of the issue
  • Link to any page where you saw the issue
  • Screenshots that illustrate the problem - How do I take a screenshot?