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 a simple way to have your Wikispaces Private Label site authenticate against the same authentication server. Contact Wikispaces support if 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 exist in your Private Label site, and (2) the database of user accounts than already exist on your Moodle server. I f a user logs in before you have turned off your Wikispaces Password database and/or migrate 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 that you can reasonably rename by hand, send us a request and we'll rename them for you.
User names on Wikispaces must be between 3 and 32 characters long and contain only letter ( a-z and A-Z); numbers (0-9); and/or period (.), underscore (_) or hyphen (-) characters. If your usernames do not match the allowed criteria, the 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 invariable 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 a 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 the 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 to get ready, dowload the plugin and read the documentation (INSTALL.txt):
FILE ( moodle_auth_wikispaces18-1.8.zip)
FILE (Moodle_auth_wikispaces 18-1.8.tgz)
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, Wikispaces will query the SSO server when the user first logs in, and then cache the results. 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 the 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 your are using and 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
- Once the plugin has been installed, log into Moodle and go to Administrator>Users>Authentication>Manage Authentication.
- Find the Wikispaces SSO Integration item and click on its Settings link. If you can 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.
- Enter a share secret. A share 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 your pasword. Use lower characters letters, capital letters, numbers, and special characters ( excluding foreing characters or the backslash). NEVER send your shared secret through instant messaging or email.
- Enter your Private Label site's domain name.
- If your private label sites 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."
- Go back to Administrator> Users> Authentication, and enable the plugin by clicking on the closed eye.
- Log into your Private Label site as an administrator.
- 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 accounts to match the Moodle account name.
- Go to Site Administration> Settings>Authentication.
- Below Add New Authentication Source, select Moodle, then click the Add Authentication Source button.
- Fill out the form:
- Moodle Pluging URL: Your Moodle URL followed by "auth/wikispaces/sso.php?returnTo=%%RETURNTO%%. ( For example, http://moodle.wn.livewiki.com/auth/wikispaces/sso.php?return To=%%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 uncheck. Read more above
7. Go back to Site Administration>Settings> Authentication and change the status of Wikispaces Password to Disabled.
If some users already had active accounts with Wikispaces Passwords, you will probably want to migrate those users yo the Moodle SSO authentication source:
- Log into your Private Label site as an administrator.
- Go to Site Administration>Settings>Authentication.
- Click on the number of users in the Wikispaces Password row.
- 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 pages, checking the users you wish to migrate.
- 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.