We provide a supported library for Java applications called SSO Client. Through some provided Servlets, Filters and JSP tags (and equivalents for Play! Framework), it handles the whole login process, and provides you with a User object to access properties about the currently logged-in user. There are also some additional methods for looking up information about arbitrary user codes. SSO Client supports either old or new mode, but unless there is a particular reason not to, we will be getting set up for new mode.

This guide assumes that you are reasonably familiar with how Servlets and Filters are defined in the web.xml file of a web application, or with how to build a basic Play! application.

First you will need a copy of SSO Client. SSO Client is open source and builds are publicly available in our Nexus repository. If you are using a dependency management tool such as Maven or Gradle, it is straightforward to add SSO Client as a dependency. The examples below show how to set-up the repository with Maven:

<repositories>
  <repository>
    <id>warwick-its-nexus</id>
    <name>Warwick ITS Nexus Repository</name>
    <url>https://mvn.elab.warwick.ac.uk/nexus/repository/public-anonymous/</url>
  </repository>
</repositories>

And the dependency:

<dependencies>
  <dependency>
    <groupId>uk.ac.warwick.sso</groupId>
    <artifactId>sso-client</artifactId>
    <version>2.62</version>
  </dependency>
</dependencies>

Alternatively, if you specify that your application is written in Java when you register your service, we can send you a copy of the latest version of the library.

Setting up SSO Client (Servlet)

• You will need to contact us to register your service.
• Add the JAR and its dependencies to your WEB-INF/lib directory, so they get deployed as part of your application.
• Add sso.tld (provided) to WEB-INF/tld or the location of your choice.
• Add the example XML to your web.xml, amending as appropriate. Some filters are commented as optional, so you can modify or remove those to your needs.
• Place your myapp-sso-config.xml file in the location specified by web.xml, such as the conf/ directory of your JBoss or Tomcat instance. Documentation is available which explains the structure of this config file. (We should provide you with a config file - let us know if you don't have one.)

At this point, your application should be checking for a valid SSO session on each request. If you have configured the ForceLoginFilter on any locations, it will redirect a browser to SSO if the user is not signed in. Now is a good time to look out for any error messages in your logs - if something has failed then check that you've followed each of the steps. If it's still unclear, drop us an email or post on the SSO forum.

Accessing user data

By default, SSOClientFilter will place a User object in an attribute called SSO_USER. You can access this User from code via the HttpServletRequest object, and directly from your JSP views as ${SSO_USER}. You may test your setup by adding ${SSO_USER.lastName} to a JSP. If you are signed in, it should display the current user's surname.

When nobody is logged in, there will still be a User object representing the anonymous user. You can check whether someone is actually signed in using ${SSO_USER.loggedIn} (representing the method User.isLoggedIn())

Login and logout links

You can generate login and logout links yourself but it's much easier to use the tags provided by the sso.tld file you added to your application. The following snippet shows some example JSP that loads sso.tld at the top of your JSP, and uses the tags to display a login/logout link as appropriate.

<%@taglib uri="/WEB-INF/tld/sso.tld" prefix="sso" %>
<%@taglib uri="/WEB-INF/tld/c.tld" prefix="c" %>
<!--

 ... your JSP code ...

-->
<c:choose>
 <c:when test="${SSO_USER.loggedIn}">
  Signed in as <c:out value="${SSO_USER.fullName}" /> (<c:out value="${SSO_USER.userId}" />)
  &bull;
  <strong><a href="<sso:logoutlink />">Sign out</a></strong>
 </c:when>
 <c:otherwise>
  <strong><a href="<sso:loginlink />">Sign in
 </c:otherwise>
</c:choose>

At this point, you can log users in, and show your own custom content for that user. You can also restrict access to certain URLs to members of a Webgroup, which is useful for an admin section. This may be all you need. However, with a bit more work you can do a few more things, such as fetch info about other users (not just the one who's logged in).

Accessing other users with UserLookup

This is done through a class called UserLookup.

// This line will get a default instance of UserLookup - usually this is fine,
// but you can also manually create a single UserLookup object in your web app and use that throughout.
UserLookupInterface userLookup = UserLookupFactory.getInstance();

User someUser = userLookup.getUserByUserId("abcdef");
if (someUser.isFoundUser()) {
  // this user exists
}

You can also look up WebGroups with this service.

Group chemStaff = userLookup.getGroupService().getGroupByName("ch-staff");
itStaff.getUserCodes();