Sakai Connector Portlet - Configuration and Installation

Owned by Steve Swinsburg
Last updated: Feb 21, 2013Version comment
4 min read

Configuration and Installation

Because this portlet integrates uPortal and Sakai, there is configuration that must be performed on both. Note also, that with some minor modifications, this portlet also works on Liferay. See the section below.

Configuring Sakai

1. Install Basic LTI

You must be either running Sakai 2.7+ (which comes with Basic LTI support) or have installed Basic LTI into your Sakai instance. Basic LTI will happily run on earlier versions of Sakai and you can find packaged WAR's here: http://source.sakaiproject.org/maven2/org/sakaiproject/basiclti/imsblti/ or source tags here: https://source.sakaiproject.org/svn/basiclti/tags/ 

2. Setup the Basic LTI provider

You now need to configure the Sakai Basic LTI provider. You should read the documentation here: https://source.sakaiproject.org/svn/basiclti/trunk/basiclti-docs/resources/docs/

There are security implications if you improperly configure Basic LTI. But it's easy to configure so read on.

First, you need to enable Basic LTI itself. In sakai.properties:

basiclti.provider.enabled=true

You then need to set the list of Sakai tools that are allowed to be exposed via Basic LTI:

basiclti.provider.allowedtools=sakai.resources:sakai.rwiki:sakai.profile2

Finally, you need to setup a key and secret. There is a special syntax for this, basiclti.provider.key.secret=secret. Here's an example:

basiclti.provider.my.school.edu.au.secret=abc123

You can setup multiples so that multiple consumers can connect to Sakai:

basiclti.provider.my.school.edu.au.secret=abc123
basiclti.provider.some.other.school.edu.au.secret=def456
3. Install some extra web services (Only required for Sakai 2.7 and lower)

A couple of extra web services are required for the integration to work. Grab the contents of the additional web services and add them to: $SAKAI-SRC/webservices/axis/src/webapp/SakaiScript.jws

Note that this has been updated for the 1.1 release so if you are upgrading, you need to review this.

3. Enable the web services

The Sakai Connector portlet needs to be able to connect to Sakai to retrieve configuration data, so the web services must be enabled in Sakai.

To enable them, in sakai.properties:

webservices.allowlogin=true

You also need to specify a comma separated list of IP addresses/hostnames that are allowed to connect. This can be a regex expression so the dots need to be escaped with backslashes:

webservices.allow=localhost,127\.0\.0\.1,192\.168\.[0-9.]+,domain\.somewhere\.ac\.uk,123\.45\.678\.90

For development you could use the following to allow unrestricted access however DO NOT USE THIS IN PRODUCTION:

webservices.allow = .*

You can optionally enable access logging:

webservices.log-allowed=true
webservices.log-denied=true
4. Enable clean pass through of credentials to Basic LTI

There is one final addition to sakai.properties that completes the configuration. Ordinarily, Basic LTI will prefix the incoming userId and siteId, and create a new user account and site. This limits the level of integration possible as many users will have existing sites and content they want to reuse outside of Sakai. You need to set the following property to allow the userId and siteId to passthrough without this prefixing occurring:

basiclti.provider.highly.trusted.consumers=my.school.edu.au

The my.school.edu.au needs to match the key in the section above, and also in the next section. You can have multiples too:

basiclti.provider.highly.trusted.consumers=my.school.edu.au:some.other.school.edu.au

Of course, this assumes that the username of users in both uPortal and Sakai are identical (e.g. jsmith26 in both systems).

5. Test.

Restart Sakai and navigate to http://your.sakai.server/imsblti/provider/. If you've set it up correctly, you should not get an error, but you will get a warning message: Invalid value for Basic LTI Launch. This is good! If you get any other error, go back through the documentation and your settings. Also check catalina.out for any clues.

Deploying the portlet

As of version 1.3, the CONFIG portlet mode is the primary method of configuring the portlet. No configuration is required prior to deploying the portlet. If you have the built WAR, you can simply drop it into uPortal tomcat/webapps, it is already configured with the Pluto Invoker.

If you build from source, run the following command:

mvn clean install -Ddeploy -Dmaven.tomcat.home=/path/to/your/tomcat

Start uPortal and open the Portlet Manager so that we can setup the portlet.

Configuring the portlet

As of version 1.3, the portlet is configured via the CONFIG mode. Register the portlet via the 'Portlet' type, follow through the screens as per a normal portlet, and then you will be prompted with a screen as below:

Each of these settings come with explanatory text to guide you filling them in. Enter in the details for your environment and click Save Configuration.

You can now add the portlet to your page and embed tools for your Sakai environment into your portal.

Optional configuration

There is also an optional setting in portlet.xml you may need to modify if your personDirectoryContext.xml is configured to store the username value in a different field. The value of the init-param below must match the 'name' value of the Username attribute below so that the username is mapped correctly in different portal environments, or if your environment has this setup differently. In most cases this can be left as-is.

<init-param>
  <name>portal.attribute.mapping.username</name>
  <value>username</value>
</init-param>

<user-attribute>
  <name>username</name>
  <description>Username attribute</description>
</user-attribute>

Now that you've configured everything you should be able to deploy your portlet.

Build/deploy the portlet

If you have the built WAR, you can simply drop it into uPortal tomcat/webapps, it is already configured with the Pluto Invoker.

If you build from source, run the following command:

mvn clean install -Ddeploy -Dmaven.tomcat.home=/path/to/your/tomcat

Now simply register the portlet in uPortal, add it to your page and start configuring it.

Other requirements

  • You need to have an account in both uPortal and Sakai with an identical username, (e.g. jsmith26 in both systems).
  • In the Portlet Manager, you should set Disable Dynamic Title to false, so users can change the title of their portlet.

Modifications for Liferay

The following modifications are required to get this portlet running in Liferay. This is from a user contributed experience.

1. You must be running version 1.1+ of the portlet.

2. If you have the built WAR, skip this step.

Build the portlet normally. This will set up the portlet web.xml for Pluto. 

3. In web.xml, replace:

<servlet-class>org.apache.pluto.core.PortletServlet</servlet-class>

with:

<servlet-class>com.liferay.portal.kernel.servlet.PortletServlet</servlet-class>

4. In portlet.xml, replace:

<user-attribute>
  <description>Username</description>
  <name>username</name>
</user-attribute>

with:

<user-attribute>
  <description>Username</description>
  <name>user.name.nickName</name>
</user-attribute>

5. In portlet.xml, replace:

<init-param>
  <name>portal.attribute.mapping.username</name>
  <value>username</value>
</init-param>

with:

<init-param>
  <name>portal.attribute.mapping.username</name>
  <value>user.name.nickName</value>
</init-param>