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://noplacelikehome.ifixit.com/Guide/User/remote_login with your query string from above appended to the end.

   url = "http://noplacelikehome.ifixit.com/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://noplacelikehome.ifixit.com/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://noplacelikehome.ifixit.com/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:

• SSO for PHP (Source)
• Our GitHub Repository

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 Entity ID

The URI (unique resource identifier) of your Identity Provider. May be referred to as the Issuer depending on your Identity Provider.

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 Entity ID, 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.