Google Apps Integration
Introduction
Moodlerooms and Google have worked together to build a state of the art integration. The 1.0 version of the integration provides:
- Automatic creation of users in Google Apps (Google Docs™, Google Calendar™, and Gmail™) when they are created in Moodle
- Automatic log in to Google Apps when a user logs in to Moodle
- A Gmail block in Moodle that displays latest Gmail messages on the Moodle Front Page
- A Google Apps block on the Moodle Front Page displays links to Google Start Page, Google Docs, Google Calendar and Gmail
- A Moodle app on the Google Apps Start PageGoogle Apps can integrates with Moodle v1.9 and above. There is a contributed code block that can be added to Moodle and a widget which can be added to Google. It will allow for a single sign-on for users from Moodle to Google.
Moodle 2.0 support now available
The New Zealand Moodle in Schools project and Catalyst IT have collaborated to port this functionality to Moodle 2.0 and is available from the Catalyst git repository in the feature-20-googleapps branch.
Integration Setup
There are a few steps involved with setting up the Google Apps Education Edition Integration. This setup should be configured by a technically knowledgeable Moodle administrator.
- Set up Moodle's Authentication
- Set up Google's Authentication
- Add and configure the Gmail and Google Apps blocks
- Add and setup the User Sync block (optional; for those who do not have a Google account creation/management process)
Requirements
The following must be installed:
- auth/gsaml
- blocks/gmail
- blocks/gdata
- blocks/gaccess
- lib/zend
Generating Private Key and SSL signed Certificate
Generate the private key:
sudo openssl genrsa -out googleappsidp.key 1024
RSA encrypt the key for use with Google Apps:
sudo openssl rsa -in googleappsidp.key -out googleappsidp.pem
Create the .csr fill to generate the certificate from:
sudo openssl req -new -key googleappsidp.key -out googleappsidp.csr
Encrypt the key in x509 format using the key:
sudo openssl x509 -req -days 9999 -in googleappsidp.csr -signkey googleappsidp.key -out googleappsidp.crt
Set Up Moodle's Authentication
- Log in to Moodle as an Administrator
- Click Notifications to update block tables
- Enable the Google Authentication plug-in from the Manage Plug-ins admin page
- In the Site Admin menu, select "Plugins-> Authentications -> GOOGLE SAML AUTHENTICATION"
- Enter your Google partner page domain name.
- Past RSA keys content into RSA key text area, Past SSL x509 content in SSL signing Certificate textarea
- Click Save Changes
Set Up Google's Authentication
- In a new browser window, log in to the Google Apps Control Panel page as an admin. To access this page, you can use this URL -- just change the end to have your partner page domain information: https://www.google.com/a/yourpartnerpagedomainname.com.
- Click the Advanced tools tab
- Click the Set up single sign-on (SSO) link next to Authentication
- Select the checkbox to "Enable Single Sign-on"
- Enter this URL into the Sign-in page URL text field:
- http://<moodle site url>/login/index.php
- Enter this URL into the Sign-out page URL text field:
- http://<moodle site url>/login/logout.php
- Enter this URL into the Change password URL text field:
- http://<moodle site url>/login/change_password.php
- Generate and upload a verification certificate to Google (X.509 certificate containing the public key)
- Click Save Changes
- Click the Dashboard tab
- This displays existing users as well as a message that says "You can create up to ### user accounts for this domain." If you are using the Google User Sync block for account management, this number must match or be larger than the number of accounts you plan on creating. Request more accounts if you need them by clicking the request more link on this page.
- Click the Domain settings tab
- Click the User settings link. Check the box to "Enable provisioning API" (otherwise users will NOT be updated) (Domain settings > User settings > Enable provisioning API must be checked.)
- Click Save Changes
- Next you will add and configure the blocks as well as the Moodle-Google Gadget. See the "Google Blocks Configuration" and "Moodle-Google Gadget Setup" tutorials for more information.
Things to Consider:
- The Gmail feed might not be found and display an error. Troubleshooting tips include:
- Turn on debugging and the diagnostics page will perform a basic check on the Gmail feed.
- If you are using the Google User Sync block, check to see if an admin or guest user has been added to the sync. If so, remove them.
- If you are using the Google User Sync block, be sure your Google user settings are set to allow the number users you are adding to the sync in Moodle. If the number of Moodle users is larger than the number set in Google, then those accounts will not be created or synced (ie, if Google is set to 1000 users and Moodle has 1500, 500 accounts will fail to be created or synced).
- The location of the Google Authentication Plug-in in the Authentication order is important. Currently, it needs to override a user's auth type when a Moodle user changes passwords. This behavior may affect M-Net users. A solution for this problem has not yet been found.
- Do not add a user to the sync if their user name has been deleted from Google. You need to wait five days before adding them to the User Sync.
- See the Diagnostics Page in the gsaml settings for more information about your setup.
Gmail Block Settings
- OAuth Consumer Secret
- This is a string that Google apps generates and is used as a shared secret.
- Google Apps Domain
- your google apps partner domain.
- Unread Message Count
- Here, you can specify the number of unread messages to display in the Gmail block. Leave as zero for no limit.
- New Window Links
- By default, the Gmail links open in a new browser window or tab. You can change this to open in the same window by unchecking this setting.
- Show first name and Show last name
- By default, the author's first and last name is displayed next to the e-mail title -- uncheck these settings to hide.
To configure the Gmail block:
- In Site Admin, go to Modules > Blocks > Manage Blocks
- Define the OAuth consumer secret. To find your consumer secret:
- Log in to http://www.google.com/a/YOURDOMAIN with your Google Admin account
- Click Advanced Tools
- Click Manage OAuth Access
- Copy the OAuth consumer secret from this screen and paste it into the Moodle text box
- Enter your Google apps domain
- Save changes
Google Apps Block Settings
- New Window Links
- By default, the Google Apps links open in a new browser window or tab. You can change this to open in the same window by unchecking this setting.
User Sync Block Settings
- Google Apps username
- This is a username in Google apps that has administrative permissions. This user should not be in Moodle and not part of the user sync. This user is used to create, delete and update Google accounts.
- Google Apps password
- password for the google user to sync with.
- Google Apps domain
- Your partner domain.
- Use Google Apps e-mail
- This is unchecked by default. Checking this box will cause the e-mail address in the Moodle profile to be changed to the Gmail address.
- Enable events
- This is turned on by default, as this causes any change of Moodle profile information to be instantly updated in Google. Unchecking this setting will cause Moodle profile updates to only be changed in Google when the cron runs. This is preferable if you do not want the deletion of Moodle accounts to immediately delete Google accounts.
- Cron interval
- Enter how regularly (in minutes) you want the cron to run and sync Google and Moodle accounts. This is set to every 30 minutes by default.
- Cron expire
- When the synchronization runs, it locks the cron from being executed again until it has finished. This setting is used to determine when that lock has expired. Consider setting this to a high value, especially on first runs with a lot of users. By default, it is set to 24 hours.
Configuring the Google User Sync Block:
- Log in to Moodle as an administrator. You must also be an administrator in Google.
- Click the Add Blocks drop down and choose "Google User Sync."
- Click the Settings link in the Google User Sync block.
- Configure the settings according to your Google Partner page information. You will need to enter the Google administrator user name and password in addition to your Google Partner domain.
- Save changes
Confirming the configuration is working:
- Click the Status link in the Google User Sync block to confirm that the integration was successful.
- Go to Site Administration > Security > Site policies
- Check Password Policy and make sure the Set Password Length is set to "6 or greater" (Required for Google's password policy)
- if getting "Google Apps error: Unable to Connect to ssl://www.google.com:443. Error #110: Connection timed out" check 1) Server time is sync using NTP service, 2) force Server's www.google.com using HOSTS file, and setting to a fixing IP, using the least TTL in ping.
User Sync Status
The user sync status will tell you if the integration was successful or not. If there is an error here, it means one of your settings is wrong. Check to make sure the user name and password is correct,
Moodle-Google Gadget Setup
To set up the Moodle-Google gadget, you need to first set up and configure the Google Apps Education Edition Integration. To complete this process, you must be an admin for both the Moodle installation and the Google installation.
- Log in to the Google Control Panel as an admin. Use the link below, substituting your Google domain name for "mroomsdev.com"
- Click the Service Settings tab, then the Start Page link.
- Click Customize and Publish
- Click Select default content
- Click Refresh default content below to make the Add stuff link appear
- Click Add stuff
- Click Add by URL
- Paste the following URL, substituting your Moodle domain name for "test.mroomsdev.com"
- http://<moodle site url>/auth/gsaml/moodlegadget.php
- Click Add
- Click close
- Click Back to Homepage
- You should see the Moodle Gadget appear
- Lastly, be sure to click the Publish link in the furthest upper right-hand corner.
Things to Consider
The Moodle-Google Gadget is a beta prototype. In the future, it may be much more useful. Currently, there is a known bug regarding the Gadget not updating immediately upon install. Developers are looking into it.
Gmail Block
Description
The Gmail block displays an inbox link, along with a list of a customizable number of unread e-mails. This list contains the subject of the e-mail as well as the name of the sender. Each subject is a link, which you can hover over with your mouse to see a summary of the e-mail.
Granting Access
The first time a user uses the Gmail block they will be required to grant the block access to view their Gmail account. This is required for the 3 legged OAuth connection.
To grant access perform the following steps:
- Click the Grant access link in the Gmail Block
- If Google authentication plugin is not configured then you will be asked to login to your site.
- Click the grant access button. (all of the black lines will be filled in with data about your email or site.
- Once you have granted access you will be shown a success screen an then returned to your Moodle site. You will not see a list of unread emails in your Gmail block.
Using Gmail block
To use the Gmail block
- Click the subject link of the e-mail you want to open. Click the Inbox link to go directly to your Gmail inbox.
- This opens the e-mail (or inbox) in a new browser window or tab.
- When you're done using Gmail, navigate back to your Moodle window. Unread messages will not update in your Moodle Gmail block until you log out and log back in.
Refresh Access
The Refresh Access Token Link can be used to renew a users access token when it expires or allows a user to deny access to an previously granted token. User's should seldom have to click this link to obtain a new access token from Google.
Technical Notes on the Gmail Block
- The Gmail block requires the rest of the Google-Moodle SSO system to be functional in order to operate properly.
- The system does not support Google's optional custom certificate authentication.
- If you are experiences SSO errors double check that your server time is in agreement with one of the internets many NTP servers. Your server and Google's systems must have proper time in order to process SSO requests properly.
2 legged OAuth is no longer supported by Google's Gmail atom feed and thus has been removed from the system.
It seems that two-legged OAuth is now supported again, and at least for the Moodle 2.x ports (at http://git.catalyst.net.nz/gw?p=moodle-r2.git;a=shortlog;h=refs/heads/feature-20-googleapps and https://github.com/piersharding/moodle-google) the Gmail feed will not work unless 'Allow access to all APIs' is enabled on the 'Manage OAuth key and secret' page, under 'Advanced tools' (see http://support.google.com/a/bin/answer.py?hl=en&answer=162105).
Regarding General Maintenance
The Gmail block contains a local copy of Mozilla's Certification Authorities list. Overtime the Authority certificates bundle may need to be updated. If the Gmail block returns an error regarding SSL you may need to look into this issue.
Google Apps Block
To use the Google Apps block:
- Click the link of the application you want to use. This will take you directly to it in a new browser window or tab. You can choose from:
- Gmail
- Calendar
- Docs
- When you're done using the Google App, navigate back to your Moodle window.
Logging Out of Google Apps
If you click the Sign out link from a Google App, you will be taken to a page confirming that you want to log out.
If you click Yes, it also logs out of Moodle as well and takes you back to the Moodle Front Page. Likewise, if you log out of Moodle, it will also log out of Google. This prevents you from logging out of one system and forgetting to log out of the other. This is especially useful when using a public or shared computer.
If you click No, you will be taken back to the Moodle Front Page.
Google User Sync
This block allows you to create and manage Google accounts from Moodle. When a Moodle user is added to the User Sync, their account is automatically created in Google. If their account is deleted in Moodle, it will also be deleted in Google.
Once the block has been configured by a technically knowledgeable Moodle administrator (see "Google User Sync Settings" tutorial), the actual management of users can be performed by anyone with Moodle administrator permissions.
==Adding to the User Sync
- Click the Add users to sync link
- Use the Moodle filter to locate the users you wish to add. Note: never add a guest user or the main administrator. This will break the syncing process.
- Select the boxes next to the user names you wish to add. Alternatively, you can click the Add all users button.
- Click Add users to sync
- The page will refresh and the users you just added will no longer appear.
Managing the User Sync
To view the users currently being synced and remove them, you can use the feature Users being synced.
- Click the Users being synced link.
- This displays a list of all the users being synced. You can manage which users are displayed by searching with the Moodle filter. You can also display more users per page by using the Page size drop down menu.
- There are two ways to remove users. You can use the Remove all users button, or you can select specific users and click Remove users from sync.
- The page will refresh, and the users will no longer appear in the Users being synced tab.
Moodle-Google Gadget
If you have a Gmail account, you should see a Google gadget that contains a link back to Moodle on your Google Start Page. If you don't see a link to Moodle on your Google Start Page, follow these directions to add the Moodle Gadget.
- Open your Start Page.
- Click the Add stuff link.
- Click the Add by URL link.
- Copy and paste this URL, but be sure to change "test.mroomsdev.com" to your Google Partner Page domain: http://test.mroomsdev.com/auth/gsaml/moodlegadget.php
- Click Add
- A warning message will pop up. Click OK.
- A message should appear below the URL field that says it was added.
- Click Back to Homepage to return to your Start Page and verify the link is there.
Tips and tricks
- Once the Moodle accounts are disabled, so are the Google accounts. However one could choose to grant access via Google to continue collaboration after a course is completed.
See also
- Modules and Plugin page: Modules and Plugin
- Using Moodle Discusion: Google Apps integration forum
- Download: Google_1.0_for_Moodle_1.9 on Moodlerooms.com no login required
- Google gadgets- code to put into a Moodle HTML block
- Gradebook integration for Google Fusion Tables using OAuth interface for Moodle 2.x
- An SSO integration between Moodle and Google