58.1 Overview of JBoss Integration with Access Manager

JBoss application server is an open source alternative to the IBM WebSphere and SAP NetWeaver application servers. The JBoss application server and related services are a J2EE platform used for developing and deploying enterprise Java applications, Web applications services, and portals.

J2EE allows the use of standardized modular components and enables the Java platform to handle many aspects of programming automatically. For integration with JBoss, Oracle provides:

A J2EE type JBoss Agent
A JAAS-compliant Login Module, which can be used with any client to authenticate against Access Manager

Note:

There is no special processing within (or by) Access Manager with (or for) the JBoss Agent.

Integration between JBoss and Access Manager enables you to:

Protect Web applications and establish user single sign-on
Secure EJB access by configuring the login module for EJBs
Secure Web Services using the login module with Web service handlers to authenticate and authorize the caller

There are no client interfaces. For more information, see the following topics:

58.1.1 Configuration and Processing by the JBoss Agent

The JBoss Agent is a fully capable agent running on the JBoss Server. This JBoss Agent supports Access Manager Web single sign-on flows with (or without) a WebGate.

Authentication and authorization are based on resource URLs defined within Access Manager policies. The JBoss Agent intercepts every incoming request to the OAM Server and checks for access permissions for the requested resource. If the resource is protected by an OAM policy, the JBoss Agent initiates authentication and authorization for the user trying to access the resource.

Whenever an unauthenticated user requests access to any protected resource, the JBoss Agent redirects the user to the credential collector for a user name and password. The username and password that is entered is authenticated by the OAM Server. The JBoss Agent then establishes user session on the JBoss Container using the login module for the user. The login module queries the LDAP directory and fetches the authenticated user principals to set the subject.

Note:

The JBoss Agent depends on the Pure Java ASDK classes and APIs for accessing and communicating with the OAM Server. The JBoss Agent implements the javax.servlet.Filter interface. For more information, see the Access Manager Java API Reference.

The JBoss Agent requires OAM Server communication details, certificate store, and more, which can be configured as:

A properties file containing all configuration details (the path to this file can be set as a filter parameter)
The absolute path of the properties file added within the filter configuration in web.xml

Note:

The custom headers that are defined by the Oracle Access Management Administrator can only be defined using these methods.

The application filter should log messages at different logging levels (FATAL, ERROR, WARNING, DEBUG, TRACE). Each level indicates the severity of information logged, in descending order. The filter should be able to log the detailed trace of an incoming message as one set. The JBoss Agent and the Login Module are both equipped with messages for various log levels. For logging in the same log file (server.log):

<category name="<<Component_code_package>>">
 <priority value="FINEST" class="org.jboss.logging.log4j.JDKLevel"/>
</category>

For example, for ASDK, the category name in the previous tag is oracle.security.am.asdk, as shown:

<category name="<<oracle.security.am.asdk>>">
 <priority value="FINEST" class="org.jboss.logging.log4j.JDKLevel"/>
</category>

The following overview outlines the processing functions for the Access Manager JBoss Agent.

Query the OAM Server to check whether the requested resource is protected.
Call the OAM Server to retrieve the authentication scheme.
Analyze the authentication scheme for the protected resource, and redirect the request to the credential collector.
Authenticate the user credentials.
Successful Authentication: Set the authentication token generated from the OAM Server in the cookie.
Authentication Token: Validate the integrity of the token before servicing the request. Request the OAM Server to verify the user is authorized to access the protected resource and handle the response from the OAM Server accordingly.
Depending upon the user requests and OAM Server responses, the JBoss Agent identifies where user requests should be redirected to allow or deny access to the protected resource.

The JBoss Agent is comprised of components described in Table 58-1. Each component uses the Access ASDK to communicate with the OAM Server.

Table 58-1 JBoss Agent Composition

Component	Description
Authentication Valve	Invoked during the JBoss Authentication phase for all incoming requests. If the resource is marked as protected by security constraints in the application's Web descriptor, the Authentication Valve checks for the presence of a user principal in the HTTP session: Valid User Present: The Authentication Valve evaluates whether the user principal satisfies the security constraints from the application's Web description. If constraints are satisfied, the request proceeds. Otherwise, an authorization failure message is displayed. Valid Single Sign On Cookie Present (ObSSOCookie) (No Valid User): The Authentication Valve verifies the cookie's validity by using the Access Manager Login module (and sets the user principal in the session). No Valid Single Sign On Cookie Present (ObSSOCookie) / No Valid User: The Valve redirects to the OAM Login page when the resource is marked as protected using Access Manager policies.
Authentication Filter	Invoked for each incoming request following the JBoss authentication phase. For each incoming request, the filter verifies whether a token is present. Token Present: The filter uses the ASDK to validate the token. Invalid Token: The filter redirects to the Access Manager Login page.
Access Manager Login Module	Used internally by the JBoss Agent to authenticate the user based on the SSO token. Any client (stand alone or deployed within the JBoss Container) can use the Login Module to authenticate the incoming user based on username and password or a valid token.

Component

Description

Authentication Valve

Invoked during the JBoss Authentication phase for all incoming requests. If the resource is marked as protected by security constraints in the application's Web descriptor, the Authentication Valve checks for the presence of a user principal in the HTTP session:

Valid User Present: The Authentication Valve evaluates whether the user principal satisfies the security constraints from the application's Web description. If constraints are satisfied, the request proceeds. Otherwise, an authorization failure message is displayed.
Valid Single Sign On Cookie Present (ObSSOCookie) (No Valid User): The Authentication Valve verifies the cookie's validity by using the Access Manager Login module (and sets the user principal in the session).
No Valid Single Sign On Cookie Present (ObSSOCookie) / No Valid User: The Valve redirects to the OAM Login page when the resource is marked as protected using Access Manager policies.

Authentication Filter

Invoked for each incoming request following the JBoss authentication phase. For each incoming request, the filter verifies whether a token is present.

Token Present: The filter uses the ASDK to validate the token.
Invalid Token: The filter redirects to the Access Manager Login page.

Access Manager Login Module

Used internally by the JBoss Agent to authenticate the user based on the SSO token.

Any client (stand alone or deployed within the JBoss Container) can use the Login Module to authenticate the incoming user based on username and password or a valid token.

58.1.2 Configuration and Processing by the Login Module

The JAAS-compliant Access Manager Login Module is a pluggable authentication module using JAAS APIs provided by the Access Manager javax.security.* package. The JAAS-compliant Login Module interfaces enable the client to pass authentication data to the server. The login module is configured with the JBoss server and application to integrate the module with the JBoss application server.

The Login Module implementation class is:

   public class OAMLoginModule implements LoginModule

The standard JAAS packages required by this class are javax.security.*. The login module class is stored in a jar file: $JBOSS_HOME/server/default/lib.

The login-config.xml file is the default JBoss Login Module configuration file. This Login Module requires a JAAS security domain name (OAMLoginModule, for instance). Information is stored in login-config.xml as a list of named security domains, each of which specifies a number of JAAS Login Modules that are used for authentication within that domain. For example, you add this manually and then restart the JBoss Server.

 <application-policy name="OAMLoginModule">
    <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 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>

Note:

Whenever an application requires security, you must specify the domain name to use in the application's JBoss-specific deployment descriptors (either one or both):

jboss.xml: Defines JBoss-specific configurations for an application.
jboss-web.xml: Defines JBoss for a Web application. This file must declare the security domain and should be placed in the WEB-INF folder.

The JAAS-compliant Login Module consumes either user name/password or Access Manager token. It authenticates and validates the credentials or token with the OAM Server (using the Access Manager Java ASDK APIs) and populates the JAAS subject with user and group information obtained from the OAM Server.

The Login Module can operate in either usernamePassword mode or tokenBased mode. The following sections provide details.

58.1.3 Login Module Process in usernamePassword Mode

The usernamePassword mode authenticates the user based on user name and password or a user and certificate combination that forms a security identity and credential pair.

The Login Module does not directly query the LDAP. Instead the login module uses the OAM Java ASDK to communicate and authenticate the user credentials with the OAM Server; user and group information is retrieved as responses. Following is an overview of the process.

Fetches login information.
Authenticates the user with Access Manager based on credentials collected by the JBoss Agent.
Creates the container session for the client on the server.
Sets the JAAS subject with the userID and roles.
On logout, clears the principal settings of the subject in the session and removes the privilege settings associated with the roles of the subject.

58.1.4 Login Module Process in tokenBased Mode

The tokenBased mode sets the Subject by validating the SSO token.

Following is the process flow for setting the Subject:

Fetches login information.
Validates the SSO authentication token generated from the OAM Server in the cookie.
Creates the container session for the client on the server.
Sets the JAAS subject with the userID and roles fetched using the existing SSO session token.
On logout, clears the principal settings of the subject in the session and removes the privilege settings associated with the roles of the subject.