This document describes the steps needed to enable JASPI authentication for Web applications on JBoss AS7.

Application Server Configuration

The first step to enable JASPI is to configure a security domain that installs the JASPI login modules. So, in your standalone.xml (or domain.xml if using domain mode), add the JASPI configuration in the security subsystem:

                <!-- security domain configuration for the jaspi web basic test -->
                <security-domain name="jaspi-test" cache-type="default">
                    <authentication-jaspi>
                        <login-module-stack name="lm-stack">
                            <login-module code="UsersRoles" flag="required">
                                <module-option name="usersProperties" value="../standalone/configuration/jaspi-users.properties"/>
                                <module-option name="rolesProperties" value="../standalone/configuration/jaspi-roles.properties"/>
                            </login-module>
                        </login-module-stack>
                        <auth-module code="org.jboss.as.web.security.jaspi.modules.HTTPBasicServerAuthModule" login-module-stack-ref="lm-stack" flag="required"/>
                    </authentication-jaspi>
                </security-domain>

In this example we are configuring the HTTPBasicServerAuthModule, which will perform the BASIC authentication of a Web application. If FORM authentication is desired, just change the auth-module to org.jboss.as.web.security.jaspi.modules.HTTPFormServerAuthModule. Notice the configuration style is very similar to what is found in previous JBoss AS versions. The configured JASPI module can delegate the authentication and role mapping processes to a login module stack. In this case, we're using a simple UsersRoles module to authenticate and obtain roles for the users.

The sample security-domain can also be configured by using CLI management tool using following commands:

/subsystem=security/security-domain=jaspi-test:add(cache-type=default)
/subsystem=security/security-domain=jaspi-test/authentication=jaspi:add(auth-modules=[{"code"=>"org.jboss.as.web.security.jaspi.modules.HTTPBasicServerAuthModule", "login-module-stack-ref"=>"lm-stack", "flag"=>"required"}])
/subsystem=security/security-domain=jaspi-test/authentication=jaspi/login-module-stack=lm-stack:add(login-modules=[{"code"=>"UsersRoles", "flag"=>"required", "module-options"=>{"usersProperties"=>"../standalone/configuration/jaspi-users.properties", "rolesProperties"=>"../standalone/configuration/jaspi-roles.properties"}}], operation-headers={"allow-resource-service-restart"=>"true"})

Web Application Configuration

The next step is to configure the Web application. First, we specify the type of authentication that is to be performed. For example, an application that requires BASIC authentication must specify that in the WEB-INF/web.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/j2ee/web-app_2_5.xsd">
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>Home</web-resource-name>
      <url-pattern>/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>architect</role-name>
    </auth-constraint>
  </security-constraint>

  <login-config>
      <auth-method>BASIC</auth-method>
      <realm-name>JASPI</realm-name>
   </login-config>

  <security-role>
    <role-name>architect</role-name>
  </security-role>
</web-app>

Finally, we need to link the Web application to the security domain that will perform the authentication and configure the valve that will enable the JASPI authentication. Both things are done in the WEB-INF/jboss-web.xml file:

<?xml version="1.0"?>

<jboss-web>
   <security-domain>jaspi-test</security-domain>
   <valve>
      <class-name>org.jboss.as.web.security.jaspi.WebJASPIAuthenticator</class-name>
   </valve>
</jboss-web>

The specified <security-domain> must match the name of the security domain that has been configured in the application server. It is also important that the WebJASPIAuthenticatorValve is configured as this valve replaces the Web container authenticator ir order to perform the JASPI authentication.

NOTE: the WebJASPIAuthenticator replaces the previous org.jboss.web.tomcat.security.jaspi.TomcatJASPIAuthenticator and MUST be configured in the jboss-web.xml file. JBoss AS7 doesn't allow for the configuration of authenticator valves in the JBossWeb subsystem like previous versions.