New with uPortal 4.1

As of version 4.1, uPortal now supports Tenants. A tenant is a campus, professional school, or department in your community that will receive a "portal-within-a-portal" experience complete with custom logo, custom colors, and some custom content.

uPortal 4.3

uPortal 4.3 has tenancy included and enabled by default in the quickstart data set.

Default Tenancy Behavior

The default tenancy implementation creates a local tenant admin account with a default password of 'admin'. The configuration of the 'tenantOperationsListeners' in uportal-war/src/main/resources/properties/contexts/servicesContext.xml will attempt to send a 'password reset' email to the administrator's email address entered in the Add Tenant page. This will fail silently if email is not configured. If you choose to use local tenant admin accounts, you should remove the default password from the tenant template files and configure uPortal to be able to send emails.

Recommended Tenancy Configuration Process

Perform the following recommended steps for configuring multi-tenancy:

Adjust the authentication approach for your situation

By default, tenant admins have a local account in the portal. Users must have a user attribute (tenantOrg by default) matching a value configured in the Add Tenant form. If your tenant users are authenticating via Shibboleth or obtaining their attribute values via LDAP, you will need to adjust the tenant templates sample to use the attribute your identity system provides.

Configure email if needed

See email section lower in page

Create copies of the tenant template sample files and modify to suit your needs

There are templates that are processed using data values entered in the Add Tenant form to create and import the entities needed for tenancy. The tenant templates sample files are in uportal-war/src/main/resources/org/jasig/portal/tenants/data/sample. Copy these files to src/main/resources/tenantTemplates and modify them to suit your needs. Also change the property org.jasig.portal.tenants.TemplateDataTenantOperationsListener.templateLocation to point to the location you specified; e.g.

portal.properties

 org.jasig.portal.tenants.TemplateDataTenantOperationsListener.templateLocation=classpath:tenantTemplates/**/*.xml

uPortal 4.2

In an effort to modify some behavior that affects tenancy, I decided to create a brand new instance of uPortal from github as my starting point. A clean install by default will not work correctly, so I made several changes to the default uPortal to get things to work.

Environment

Mac OSX 10.9 Mavericks
Java 1.7.0_45
Maven 3.0.5
Apache Tomcat 7.0.53
uPortal 4.1.0-SNAPSHOT (downloaded from github.com/Jasig)

The Maven dependency is important to the installation instructions, but the others are just in case you are running a different environment and have different results.

Initial setup

I followed the standard uPortal download and installation instructions for Tomcat and to build uPortal - Installing uPortal but had an error.

[artifact:mvn] TypeError: can't convert String into Array
[artifact:mvn]        + at org/jruby/RubyArray.java:2963
[artifact:mvn]   (root) at <script>:5
[artifact:mvn] org.jruby.embed.EvalFailedException: (TypeError) can't convert String into Array

Sass Maven Plugin Incompatibility

This is an incompatibility in the Sass Maven plugin, version 1.1.1. To fix it, you need to:

download the head version of the Sass Maven plugin from github.com/Jasig. As of this time, it is version 1.1.2-SNAPSHOT
build it locally with `mvn clean install`.
within uPortal, modify uPortal-war/pom.xml and change the version of sass-maven-plugin from 1.1.1 to 1.1.2-SNAPSHOT.
Rebuild uPortal. I do `ant initportal` to rebuild everything.

uPortal should build successfully now and you can login as admin.

This is where the dependency on Maven comes in. Sass maven plugin will not compile by default on Maven 3.1. You will get errors that will require additional research and effort to resolve. If you build the plugin with Maven 3.0.x, you shouldn't have any build issues.

You only need to rebuild the Sass maven plugin if you get the error above. I would expect at some point, we'll release sass-maven-plugin v1.1.2 and include that change into the pom file. Then these instructions will be moot.

Tenancy and PAGS

Tenancy requires the database-backed PAGS implementation. With uPortal 4.1 you may need to modify uportal-war/src/main/resources/properties/groups/compositeGroupServices.xml for Tenancy to work. For uPortal 4.2 the correct PAGS implementation is chosen by default.

There are two services named "pags". The XML-based one should be commented out and the database-backed one should be uncommented.

Required for Tenancy to work - USE THIS ONE

  <service>
    <name>pags</name>
    <service_factory>org.jasig.portal.groups.ReferenceIndividualGroupServiceFactory</service_factory>
    <entity_store_factory>org.jasig.portal.groups.pags.dao.EntityPersonAttributesEntityStoreFactory</entity_store_factory>
    <group_store_factory>org.jasig.portal.groups.pags.dao.EntityPersonAttributesGroupStoreFactory</group_store_factory>
    <entity_searcher_factory>org.jasig.portal.groups.pags.dao.EntityPersonAttributesEntitySearcherFactory</entity_searcher_factory>
    <internally_managed>false</internally_managed>
    <caching_enabled>true</caching_enabled>
  </service>

Enable EMail services on localhost

One of the services that Tenancy provides is to create a new user when a new Tenant is created. As part of creating this new user, uPortal will automatically send an email to that user, asking them to reset their password. By default this will fail, since no email services have been defined. I made the following changes to configure email for my local uPortal instance.

uportal-war/src/main/resources/properties/contexts/userContext.xml

    <bean id="passwordResetMailSender" class="org.springframework.mail.javamail.JavaMailSenderImpl">
        <property name="host" value="${org.jasig.portal.email.host:localhost}" />
        <property name="port" value="${org.jasig.portal.email.port:25}" />
        <property name="protocol" value="${org.jasig.portal.email.protocol:smtp}" />
        <property name="username" value="${environment.build.uportal.email.username}" />
        <property name="password" value="${environment.build.uportal.email.password}" />        
    </bean>

add the "username" and "password" properties, so that you can successfully authenticate to your email server

portal-war/src/main/resources/properties/portal.properties b/uportal-war/src/main/resources/properties/portal.properties

org.jasig.portal.email.host=${environment.build.uportal.email.host}
org.jasig.portal.email.port=${environment.build.uportal.email.port}
org.jasig.portal.email.protocol=${environment.build.uportal.email.protocol}
environment.build.uportal.email.username=<authenticated email user id>
environment.build.uportal.email.password=<authenticated email user password>

The top three lines are initially commented, you need to uncomment them. The last two lines are new lines that you need to add. You'll need an email uid and pwd if your email server requires authentication to send email.

uPortal/build.properties

environment.build.uportal.email.host=<mail server dns name>
environment.build.uportal.email.port=<mail server port>
environment.build.uportal.email.protocol=<mail server protocol>

Add these three lines for your email server. You'll need to get the real values from your email server administrator.