58.6 Protecting Web Applications with the JBoss Agent

This section provides the following tasks required to protect Web Applications with the JBoss Agent. Before beginning this section, deploy the application as usual.

58.6.1 Creating Configuration Properties for the JBoss Agent

You copy Jboss Agent registration artifacts from the AdminServer to the JBoss host and create a filter configuration properties file that is referenced later. The JBoss Agent relies on the 11g Java ASDK which operates in the same mode as the registered JBoss Agent.

The JBoss Agent requires a configuration file (oam_config.properties) that defines a number of critical properties. These include the file system path to the agent's registration artifact (ObAccessClient.xml), the security domain defined in the JBoss server's login configuration file, parameters and values that return to the JBoss Agent during authentication, and an optional attribute to check for the presence of authToken in the request. Use this procedure to create a configuration properties file for the JBoss Agent.

Create a JBoss Agent configuration file named oam_config.properties using the following sample as a guide:

##Path of the folder containing the ObAccessClient.xml
configPath=D:\\agentconfig

##Name of the security domain as configured in JBoss's login-config.xml
realmName=oamrealm

##Optional. If not specified then defaults to /Authen/Basic
##publicAuthnResourceName=/Authen/Basic 

##Optional. If not specified then defaults to http
##publicAuthnResourceType=http

##Optional. If not specified then defaults to GET
##publicAuthnResourceOperation=GET

##Optional. If not specified then defaults to /Authen/SSOToken
##publicAuthzResourceName=/Authen/SSOToken

##Optional. If not specified then defaults to http
##publicAuthzResourceType=http

##Optional. If not specified then defaults to GET
##publicAuthzResourceOperation=GET

rolesParam=OAM_GROUPS

##Optional. This attribute is responsible to check whether the credential in  
##the subject / callback handler is an authn token. Defaults to authnToken.
authToken=authToken

####################################
##### OAM logout related properties #####
####################################
##Host name of the OAM 11g Server
##oamHost=abchost.us.example.com

##Managed server port number of the OAM 11g Server
##oamPort=Port_value

Save oam_config.properties on the JBoss host:
```
/agentconfig/oam_config.properties
```
Proceed to "Configuring the Authentication Valve".

58.6.2 Configuring the Authentication Valve

You can configure the Authentication Valve in one of the two ways that is best suited to your environment.

Note:

This procedure is not needed if you are Preparing Your Environment for JBoss 6.x Integration as the Valve is not currently supported at the Global level.

To configure the Authentication Valve:

Adding the Authentication Valve to context.xml: This global configuration causes the Authentication Valve to intercept all requests to the JBoss Agent.
Adding the Authentication Valve to the Application's Deployment: Rather than adding the Authentication Valve to context.xml for global use, you can add a context.xml as part of the application's deployment. This configuration affects only the concerned application (the Authentication Valve intercepts requests coming only to this specific application).

58.6.2.1 Adding the Authentication Valve to context.xml

You can add the Authentication Valve to context.xml.

Locate and open for editing the JBoss Agent context.xml file in:

JBoss_install_dir\server\default\deploy\jbossweb.sar\context.xml

Add the following Valve entry and save the file:

<Valve className="oracle.security.am.agent.common.authenticator.OAMAuthenticatorValve" configFile="<full_path_to_oamagent_config_properties_file> " />

Proceed to Mapping the Filter in the Application's web.xml File

58.6.2.2 Adding the Authentication Valve to the Application's Deployment

You can add the Authentication Valve to the application's deployment.

Create a fresh context.xml file and store it under WEB-INF with web.xml:
```
JBoss_install_dir\server\default\deploy\jbossweb.sar\context.xml
```

Add the following Valve entry:

<?xml version="1.0" encoding="UTF-8"?>
 
<Context privileged="true">
   <Valve className="oracle.security.am.agent.common.authenticator.OAMAuthenticatorValve" configFile="<full_path_to_oamagent_config_properties_file> " />

</Context>

Redeploy the application.
Proceed to Mapping the Filter in the Application's web.xml File

58.6.3 Mapping the Filter in the Application's web.xml File

You can add filter mapping for this integration to the application's web.xml.

You also add the name of the filter's configuration properties file.

Locate the web.xml file in the application EAR file:
```
my_app/WEB-INF/web.xml  
```

Add the following filter mapping to the application's web.xml. For example:

<filter>
  <filter-name>OAMFilterAgent</filter-name> 
  <filter-class>
    oracle.security.am.agent.common.filter.OAMAuthenticationFilter
  </filter-class>
  <init-param>
    <param-name>configFile</param-name>
    <param-value>D:/oam_config.properties</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>OAMFilterAgent</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

Save the file.
Proceed to Configuring the JBoss Login Module to Use Access Manager Policies

58.6.4 Configuring the JBoss Login Module to Use Access Manager Policies

This procedure describes the required login module entry for JBoss to use Access Manager policies. After you add filter mapping to web.xml, you redeploy the application and start the JBoss Server.

Note:

Starting JBoss Server using -b 0.0.0.0 allows the user to access the server by the host name rather than localhost / 127.0.0.1. Without this parameter, JBoss Server can be accessed using localhost / 127.0.0.1 as well as the host name.

Locate and open the login-config.xml file:

JBoss_install_dir\server\default\conf\login-config.xml

Add a new entry for the login module, as follows:

<application-policy name="oamrealm">
  <authentication>
    <login-module code="oracle.security.am.agent.common.jaas.login.OAMLoginModule"       flag="required">
      <module-option name="loginType">tokenBased</module-option>
      <module-option name="configPath">D:/agentconfig</module-option>
      <module-option>       
      <module-option name="publicAuthnResourceName">/Authen/Basic</module-option>
      <module-option name="rolesParam">OAM_GROUPS</module-option>
      <module-option name="publicAuthzResourceName">/Authen/SSOToken</module-option>
    </login-module>
  </authentication>
</application-policy>

The name of application-policy in this entry should have the same value as that defined for the realmname property in oam_config.properties.

Deploy the application.
Start JBoss as follows using the following command:
```
JBoss_install_dir\bin\run –b 0.0.0.0 
```
See Configuring JBoss Server to Access a Host Name (not localhost)