Skip to main content

Dozuki Single Sign On

Dozuki SSO allows the users of your site to be automatically signed in when they visit your Dozuki site. To make this as simple as possible, we provide a canonical implementation which you can copy and alter and may be all you need.

Terms

Your Site
The website whose user signin state will be shared with your Dozuki site.
Your Dozuki Site
The dozuki.com website that users will be automatically signed in to.
Remote Authentication URL
The URL on your site of the page you create from below.

What You Need To Do

Pick a URL on your site for remote authentication

It can be whatever you want, but it must be accessible by all users, even those that are not signed in.

Create a page that responds to that URL

The page should follow the below logic:

  1. If the register url parameter is set to "1", send the user to your register/signup page, and then back to your Remote Authentication URL.
  2. If the logout url parameter is set to "1", the user has just logged out of Dozuki. You should show them a 'logged out' page or send them someplace that won't immediately send them back to Dozuki.
  3. If the user is not signed in, send them to your signin page, and then back to this same URL.
  4. Build a URL encoded HTTP query string of the required parameters (exclude the question mark)
    query = "userid=2345&email=george@email.com&name=George&t=1357604345"
  5. Compute the hex representation of the SHA1 hash of your SSO secret appended to the end of the query string. Note: the secret should NOT be sent in the query string.
    hash = hex(sha1(query + secret))
  6. Append &hash=abcd01234... to the end of your query string
    query = query + "&hash=" + hash
  7. Redirect the user to the URL: http://learn.ooznest.co.uk/Guide/User/remote_login with your query string from above appended to the end.
    url = "http://learn.ooznest.co.uk/Guide/User/remote_login?" + query

Required URL Parameters

The order is only important for the hash parameter, which MUST be the last parameter.

Parameter Description
userid A string that uniquely identifies the signed in user. This can be anything that doesn't change: (id, email, username).
email The user's email address. It must be valid and unique among your users.
name The display name for the user.
t Unix timestamp. The integer number of seconds since Unix EPOCH expressed in GMT.
hash Hex representation of the SHA1 hash from above.

Optional URL Parameters

Parameter Description
role Specify role to set or replace the user's permission level. Roles include: user, author, moderator, admin, and author & mod

Test It

The easiest way to test your implementation is to use the test form in the SSO section of the Manage page for your site.

You can also test your implementation from above by appending /test to the Dozuki URL to make it http://learn.ooznest.co.uk/Guide/User/remote_login/test Then visit the remote authentication URL on your site. You should be redirected to your Dozuki site and see a Success message, or an explanation of failure.

Enable SSO

After using Test mode to verify that your implementation is correct, enable SSO using the management interface and enter your Remote Authentication URL.

Anonymous Users

If a user is redirected to your remote authentication URL and they are not signed in, you will need to send them to your signin page and then redirect them back to your remote authentication URL once they've been authenticated.

Updating User Information

You can update a user's information by sending a different email, name, or role parameter during SSO login. Please note that a user's userid can never be changed.

Remote Logout

To sign a user out of your Dozuki site, send a POST request from your server to http://learn.ooznest.co.uk/Guide/User/remote_logout with the same URL parameters as login. This is useful to make users who sign out of your site also signed out of your Dozuki site. Make this HTTP request from your server and do not direct users to this URL. A successful request results in a blank 204 No Content response.

Reference Implementations

Here are some examples to make it easier to implement SSO:

Single Sign On: SAML

SAML allows the users of your organization to be automatically signed in when they visit your Dozuki site. By configurating your current Identity Provider for use with Dozuki as a Service Provider, you can administer user accounts through your existing ADFS/LDAP or other SAML provider.

Terms

Identity Provider URL
The URL that Dozuki will redirect users to for authentication.
Identity Provider X.509 Certificate
The certificate used by Dozuki to verify XML documents from your Identity Provider.
Logout URL
The URL that users are redirected to after they logout.

What You Need To Do

Set the Required SAML Settings

SAML settings are accessible at the Admin Security interface. You will need to set the Identity Provider URL, Identity Provider X.509 Certificate, and Logout URL.

If your SAML Identity Provider supports importing settings through a metadata.xml file, there is a link on the same page title SAML Metadata.

Please note that if you are using ADFS as an Identity Provider, you will need to map LDAP Attributes to Outgoing Claim Types in your Claim Rule.

LDAP Attribute Outgoing Claim Type
Display-Name username
E-Mail-Addresses email
SAML-Account-Name userid

Set the Optional SAML Settings

LDAP Attribute Outgoing Claim Type
Role role

Specify role to set or replace the user's permission level. Roles include: user, author, moderator, admin, and author & mod. Setting custom attributes will vary depending on your provider

Test It

The Identity Provider URL and Logout URL fields have dialogs to test that the SAML URLs given redirect correctly.