Moodle SSO plugin


Moodle Plugin


Overview

The instructions below will walk you through adding a plugin to your Moodle server that will let your Private Label site integrate with your Moodle user database. Be sure to read the documentation through completely before you start. If your Moodle server already authenticates against your authentication server, this is a simple way to have your Wikispaces Private Label site authenticate against the same authentication server. Contact Wikispaces support if you run into any trouble or if you have any questions.

Before You Get Started

Map your users

Once your Moodle 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 Moodle server. If a user logs in before you have turned off your Wikispaces Password database and/or migrated your users to Moodle, 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 their Moodle usernames before you turn on SSO. If this is a larger list than you can reasonably rename by hand, send us a request 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 Moodle server's clock

As a security precaution, the SSO process requires the Moodle server to generate exact timestamps for the precise time. The easiest way to ensure accurate time is to synchronize your Moodle 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." Check with your IT department if you are unsure whether this is taking place.

Consider a custom domain

If your Private Label site and Moodle 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.

Get the plugin

When you’re ready to get started, download the plugin and read the documentation (INSTALL.txt):



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

What to Do

The plugin should be installed and configured by a user who has administrator accounts in both the Private Label site and Moodle. As noted above, these accounts must share a username or the user will be locked out of the Private label site.

This plugin was built for use with Moodle 1.9, but should also work for 2.0. If you are using an older version of Moodle, please Contact Wikispaces support.

Install the plugin

Copy the wikispaces folder (located in the plugin archive at moodle/auth/wikispaces) into your moodle/auth/ directory.

Configure the plugin

  1. Once the plugin has been installed, log into Moodle and go to Administration > Users > Authentication > Manage Authentication.
  2. Find the Wikispaces SSO Integration item and click on its Settings link. If you can't find the Wikispaces SSO Integration item, the plugin may not have been installed correctly. Contact the person who installed the plugin to see if they can resolve this. If they can’t resolve the problem, ask them to contact Wikispaces support.
  3. Enter a shared secret. A shared secret is not a password: you won’t have to remember it very long, and the only other time you’ll have to retype it will be during the configuration of your Private Label site. Try to make it longer and more complicated than you would make a password. Use lowercase letters, capital letters, numbers, and special characters (excluding foreign characters or the backslash). NEVER send your shared secret through instant messaging or email.
  4. Enter your Private Label site's domain name.
  5. If your Private Label site shares a domain suffix with your Moodle server, check the Shared Domain box. What this means and why it is valuable is explained above in "Consider a custom domain."
  6. Go back to Administration > Users > Authentication, and enable the plugin by clicking on the closed eye.

Configure your Private Label site

  1. Log into your Private Label site as an administrator.
  2. Make sure that you are logged into Moodle with the account that you will be associating with your Wikispaces site administrator account. If the names of these accounts are different, you will be given the option of renaming your Wikispaces account to match the Moodle account name.
  3. Go to Site Administration > Settings > Authentication.
  4. Below Add New Authentication Source, select Moodle, then click the Add Authentication Source button.
  5. Fill out the form:
    • Moodle Plugin URL: Your Moodle URL followed by “auth/wikispaces/sso.php?returnTo=%%RETURNTO%%”. (For example, http://moodle.wn.livewiki.com/auth/wikispaces/sso.php?returnTo=%%RETURNTO%% )
    • Shared Secret: the shared secret that you used for step 3 of configuring the plugin. You can cut and paste the shared secret from the Wikispaces plugin's settings page on Moodle. Once again, make sure you never send the shared secret in an instant message or email.
    • SSO Cookie Domain: Domain suffix in common between your Private Label site and your Moodle site. (Optional; you can find out why this is valuable above.)
    • Disconnected Mode: You will probably want to leave this box unchecked. Read more above.
  6. Hit the Test Moodle Settings button.
  7. Go back to Site Administration > Settings > Authentication and change the status of Wikispaces Password to Disabled.

Migrate Users

If some users already had active accounts with Wikispaces Passwords, you will probably want to migrate those users to the Moodle SSO authentication source:
  1. Log into your Private Label site as an administrator.
  2. Go to Site Administration > Settings > Authentication.
  3. Click on the number of users in the Wikispaces Password row.
  4. Check the boxes for the users you would like to migrate. If you want to select the whole page of users, check the box in the title row. If you would like to select users on multiple pages, just move from page to page, checking the users you wish to migrate.
  5. When you’ve selected all the users you want to migrate, click the Set Authentication button, and choose the correct authentication source from the dropdown list.


Still have questions? Contact Wikispaces support.