About OpenAM Java EE Policy Agents A Java EE policy agent is an OpenAM add-on component that functions as a Policy Enforcement Point (PEP) for applications deployed on a Java EE-based servlet container or application server. The policy agent protects web-based applications and implements single sign-on (SSO) capabilities for the applications deployed in the container. OpenAM Java EE policy agents provide medium touch integration and run on a wide variety of servlet containers and application servers. The installation process for Java EE policy agents differs slightly for each container type and may require some configuration and code changes to the configuration files. The installation procedures for each container type are presented later in this guide. This chapter covers what Java EE policy agents do, their key features, and how they work. A single policy agent can work with multiple applications. You therefore install only one policy agent per application server. Installing more than one policy agent in an application server is not supported. Java EE Policy Agent Components The OpenAM Java EE policy agent is comprised of five main components: Policy agent filter Container-specific Java Authentication and Authorization Server (JAAS) realm implementation Agent application .war file Agent installer Client SDK The installer integrates the other components within the container, after which the components run transparently, connecting to OpenAM through its client SDK. Java EE Policy Agent Filter. The Java EE Policy Agent filter is a servlet filter referenced within the deployment descriptor file web.xml, of each protected application in the container. Applications that do not have their deployment descriptor file updated to use the agent servlet filter will not be protected. The filter’s main function is to intercept an inbound client access request for a protected resource and run through a set of task handlers, including determining whether the user has a session ID or token. If the user does not have a session token in the browser cookie iPlanetDirectoryPro, then the policy agent immediately redirects the user to OpenAM for authentication. Once the user has a session token, the agent retrieves the agent profile from OpenAM and continues to process the request based on the property settings defined in the agent profile. Agent Realm. The Agent realm is not strictly a component, but is a container-specific integration to allow support for Java Authentication and Authorization Service (JAAS). The Agent Realm, or more accurately the JAAS Realm, leverages the underlying Java EE container’s ability to retrieve the user’s identity and populate the principal in the HTTPServletRequest object. You can use the Java EE container’s declarative and programmatic security settings that define role-based access control over the web resources. You can define the roles in the descriptor files and then define the user’s roles within OpenAM, allowing the application to check authorization. JAAS support provides another powerful feature that lets you implement such Java EE permissions-related annotations as @RolesAllowed and @DeclareRoles, which are specifically designed to secure Enterprise Java Bean (EJB) modules for authenticated users. Agent Application. The Agent application, deployed as agentapp.war, processes notifications from OpenAM, refreshes the caches, and runs processes for cross-domain single sign-on (CDSSO). The agentapp.war file also displays error messages if the cross-site scripting (XSS) detector is enabled. Note that there are some subtle container-dependent configuration differences that may affect the installation of agentapp.war. For certain containers, the installer installs the agentapp.war file; for others, you must manually install the file as part of the agent installation. Technically, the agentapp.war is not a required component if you have no plans to use CDSSO and notifications, but it is strongly recommended that you deploy it as notifications from OpenAM are extremely useful. Agent Installer. The agent installer, invoked by the agentadmin tool, automates the policy agent installation within a container. The agent installer’s configuration is set in an XML descriptor file (config/configure.xml). The descriptor file defines the user interactions when the install, custom-install, migrate, and uninstall subcommands are run. The descriptor file also defines the tasks needed to complete installation process, such as creating the agent directory layout, creating backups for the container’s configuration files, and encrypting the agent profile’s password and saving it in the agent bootstrap configuration file plus other tasks. openssoclientsdk.jar. Although not technically a part of the Java EE policy agent, the Java EE agent bundles the OpenAM Client SDK for the container. The SDK provides the set of APIs that are designed to work with OpenAM’s service and security infrastructure. Java EE Process Flow To illustrate how Java EE policy agents work, it is first instructive to understand a simplified and generic web application example with OpenAM. While the specific configuration settings differ depending on the container or application server, the architectural components that make up the OpenAM Java EE policy agent are the same. Imagine a web application, such as an e-commerce site, deployed in multiple containers: a client application server (not fully displayed), a web container and an EJB container for the business logic. After the user is granted access to a resource through the Java EE policy agent and OpenAM, the servlet instance processes the request and determines which business logic objects or Java bean classes to invoke from the EJB container. The EJB container may have dedicated EJB components that provide specific transactions, such as sales order creation or processing. The EJB processes the transactions and retrieves any data from the database. The servlet constructs a response and then forwards a JavaServer Page (JSP) or JavaServer Face page to the client. Do not install the Java EE policy agent in the same container as OpenAM. OpenAM must be up and running before the Java EE policy agent starts. This cannot be guaranteed when both run in the same container. Open Identity Platform Community does not support configurations where OpenAM and the Java EE policy agent are installed in the same container. The following sequence diagram shows how the pieces fit together when a Java EE client accesses a resource protected by a policy agent. This diagram is simplified to show only the Java EE policy agent steps rather than to describe every possible case. The web client or user attempts to access a protected resource at www.example.com by pointing her browser to a page in a protected application. The agent filter intercepts the inbound request to the server. The agent filter authenticates the agent account and retrieves the agent profile from OpenAM. The agent profile is returned. For this example, we assume that the filter mode is set to ALL. The agent filter checks if the requested resource is on the Not-Enforced URI list. If yes, skip to step 18. The agent filter checks if the session cookie, iPlanetDirectoryPro, is present. If yes, skip to step 11. The filter redirects the client browser to the OpenAM Authentication Service, which displays a login page. The client must input their credentials. Once the client has been authenticated, create a session ID. Redirect back to the web server with a newly issued session ID, contained in the iPlanetDirectoryPro browser cookie. The request is once again intercepted by the servlet filter. The agent filter checks for the session cookie, which is found. The session cookie gets validated by OpenAM’s Session Service. If it is not valid, go back to step 5. OpenAM validates the session cookie. If the agent filter authenticates into the container’s security calm and has the correct roles assigned, then the container determines whether the user’s role is authorized to access the resource. Internal authentication is successful. The agent filter checks the URL_BASED policy in OpenAM. OpenAM’s Policy Service is called to return an authorization decision to allow the client or user access to the protected resource. The Policy Service returns an ALLOW. The agent filter writes the policy decision to an audit log. Pass through to the web resource. The web resource performs the Java EE security checks. Response returns the resource from www.example.com How Java EE Policy Agents are Configured You install Java EE policy agents in the web application containers serving web applications that you want to protect. Java EE policy agents are themselves web applications running in the container whose applications you configure OpenAM to protect. By default, the Java EE policy agent has only enough configuration at installation time to connect to OpenAM in order to get the rest of its configuration from the OpenAM configuration store. With nearly all configuration stored centrally, you can manage policy agents centrally from the OpenAM console.[1] For each web application that you protect, you also configure at least the deployment descriptor to filter requests through the policy agent. Open Identity Platform Community delivers the Java EE policy agents with a sample application .war file under j2ee_agents/container_agent/sampleapp/, which shows the configuration to use to protect your web application. In the WEB-INF/web.xml deployment descriptor file for the sample application, you find an example of the filter configuration that you must add to the deployment descriptors of your applications. You configure Java EE policy agents per OpenAM realm. Thus, to access centralized configuration, you select Realms > Realm Name > Agents > Java EE > Agent Name. Java EE policy agent configuration is distinct from policy configuration. The only policy-like configuration that you apply to Java EE policy agents is indicating which URLs in the web server can be ignored (not enforced URLs) and which client IP address are exempt from policy enforcement (not enforced IPs). For each aspect of Java EE policy agent configuration, you can configure the policy agent through the OpenAM console during testing, and then export the resulting configuration in order to script configuration in your production environment. 1. You can opt to store the agent configuration locally if necessary. Preface Java EE Policy Agent Features