JASPIC

Table of Contents

Introduction

Tomcat implements JASPIC 1.1 Maintenance Release B (JSR 196). The implementation is primarily intended to enable the integration of 3rd party JASPIC authentication implementations with Tomcat.

JASPIC may be configured in one of two ways:

  • At the container level via the static configuration file $CATALINA_BASE/conf/jaspic-providers.xml. With this approach all required classes must be visible to Tomcat's Common class loader which normally means placing a JAR in $CATALINA_BASE/lib.
  • At the web application level via dynamic configuration using the JASPIC API. With this approach all required classes must be visible to the web application class loader which normally means placing a JAR in the web application's WEB-INF/lib directory.

Users should be aware that if the static JASPIC configuration file configures JASPIC for a given web application then the JASPIC configuration will take precendence over any <login-config> present in the web application's WEB-INF/web.xml file.

Static configuration

AuthConfigProvider

If the 3rd party implementation includes an AuthConfigProvider then a web application can be configured to use it by nesting the following inside the <jaspic-providers> element in $CATALINA_BASE/conf/jaspic-providers.xml.

<provider name="any"
          className="fully.qualified.implementation.class.Name"
          layer="HttpServlet"
          appContext="Catalina/localhost /contextPath"
          description="any">
  <property name="see-provider-documentation"
            value="see-provider-documentation" />
</provider>

The name and description attributes are not used by Tomcat.

The className attribute must be the fully qualified class name of the AuthConfigProvider. The implementation may be packaged with the web application or in Tomcat's $CATALINA_BASE/lib directory.

The layer attribute must be HttpServlet.

The appContext attribute must be exactly the concatenation of:

  • The engine name
  • The forward slash character
  • The host name
  • A single space
  • The context path

If the AuthConfigProvider supports configuration via properties these may be specified via <property> elements nesting inside the <provide> element.

ServerAuthModule

If the 3rd party implementation only provides an ServerAuthModule then it will be necessary to provide a number of supporting classes. These may be a custom implementation or, alternatively, Tomcat provides a simple wrapper implementation for ServerAuthModules.

Tomcat's wrapper for ServerAuthModule can be configured by nesting the following inside the <jaspic-providers> element in $CATALINA_BASE/conf/jaspic-providers.xml.

<provider name="any"
          className="org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider"
          layer="HttpServlet"
          appContext="Catalina/localhost /contextPath"
          description="any">
  <property name="org.apache.catalina.authenticator.jaspic.ServerAuthModule.1"
            value="fully.qualified.implementation.class.Name" />
  <property name="see-provider-documentation"
            value="see-provider-documentation" />
</provider>

The configuration is similar to the AuthConfigProvider in the previous section but with some key differences.

The className attribute must be org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider.

The ServerAuthModule(s) are specified via properties. The property name must be org.apache.catalina.authenticator.jaspic.ServerAuthModule.n where n is the index of the module. The index must start at 1 an increment in steps of 1 until all modules are defined. The value of the property must be the fully qualified class name of the module.

Dynamic configuration

JASPIC modules and configuration can be packaged within a WAR file with the web application. The web application can then register the required JASPIC configuration when it starts using the standard JASPIC APIs.

If parallel deployment is being used then dynamic configuration should not be used. The JASPIC API assumes that a context path is unique for any given host which is not the case when using parallel deployment. When using parallel deployment, static JASPIC configuration should be used. This will require that all versions of the application use the same JASPIC configuration.

3rd party modules

This is not an exhaustive list. The Tomcat community welcomes contributions that add to this section.

Philip Green II's module for Google OAuth 2

The source code for this module along with the documentation which includes details of the necessary Google API configuration is available on GitHub.

A sample configuration for using this module with Tomcat would look like this:

<jaspic-providers xmlns="https://tomcat.apache.org/xml"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="https://tomcat.apache.org/xml jaspic-providers.xsd"
                  version="1.0">
  <provider name="google-oauth"
            className="org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider"
            layer="HttpServlet"
            appContext="Catalina/localhost /contextPath"
            description="Google OAuth test">
    <property name="org.apache.catalina.authenticator.jaspic.ServerAuthModule.1"
              value="com.idmworks.security.google.GoogleOAuthServerAuthModule" />
    <property name="oauth.clientid"
              value="obtained-from-Google-console" />
    <property name="oauth.clientsecret"
              value="obtained-from-Google-console" />
    <property name="ignore_missing_login_context"
              value="true" />
  </provider>
</jaspic-providers>