Shibboleth

Shibboleth Overview

Skipping a lot of detail here is an overview of the steps involved with using Shibboleth with uPortal. The uPortal configuration step is very small and generally trivial. In the list below steps 1 through 4 are covered by the Shibboleth Documentation. Step 5 is the only uPortal specific part and described below.

  1. Install and configure Shibboleth SP - configure SP to pass uid via REMOTE_USER to get it working faster.
  2. Install and configure uPortal - get it running on its own without Shib.
  3. Install and configure Apache httpd server.  Configure httpd with Shib and validate that Shib can protect resource AND pass attributes.  Also configure httpd to work with tomcat (mod_jk).
  4. Configure httpd server to protect uri '/uPortal/Login' 
  5. Configure uPortal authentication - use the RemoteUserSecurityContext for (Shib) authentication

For Shibboleth IdP or httpd server related questions please contact the shibboleth-users list.

Shibbolizing uPortal

Step 1 - Security Context

Shibboleth only configuration

Configure uPortal to get the username from the REMOTE_USER header. In uportal-war/src/main/resources/properties/security.properties add the property:

root.remote=org.jasig.portal.security.provider.RemoteUserSecurityContextFactory

To ensure the Shibbolized uPortal instance has no chance of using anything but Shibboleth for authN, comment out root and other existing root.* and use RemoteUserSecurityContextFactory as root like:

## This is the factory that supplies the concrete authentication class
#root=org.jasig.portal.security.provider.UnionSecurityContextFactory
#root.cas=org.jasig.portal.security.provider.cas.CasFilteredSecurityContextFactory
#root.simple=org.jasig.portal.security.provider.SimpleSecurityContextFactory
root=org.jasig.portal.security.provider.RemoteUserSecurityContextFactory

Multiple Authentication Systems configuration

Configure uPortal to get the username from the REMOTE_USER header. In uportal-war/src/main/resources/properties/security.properties add the property

root=org.jasig.portal.security.provider.RemoteUserSecurityContextFactory

To enable multiple authentication systems use UnionSecurityContextFactory as root. With multiple authentication systems, uPortal will attempt to authenticate the user to all systems until one is successful.

## This is the factory that supplies the concrete authentication class
root=org.jasig.portal.security.provider.UnionSecurityContextFactory
root.cas=org.jasig.portal.security.provider.cas.CasFilteredSecurityContextFactory
root.simple=org.jasig.portal.security.provider.SimpleSecurityContextFactory
root.remote=org.jasig.portal.security.provider.RemoteUserSecurityContextFactory

Step 2 - Person Manager

Configure uPortal to create user's on demand based on the REMOTE_USER header.

In uportal-war/src/main/resources/properties/contexts/userContext.xml replace SimplePersonManager bean

<bean id="personManager" class="org.jasig.portal.security.provider.SimplePersonManager" />

with the RemoteUserPersonManager bean. Note that the bean id stays the same.

<bean id="personManager" class="org.jasig.portal.security.provider.RemoteUserPersonManager" />

Step 3 - Person Attributes

Don't Duplicate These Beans!

For recent uPortal releases, most of the following XML is already in place. You will need to add attribute mappings to the requestAttributeSourceFilter bean to access the user attributes emitted from Shibboleth in the AuthN process.

Configure uPortal to populate user's attributes based on headers from Shibboleth.

Apereo Person Directory

The minimum required version of Apereo Person Directory is 1.5.0-RC8. Recent uPortal releases meet this requirement, but if your portal is a few versions behind you should check the value of the person-directory.version property in the root pom.xml file.

In uportal-war/src/main/resources/properties/contexts/personDirectoryContext.xml add the following beans

<!--
 | Servlet filter that creates an attribute for the serverName
 +-->
<bean id="requestAttributeSourceFilter" class="org.jasig.services.persondir.support.web.RequestAttributeSourceFilter">
    <property name="additionalDescriptors" ref="requestAdditionalDescriptors" />
    <property name="usernameAttribute" value="remoteUser" />
    <property name="remoteUserAttribute" value="remoteUser" />
    <property name="serverNameAttribute" value="serverName" />
    <property name="processingPosition" value="BOTH" />
    <property name="headerAttributeMapping">
        <map>
            <!-- MODIFY THESE MAPPINGS TO EXPOSE HEADERS FROM SHIB AS USER ATTRIBUTES -->
            <entry key="cn">
                <list>
                    <value>cn</value>
                    <value>displayName</value>
                </list>
            </entry>
            <entry key="givenName" value="givenName" />
        </map>
    </property>
</bean>

<!--
 | Session-scoped descriptors object. One of these will exist for each user in their session. It will store the
 | attributes from the reques set by the requestAttributeSourceFilter
 +-->
<bean id="requestAdditionalDescriptors" class="org.jasig.services.persondir.support.MediatingAdditionalDescriptors">
    <property name="delegateDescriptors">
        <list>
            <bean class="org.jasig.services.persondir.support.AdditionalDescriptors" scope="globalSession">
                <aop:scoped-proxy />
            </bean>
            <bean class="org.jasig.services.persondir.support.AdditionalDescriptors" scope="request">
                <aop:scoped-proxy />
            </bean>
        </list>
    </property>
</bean>

In uportal-war/src/main/webapp/WEB-INF/web.xml add the following servlet filter

<filter>
    <filter-name>requestAttributeSourceFilter</filter-name>
    <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>

[...]
<filter-mapping>
    <filter-name>requestAttributeSourceFilter</filter-name>
    <url-pattern>/Login</url-pattern>
</filter-mapping>

This step is only needed if you're using the uPortal rendered login link.

Modify uportal-war/src/main/resources/layout/theme/universality/components.xsl to change the Login and Logout UIs to something appropriate to your institution.

Optional, to delete CAS login, remove:

<div id="portalCASLogin" class="fl-widget-content">

<a id="portalCASLoginLink" class="button" href="{$EXTERNAL_LOGIN_URL}" title=
"{upMsg:getMessage('sign.in.via.cas', $USER_LANG)}">
<span><xsl:value-of select="upMsg:getMessage('sign.in', $USER_LANG)"/><!--&#160;<span class="via-cas"><xsl:value-of select="upMsg:getMessage('with.cas',$USER_LANG)"/></span>--></span>
</a>


<p>
<xsl:value-of select="upMsg:getMessage('new.user.question', $USER_LANG)"/>&#160;
<a id="portalCASLoginNewLink" href="{$CAS_NEW_USER_URL}" title="{upMsg:getMessage('create.new.portal.account', $USER_LANG)}">
<xsl:value-of select="upMsg:getMessage('new.user', $USER_LANG)"/>
</a>.
</p>


</div>

 

Shibboleth only configuration

With Shibboleth configured as the only authentication system, you only need the user to click on '/uPortal/Login' through any method you prefer, e.g. url link, button, image, etc.

Multiple Authentication Systems configuration

With multiple authentication systems, you will need to design a login template that will allow users to select a specific authentication system to login. To initiate a Shibboleth session, you will need to construct a Shibboleth WAYF login url, for example the format for our school's WAYF is - https://host.school.edu/Shibboleth.sso/WAYF/shibboleth.school.edu?target=http%3A%2F%2Fhost.school.edu%2FuPortal%2FLogin

Another example repurposing the default CAS login and replacing it with a Shibboleth login.

<div id="portalCASLogin" class="fl-widget-content">

<a id="portalCASLoginLink" class="button" href="https://host.school.edu/Shibboleth.sso/WAYF/shibboleth.school.edu?target=http%3A%2F%2Fhost.school.edu%2FuPortal%2FLogin" title="Shibboleth Login">
<span>USC Login</span>
</a>

</div>

Having problems with these instructions?

Please send us feedback at uportal-user@lists.ja-sig.org

Add Feedback content box here.....