Wikispaces Single Sign-On


Overview

The instructions below will walk you through creating a Single Sign-On (SSO) integration that will let your Private Label site work with your existing user database. Be sure to read the documentation through completely before you start. Contact Wikispaces support if you run into any trouble or if you have any questions.

Before You Get Started

Map your users

Once SSO has been enabled, you will have two user databases: (1) the database of users accounts that already exists on your Private Label site, and (2) the database of user accounts that already exists on your authentication server. If a user logs in via SSO before you have turned off your Wikispaces Password database and/or migrated your users to your SSO source, a new account will be created for that user — and there is no way to merge the accounts together. To make it easy to integrate the two, you will need to rename all your Private Label user accounts to match the usernames on your authentication server before you turn on SSO. If this is a larger list than you can reasonably rename by hand, contact Wikispaces support and we’ll rename them for you.

Usernames on Wikispaces must be between 3 and 32 characters long and contain only letters (a–z and A–Z); numbers (0–9); and/or the period (.), underscore (_), or hyphen (-) characters. If your usernames do not match the allowed criteria, they must be adjusted. For example, a username of "Mr Jones" might be translated to "Mr_Jones" before being sent to Wikispaces. This can be done through a persistent database mapping on your server, or more easily through a function that replaces invalid characters with valid ones.

Synchronize your authentication server's clock

As a security precaution, the SSO process requires the authentication server to generate exact timestamps for the precise time. The easiest way to ensure accurate time is to synchronize your server's clock to an external time server using the NTP protocol. Failure to do this will lead to problems, as the clock will invariably shift over time and will eventually cause Wikispaces to stop accepting responses from the SSO server and respond with the fatal error, "Time expired."

Consider a custom domain

If your Private Label site and authentication server share a domain suffix (e.g., wiki.custom-domain.com and moodle.custom-domain.com), your Private Label site will have a little more flexibility. Specifically, guests will be able to visit your site and users will be able to log out of a session on one computer without ending their sessions on other computers. Moving your Private Label site to a custom domain isn't strictly necessary, but it's a good idea if doing so isn't too difficult. If you're interested, you can learn more about changing your domain name on our DNS page.

Disconected Mode

In most cases, you will want to leave the Disconnected Mode box unchecked. However, if your SSO server has an inactivity timeout — meaning that it logs users out whenever they leave the main application — you may want to check the Disconnected Mode box. In disconnected mode, Wikispaces will query the SSO server when the user first logs in, and then cache the result. The user will remain logged in to Wikispaces until they log out or close their browser session.

Implementation

Create a page on your authentication server

On your server, create a page that accepts a URL with a returnTo GET parameter. Note that the hostname, path, page name, and returnTo variable name on your server are configurable, e.g.:

http://authentication-hostname.domain.com/sso-page.php?returnTo=[RETURN-URL]

When Wikispaces authenticates a user, it issues a request to this page, filling in the RETURN-URL value with a URL from Wikispaces. The only requirement is that the authentication server and web page be accessible to all of your users.

Create a URL to redirect back to

If the user is logged in on your site — using any method you support (cookie, HTTP authentication, etc.) — your page redirects back to the RETURN-URL Wikispaces provides with some additional GET parameters:
[RETURN-URL]&SSOusername=[USERNAME]&SSOemail=[EMAIL]&SSOtime=[TIMESTAMP]&SSOguid=[UNIQUEID]&SSOsession=[SESSIONID]&SSOvariables=username,email,time,guid,session&SSOencode=[HMAC]
If the user is not logged in, have your page redirect to the above URL without a username and email:
[RETURN-URL]&SSOtime=[TIMESTAMP]&SSOsession=[SESSIONID]&SSOvariables=time,session&SSOencode=[HMAC]
Wikispaces will create a guest session for the user. Depending on the security settings of your Private Label, they may or may not have access to the wiki.

The RETURN-URL may or may not contain a query string (e.g., ?variable1=value), so your page should test the URL and append the additional GET parameters accordingly.

You can use the following additional GET parameters:
Variables
Logged In User
Guest User
Description
SSOusername
required
must be omitted
unique username; required when a user is logged in
SSOemail
required
must be omitted
unique user email address
SSOtime
required
required
UNIX timestamp, in seconds since 1/1/1970 with no decimal portion; must be within 2 minutes of our server time
SSOguid
optional1
must be omitted
unique, unchangeable ID that can be used to identify the user independent of their username
SSOsession
optional2
optional2
an ID associated with the user's session
SSOencode
required
required
HMAC-SHA-1 in hexidecimal form (see next section)
SSOvariables
optional3
optional3
comma-separated list of which variables will be transmitted, and in what order they will appear in the HMAC
Notes:
  1. The SSOguid variable lets Wikispaces carry user data over when a user is renamed on your authentication server. Without it, Wikispaces will create a new user account whenever a username is changed, which will prevent the user from logging in under the old username and cut off access to any data that was associated with the original account.
  2. The SSOsession variable lets Wikispaces coordinate session expiration and invalidation. Without it, Wikispaces will not know to update the session when a user logs into or out of your server, which may lead to situations where the user appears to be logged in to Wikispaces when they aren't, or appears to be a guest after they have already logged in.
  3. If you want to use SSOguid or SSOsession, you need to provide the SSOvariables parameter. If you don't provide the SSOvariables parameter, the default value will be "time,username,email." If you use this default value and allow guest users, you must include empty strings for username and email in the HMAC calculation.

Create the HMAC cryptographic hash

Create a function that will generate the crytographic hash, using HMAC-SHA-1, a shared secret, and the data from the above variables. Variable data is separated with "@@" and concatenated in the order of the SSOvariables variable. The hmac should be sent in lowercase hexit format (0-9, a-f) and should be 40 characters. For example, the default SSOvariables order, "time,username,email," would have the following HMAC data:
TIMESTAMP + '@@' + USERNAME + '@@' + EMAIL
If you wanted to send "time,email,username,session,guid" as the SSOvariables variable, the HMAC data would look like this:
TIMESTAMP + '@@' + EMAIL + '@@' + USERNAME + '@@' + SESSION + '@@' + GUID
You can find a sample HMAC generation function in PHP in the code sample below.

Verify the returnTo

Verify that the returnTo URL is located on the session.wikispaces.net domain, and that the protocol is https (SSL). Failure to do this can expose your users' email addresses and other information to a third party.

Redirect the user to Wikispaces

Redirect the user back to the URL you created above. Wikispaces will verify that the parameters are correct and the HMAC is valid. If the username exists on Wikispaces, we'll log them in. If the account does not yet exist, we'll create an account with the username and email and log the user in (please see Account Mapping below). We never receive the user's password, so the user only needs to log in on your sever, not on ours.

Synchronized Login and Logout

Logging a user in and out of an SSO system happens on the SSO authentication server, without the knowledge of your Private Label site. Unless you synchronize login and logout, the user's session changes will not be reflected in the Wikispaces server. This means that a user who logs out of the SSO system will appear to be logged into your Private Label site for up to 30 minutes after they log out — and will still be able to read the information on your site (but not make any changes). There are three methods for notifying Wikispaces that the user has logged in or out so that Wikispaces can clear its session cache.

Method 1: Shared session ID

If you provide SSOsession during the SSO redirect, Wikispaces will associate your session ID with the Wikispaces session ID. Wikispaces will invalidate the session when your authentication system fetches the following URL:
http://session.PRIVATE-LABEL-DOMAIN/session/clearsession?externalSessionId=EXTERNAL_SESSION_ID
There are several possible ways to trigger this URL:
  1. Your web server can access it through an HTTP client library.
  2. You can redirect the user through it during your login/logout process by adding the returnTo URL parameter (Wikispaces will redirect to the returnTo URL after invalidating the session).
  3. You can add it in a hidden iframe tag on one of the pages your user visits during the login/logout process.

Method 2: iframe

If you don't provide SSOsession during the SSO redirect, the user's browser can store a shared session ID in a cookie. Because browser security limits which domain names session cookies can be sent to, the destination of the login and logout URLs and the Wikispaces Private Label must share a common suffix. For example, an SSO authentication server located at sso-server.mydomain.com and a Private Label hostname of wiki.mydomain.com share the mydomain.com domain suffix. Use this domain for the SSO Cookie Domain in the Private Label configuration step. Update your login and logout destinations to include this iframe tag:
<iframe src="http://session.PRIVATE-LABEL-DOMAIN/session/clearsession?username=USERNAME" style="display:none;"></iframe>

Method 3: Log user out of all sessions

Synchronized logout is also available for Private Label customers who don't provide SSOsession and don't share a domain suffix between their Private Label site their authentication server. This option only works if the Requires Users Sign In setting is turned on to prevent guest users from accessing the Private Label site. In this case, Wikispaces will invalidate the session when the authentication system goes to the following URL (similar to Method 1 above):
http://session.PRIVATE-LABEL-DOMAIN/session/clearsession?username=USERNAME
This method is not recommended, since it will invalidate all of the user's Wikispaces sessions, including ones they may have open on other computers and other browsers. This won't impact usability, but it might cause unnecessary requests to your SSO server and Wikispaces. In addition, it can only be used to invalidate a user session, and not a guest session (which is why it requires you to disable guest access).

Login, Logout, and Join Pages

Your Private Label site will have links that prompt guests to join or log in, and that allow logged-in users to log out. With SSO, you can specify which URLs on your authentication system these links should direct the user to. You can usually use your existing log in and log out pages.

When the user or guest clicks the link, Wikispaces will add a goto GET parameter to the end of the URL. Once the visitor has successfully logged in, logged out, or joined, they will be directed back to the page they started from, and they will be logged in or out accordingly.

Configuring Your Private Label Site

Go to Site Administration > Settings > Authentication to configure your Private Label site with your authentication server details. You'll need to provide the following information:
SSO Server URL
URL of the above authentication redirect page
(You must provide a parameter that is set to %%RETURNTO%% so Wikispaces can replace it with the redirect base URL; for example: http://authentication-hostname.domain.com/sso-page.php?returnTo=%%RETURNTO%%)
Shared Secret
a shared secret between your authentication server and Wikispaces that will be used in generating the HMAC
(Never send the shared secret to Wikispaces in any of the SSO URLs. It is only used during the construction of the HMAC.)
SSO Join URL
URL to direct users to when they request to create a new account
SSO Login URL
URL to direct users to when they request to log in
SSO Logout URL
URL to direct users to when they request to log out
SSO Cookie Domain
a domain name, common between your authentication server and the Private Label site, that Wikispaces should set cookies under; only required if using Method 2 under "Synchronized Login and Logout"

Account Mapping

Usernames on Wikispaces must be between 3 and 32 characters long and contain only letters (a–z and A–Z); numbers (0–9); and/or the period (.), underscore (_), or hyphen (-) characters. If your usernames do not match the allowed criteria, they must be adjusted. For example, a username of "Mr Jones" might be translated to "Mr_Jones" before being sent to Wikispaces. This can be done through a persistent database mapping on your server, or more easily through a function that replaces invalid characters with valid ones.

Account Updates

When an account is transferred from your SSO authentication server to Wikispaces, the username and email address are stored in the Private Label site. During the SSO redirect, providing a different email address for a given username will trigger Wikispaces to update the email address for the user. If you send SSOguid during the SSO redirect, providing a different username for an existing SSOguid will trigger Wikispaces to update the username for that user.

This data will only be updated when the user accesses Wikispaces. If you want the changed data to be immediately reflected in Wikispaces, whether or not the user initiates a session with Wikispaces, you need to use the SOAP API to update the information on the Private Label site. Using the SOAP API to update information as it changes can be helpful for several reasons:
  1. A changed username will be immediately updated wherever it appears, including in editing history and wiki membership, even if the user hasn't logged in since their username was changed.
  2. Any email notifications will go to the user's new email address. (If you aren't using the API to update user details, Wikispaces may continue to send email to the old address.)
  3. Users who have been removed from your authentication database will immediately have their access to your site through SOAP and WebDAV disabled. (Since SOAP/WebDAV can be associated with different passwords, it may be possible for a deleted user to bypass the SSO check-in with your authentication server — unless you are using an API to keep all information current.)

Take the following steps to synchronize account information using the API:
  1. Set a password for your Site Administrator account on your Wikispaces Private Label site. Wikispaces cannot use your SSO account password, since that is never transferred. You need to enter a separate password for SOAP.
  2. Log in using the Site service login() function. You need to log in as a Site Administrator and use the password entered in the previous step.
  3. Retrieve the user with the User service getUser(session, username) function. Be sure to use the original username.
  4. When the username changes, call renameUser(session, oldusername, newusername).
  5. When the email address changes, call updateUser(session, user).
  6. When the user is deleted from your server, call deleteUser(session, userId).

Sample Code

PHP Code Sample
ASP.NET Code Sample
Java Code Sample (untested)


Still have questions? Contact Wikispaces support.