Web Services Security Guides › CA SiteMinder® Agent for JBoss › Configure the SiteMinder Agent Security Interceptor to Protect Web Applications on JBoss 5.x

Configure the SiteMinder Agent Security Interceptor to Protect Web Applications on JBoss 5.x

This section contains the following topics:

Configure SiteMinder Agent Authenticators

Define a JBossSX Security Domain for the SiteMinder Agent Login Module

Configure Web Applications to Invoke the SiteMinder Agent Security Interceptor on JBoss 5.x

Restart the JBoss Application Server

Configure Policy Objects for the SiteMinder Agent Security Interceptor

Configure SiteMinder Agent Authenticators

SiteMinder Agent Authenticators extend the functionality of the JBossSX default authenticators with the ability to authenticate a user request based on an associated SiteMinder session cookie.

You can configure the SiteMinder Agent Authenticators into the JBoss security infrastructure for all web applications or for individual web applications as required.

Configure SiteMinder Agent Authenticators For All Web Applications on JBoss 4.x

To configure the SiteMinder Agent Authenticators to handle all JBoss web application requests, replace the default JBossSX authenticator methods with the SiteMinder Agent Authenticator methods in the JBoss core authentication services definition.

The JBoss core authentication services are defined in the jboss-service.xml configuration file located in the following location:

server/server_name/deploy/jboss-web.deployer/META-INF/

Note: The SiteMinder Agent Authenticator methods extend the default authenticator methods; the default authenticator functionality is still available for requests without valid SiteMinder session cookies.

To Configure SiteMinder Agent Authenticators at the global level

Navigate to server/server_name/deploy/jboss-web.deployer/META-INF/.
Open the jboss-service.xml file in a text editor.
Locate the <attribute name="Authenticators" ...> element definition section.
Edit the java:value element in the java:property element definitions for BASIC, FORM, CLIENT-CERT, and DIGEST authentication, replacing the default authenticator methods with the corresponding SiteMinder Agent Authenticator methods as required.
To configure the SMJBossBasicAuthenticator, edit the java:property element for BASIC authentication as follows:
```
<java:property>
  <java:key>BASIC</java:key>
  <java:value>
  com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossBasicAuthenticator
  </java:value>
</java:property>
```
To configure the SMJBossFormAuthenticator, edit the java:property element for FORM authentication as follows:
```
<java:property>
  <java:key>FORM</java:key>
  <java:value>
  com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossFormAuthenticator
  </java:value>
</java:property>
```
To configure the SMJBossClientCertAuthenticator, edit the java:property element for CLIENT-CERT authentication as follows:
```
<java:property>
  <java:key>CLIENT-CERT</java:key>
  <java:value>
  com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossClientCertAuthenticator
  </java:value>
</java:property>
```
To configure the SMJBossDigestAuthenticator, edit the java:property element for DIGEST authentication as follows:
```
<java:property>
  <java:key>DIGEST</java:key>
  <java:value>
  com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossDigestAuthenticator
  </java:value>
</java:property>
```
If you do not want the default authentication behavior to occur if SiteMinder session cookie validation fails, configure the SMJBossIdentityAsserter in place of any authenticator. For example, to configure the SMJBossIdentityAsserter so that default Digest authentication does not occur if SiteMinder identity assertion fails, edit the java:property element for DIGEST as follows:
```
<java:property>
  <java:key>DIGEST</java:key>
  <java:value>
  com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossIdentityAsserter
  </java:value>
</java:property>
```
Save the file and exit the text editor.

The SiteMinder Agent Authenticators are configured as the default authenticators for all security-enabled web applications. The authenticator configured for the authentication method defined in the web application deployment descriptor will handle request unless an authenticator is configured individually for that application.

Example jboss-service.xml

The following is an example <attribute name="Authenticators" ...> element definition section with all SiteMinder Agent Authenticators configured.

<attribute name="Authenticators" serialDataType="jbxb">
  <java:properties xmlns:java="urn:jboss:java-properties"
   xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
   xs:schemaLocation="urn:jboss:java-properties resource:java-properties_1_0.xsd">

<java:property>
  <java:key>BASIC</java:key>
  <java:value>
  com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossBasicAuthenticator
  </java:value>
</java:property>

<java:property>
  <java:key>FORM</java:key>
  <java:value>
  com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossFormAuthenticator
  </java:value>
</java:property>

<java:property>
  <java:key>CLIENT-CERT</java:key>
  <java:value>
  com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossClientCertAuthenticator
  </java:value>
</java:property>

<java:property>
  <java:key>DIGEST</java:key>
  <java:value>
  com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossDigestAuthenticator
  </java:value>
</java:property>

<java:property>
  <java:key>NONE</java:key>
  <java:value>
  org.apache.catalina.authenticator.NonLoginAuthenticator
  </java:value>
</java:property> 
  </java:properties>
</attribute>

Configure SiteMinder Agent Authenticators For All Web Applications on JBoss 5.x

The JBoss core authentication services are defined in the war-deployers-jboss-beans.xml configuration file located in the following location:

server/server_name/deployers/jbossweb.deployer/META-INF

To Configure SiteMinder Agent Authenticators at the global level

Navigate to server/server_name/deployers/jbossweb.deployer/META-INF.
Open the war-deployers-jboss-beans.xml file in a text editor.
Locate the <attribute name="Authenticators" ...> element definition section.
Edit the java:value element in the java:property element definitions for BASIC, FORM, CLIENT-CERT, and DIGEST authentication, replacing the default authenticator methods with the corresponding SiteMinder Agent Authenticator methods as required.
To configure the SMJBossBasicAuthenticator, edit the java:property element for BASIC authentication as follows:
```
<entry>
  <key>BASIC</key>
  <value>com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossBasicAuthenticator</value>
</entry>
```
To configure the SMJBossFormAuthenticator, edit the java:property element for FORM authentication as follows:
```
<entry>
  <key>FORM</key>
  <value>com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossFormAuthenticator</value>
</entry>
```
To configure the SMJBossClientCertAuthenticator, edit the java:property element for CLIENT-CERT authentication as follows:
```
<entry>
  <key>CLIENT-CERT</key>
  <value>com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossClientCertAuthenticator</value>
</entry>
```
To configure the SMJBossDigestAuthenticator, edit the java:property element for DIGEST authentication as follows:
```
<entry>
  <key>DIGEST</key>
  <value>com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossDigestAuthenticator</value>
</entry>
```
If you do not want the default authentication behavior to occur if SiteMinder session cookie validation fails, configure the SMJBossIdentityAsserter in place of any authenticator. For example, to configure the SMJBossIdentityAsserter so that default Digest authentication does not occur if SiteMinder identity assertion fails, edit the java:property element for DIGEST as follows:
```
<entry>
  <key>DIGEST</key>
  <value>com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossIdentityAsserter</value>
</entry>
```
Save the file and exit the text editor.

Configure a SiteMinder Agent Authenticator for an Individual Application on JBoss 5.x

To configure a web application to use a specific SiteMinder Agent Authenticator to handle requests, define a context.xml file in the application WEB-INF directory. Configuring a context.xml file overrides the global authenticators defined in war-deployers-jboss-beans.xml.

To configure a web application to use a specific SiteMinder Agent Authenticator

Navigate to the application WEB-INF directory.
Open a text editor.

Define a context element containing a valve subelement that specifies the class name of the SiteMinder Agent Authenticator which you want to handle application requests.

To configure the application to use SMJBossBasicAuthenticator, type:

<Context cookies="true" crossContext="true">
  <Valve className="com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossBasicAuthenticator"/>
</Context>

To configure the application to use the SMJBossFormAuthenticator, type:

<Context cookies="true" crossContext="true">
  <Valve className="com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossFormAuthenticator"/>
</Context>

To configure the application to use SMJBossClientCertAuthenticator, type:

<Context cookies="true" crossContext="true">
  <Valve className="com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossClientCertAuthenticator"/>
</Context>

To configure the application to use SMJBossDigestAuthenticator, type:

<Context cookies="true" crossContext="true">
  <Valve className="com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossDigestAuthenticator"/>
</Context>

To configure the application to use the SMJBossIdentityAsserter, type:

<Context cookies="true" crossContext="true">
  <Valve className="com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossIdentityAsserter"/>
</Context>

Save the file as context.xml and exit the text editor.

Define a JBossSX Security Domain for the SiteMinder Agent Login Module

Define a JBoss security domain named SiteMinderDomain that configures the SiteMinder Agent Login Module required to authenticate credentials obtained by SiteMinder Agent authenticators. Configure the SiteMinderDomain by adding an application-policy element to the login-config.xml file located in server/server_name/conf/.

To configure SiteMinder Agent Authenticators at the global level

Navigate to server/server_name/conf/login-config.xml
Open the login-config.xml file in a text editor.

Add the following application-policy element defining the SiteMinderDomain:

<application-policy name="SiteMinderDomain">
  <authentication>
    <login-module
    code="com.ca.soa.agent.appserver.authenticator.jBoss.SMJBossLoginModule"
    flag="required">
    <module-option name="unauthenticatedIdentity">anonymous</module-option>
    </login-module>
  </authentication>
</application-policy>

Save the file and exit the text editor.

Configure Web Applications to Invoke the SiteMinder Agent Security Interceptor on JBoss 5.x

To protect a web application (in the web or EJB container) using the SiteMinder Agent Security Interceptor, edit its deployment descriptor to enable security and map it to the SiteMinderDomain security domain.

Edit the Application Deployment Descriptor to Enable Security

Edit the web.xml deployment descriptor to enable security for each web application that you want to protect with the SiteMinder Agent Web Interceptor. The web.xml file is located in the application WEB-INF directory.

For more information about the web.xml file and constituent element syntax, see the JBoss Enterprise Application Platform documentation.

Follow these steps:

Navigate to the web application WEB-INF directory
Open the web.xml deployment descriptor file in a text editor.

Add one or more security-constraint elements defining what resources in the web application are to be protected. For example:

<security-constraint>
    <display-name>Constraint1</display-name>
    <web-resource-collection>
        <web-resource-name>admin resource</web-resource-name>
        <description/>
        <url-pattern>/admin/*</url-pattern>
        <http-method>GET</http-method>
        <http-method>POST</http-method>
    </web-resource-collection>
    <auth-constraint>
        <description/>
        <role-name>adminRole</role-name>
    </auth-constraint>
</security-constraint>

Add a security-role element defining roles used by the application. For example:

<security-role>
     <description/>
     <role-name>adminRole</role-name>
</security-role>

Add a login-config element. The auth-method subelement of the login-config element defines the authentication method (BASIC, FORMS, and so on) and therefore determines which globally configured SiteMinder Agent Authenticator will be invoked. For example, the following login-config element would result in the SMJBossFormAuthenticator handling application requests:
```
<login-config>
    <auth-method>FORM</auth-method>
    <realm-name/>
    <form-login-config>
        <form-login-page>/login.jsp</form-login-page>
        <form-error-page>/fail_login.jsp</form-error-page>
    </form-login-config>
</login-config>
```
Save the file and exit the text editor
Install or update the web application.

Map Web Applications to the SiteMinderDomain Security Domain

Create a jboss-web.xml deployment descriptor file that defines the SiteMinderDomain as the security domain for each web application that you want to protect with the SiteMinder Agent. The jboss-web.xml file must be created in the application WEB-INF directory.

Follow these steps:

Navigate to the application WEB-INF directory.
Open a text editor.

Enter the following:

<jboss-web>
  <security-domain>java:/jaas/SiteMinderDomain</security-domain>
</jboss-web>

Save the file as jboss-web.xml and exit the text editor.

Restart the JBoss Application Server

Restart the JBoss Application Server to commit configuration changes you made for the SiteMinder Agent.

To restart the JBoss Application Server

If necessary, stop the JBoss Application Server process.
Open a command window.
Navigate to the JBOSS_HOME/bin directory.
Run the run.bat (Windows) or run.sh (UNIX) script.

The JBoss Application Server restarts with the configuration changes you made for the SiteMinder Agent.