Plugins/Auth/Janrain Engage

The plugin is designed to provide a single sign on to Mahara using Janrain Engage (former RPX) service. Janrain provides a gateway for authentication to Mahara using identity from the providers like Google, Facebook, Twitter, Yahoo! and many others. The plugin functionality resembles behaviour of XMLRPC and SAMS plugins that already exist in Mahara, but different in a way that for security reason it does not support mapping to existing Mahara users. When the user logs in the first time, a new Mahara remote user account is created, all possible profile data available from identity provider is imported to the corresponding profile fields in Mahara.

This plugin was developed by LUNS Ltd. for Learning Arabia, who permitted to open-source it.

Installation

The plugin is currently hosted in mahara-contrib repositary (http://gitorious.org/mahara-contrib/janrain-auth). It includes the trees of mahara for both 1.3 and master, as it requires some changes in the core. For the fresh installation of stable Mahara version with embedded Janrain plugin you need to run:

 git clone git://gitorious.org/mahara-contrib/janrain-auth.git
 git checkout –b janrain-auth-1.3 origin/janrain-auth-1.3

then follow normal mahara installation procedures or just copy the config file from existing installation of Mahara 1.3 into htdocs directory. Once installation is done, you should be able to use the plugin stright away.

If you already have a running Mahara, just add another remote repositary and switch to required branch (e.g. to 1.3):

 git remote add janrain-auth git://gitorious.org/mahara-contrib/janrain-auth.git
 git fetch janrain-auth
 git checkout -b janrain-auth-1.3 janrain-auth/janrain-auth-1.3

If existing Mahara database will be used (as opposed to fresh installation), you will need an additional step to enable to the plugin. Go to Site Adminstration -> Extentions, find "rpx" in "Plugin type: auth" section and install it.

Usage

Before you will be able to use the plugin, you will first need to register on Janrain website and create a new application. In order to sign up for Janrain Engage go to http://www.janrain.com/products/enga...janrain-engage and choose required plan (it makes sense to start with a free basic account). You will be issued an API key for your application which you should keep in a secret. Please add your domain to the list of Token URL Domains (even if it is a localhost), it is important for its functioning. If someone will attempt to use your API key on the website different from the listed, Janrain will not reject authentication and you will be notified about such attempt.

To activate the plugin, open Site Administration -> Institutions in Mahara, then choose a desired one and click "Edit". In the dropdown "Authentication plugin" menu choose RPX and click "Add".

The plugin can be used with only one institution at the time. Mahara will not let you using this plugin for any other institutuion, once it is in use by one of them. This is done to avoid conflicts. All newly created remote users will automatically be the members of this institution.

In the popped-up Adminster Authorities window you need to specify an API key associated with your Janrain Engage application . You can find in the Dashboard of your application on Janrain website.

Paste the key in the API key field:

The next configuration parameter is Widget Style that defines how the Janrain sign in interface will look like. It has two modes: an overlay mode in which case you will have a link just below the login box:

by clicking on it the Janrain interface will pop up to proceed with login:

the second Widget Style mode makes Janrain interface embedded to the page as an iframe.

Update user details tickbox ensures that the profile fields will be imported from the identity provider each time user logs in. The updated profile fileds will be locked from user editing.

When you click "Submit", the API key verification will be performed, if something goes wrong, you will be notified. If you open your RPX instance settings again, it will contain useful links to your dashboard and identity providers configuration. The latter one allows you to choose which providers will be displayed in Janrain sign in interface.

Now you can use the plugin for logging to your Mahara using accounts on other websites.

User data importing notes

When the user logs in the first time, all available data from content provider is being imported to the profile (at the moment it is restricted to the data available for free Janrain account). This data is imported to Mahara's required fields and additional profile fields. For more technical details about the imported fields, see Janrain documetation.

Required fields

If any of these fields will be absent (e.g. Twitter does not provide email), user will be prompted to enter them manually on the first login.

Janrain field	Mahara field	Notes
name.familyName	lastname
name.givenName	firstname
email  verifiedEmail	email	verified email is used if available

Other profile fields

Janrain field	Mahara field	Notes
name.formatted  displayName	prefferedname	name.formatted is used if available
url	personalwebsite
address.locality	town
address.region	city
address.country	country
address.formatted	address
photo		Getting imported as user profile picture

If updating user details is enabled in the auth instance settings, all possible data will imported on every login and changing these profile fields will be disabled for user (they will need to update them on identity provider website to change them in Mahara).