Shibboleth and Liferay Part 1: Installing Shibboleth

So here we go... A topic everybody seems to search on and nobody has a truly complete source of information for. Plenty of guides exist out there for setting up Apache, installing Shibboleth, setting up mod_proxy...

Some of those sites are great, some of them not so much... But the problem is they often assume a LOT about your knowledge of the subject or how your server is configured, and leave out many things important to new people.

That's the sort of problem that led to this blog. So often, blog posts, articles and forum posts are more about showing off than about actually helping people out. Figuring this thing out has been downright PAINFUL, and I want to spare the next guy by sharing lessons learned.

Oh, and many of the links out there referencing the Shibboleth Wiki are broken. They still link to a site that gives you a new URL for the Shibboleth Wiki, but you lose the specific item you were trying to read.

The project we'll be doing here will be an effort to set up Liferay to be protected by Shibboleth as a Web SSO service provider. This will be a series of blog posts detailing each step. Some of these steps aren't unique to Liferay or Tomcat so I'll break them up so if, for example, someone is looking for ways to connect Apache to Tomcat but isn't using Liferay, they can still benefit from this.

If you've been working with Liferay in just Tomcat (Or Oracle or Glassfish or whatever) you may not have had to interact with Apache. Apache is the quiet little web server that comes bundled with Linux and usually stays out of Tomcat's way. Well, now Apache is going to OWN Tomcat. Seriously. When we configure this thing Apache will decide what requests get sent to Tomcat and which ones don't. Tomcat's just going to have to learn to like it.

Here's how it works:

The user makes a request to the server. Shibboleth, having been configured to watch for this request, intercepts it and redirects the user to a separate authentication site. The user logs in using their credentials. Once they're authenticated, the request returns to the original server and Shibboleth then allows the request to proceed. Normally, with a site running under Apache, the request is turned over to Apache and the requested page is transmitted to the client. In the case of a request made to a servlet, more needs to happen. Apache will forward the request along to Tomcat, which will then handle it normally.

Technically, there are two halves of Shibboleth... The Service Provider (SP) and the Identity Provider (IdP). We're only going to worry about the SP here because that's the part that you, the person who's responsible for building this thing, are responsible for. Typically you'll be setting up a site that authenticates through a pre-existing IdP anyway so that part will already be done.

So our software today:

Operating System: (Linux) CentOS 5.6

Web Server: Apache 2.2.3

Web SSO Provider: Shibboleth 2.0

Servlet Container: Tomcat 6.0.29

Portal: Liferay 6.0.6

Step 1: Install Shibboleth

First thing's first... Install Shibboleth. If you're using the same OS I am, you can run this command:

sudo wget http://download.opensuse.org/repositories/security://shibboleth/CentOS_5/security:shibboleth.repo -P /etc/yum.repos.d

then navigate to /etc/yum.repos.d and run this command:

sudo yum install shibboleth.x86_64

If you're not, here's a WORKING link to the Shibboleth Wiki Linux install page.

Now, there are a couple of folders where log files will be written, and you need to make sure that the directory permissions are set such that Shibboleth can use them. These directories are

/var/log/httpd and

/var/log/shibboleth

The files that will be created are /var/log/httpd/native.log and /var/log/shibboleth/shibd.log. Don't create those files... Shibboleth will handle that. This is just so you know.

There is a file, located in /etc/shibboleth called shibboleth2.xml. This file contains the settings to allow Shibboleth to find and use the specific data items that control your authentication. In most cases, if you're working with a pre-existing IdP this file may be provided to you by the team that is responsible for that IdP. If not, a sample file is created for you that you can modify to your needs.

The first important part of that file is the RequestMapper section. It will look like this, assuming Liferay is installed in the ROOT and using the server name we came up with above.

<RequestMapper type="Native">

<RequestMap applicationId="default">

<Host name="test.awesome.server.dude" port="443" scheme="https">

<Path name="/" authType="shibboleth" requireSession="true"/>

</Host>

</RequestMap>

</RequestMapper>

Now, if this file wasn't provided to you by your IdP personnel then you're going to have to configure that part yourself. After RequestMapper is the ApplicationDefaults section. The opening tag for that section should look like this:

<ApplicationDefaults

entityID="https://test.awesome.server.dude/shibboleth"

REMOTE_USER="eppn persistent-id targeted-id"

attributePrefix="AJP_">

Inside this Element is another tag, <Sessions> which has yet another inside that, which we need to configure:

<SSO entityID="https://youramazingidpprovider/idp/shibboleth"

discoveryProtocol="SAMLDS" discoveryURL="https://ds.example.org/DS/WAYF">

SAML2 SAML1

</SSO>

These settings will vary depending on how the IdP is configured, and I'm afraid configuring an IdP is beyond the scope of this blog. There may be additional configuration items as well. If you're stuck having to set that up too, here's a link to the Shibboleth IdP setup page.

Save that file and be sure to start Shibboleth.

sudo /usr/sbin/shibd -fc /etc/shibboleth/shibboleth2.xml

To be continued...