Chapter 1 Read This First

Sun^TM ONE Identity Server Policy Agents, version 2.1, comprise J2EE Policy Agents and Web Policy Agents. J2EE Policy Agents enable application servers to enforce authentication and authorization using Sun^TM ONE Identity Server services. While ensuring secure client access to the hosted J2EE applications, the policy agents enforce J2EE security policies defined in the deployed application's deployment descriptors as well as URL policies defined in Sun ONE Identity Server.

In related documentation, you might see Sun ONE Identity Server referred to as Sun Java™ System Identity Server and Sun Java™ System Access Manager. These three names refer to the same product, but different versions.

This chapter provides a brief overview of J2EE Policy Agents. Topics in this chapter include:

Uses of J2EE Policy Agents

The J2EE policy agent may be installed for protecting a variety of hosted J2EE applications, which may require a varying set of security policy implementation. The security infrastructure of J2EE provides declarative as well as programmatic security that are platform-independent and are supported by all the J2EE-compliant application servers. For details on how to use J2EE platform's declarative as well as programmatic security, refer to J2EE documentation, which can be found at http://java.sun.com/j2ee.

The agent helps enable role-to-principal mapping for protected J2EE applications with Sun ONE Identity Server principals. Thus at runtime, when a J2EE policy is evaluated, it is done against the information available in Sun ONE Identity Server. Using this functionality, administrators may configure their hosted J2EE applications to be protected by the agent, which provides real security services and also other key features such as single sign-on.

Apart from enabling the J2EE security for hosted applications, the J2EE policy agents also provide complete support for Sun ONE Identity Server-based URL policies for enforcing access control over web resources hosted in the application server’s web container.

The following two sections provide examples of how the J2EE policy agents can be put to use:

The general usage examples provide usage scenarios on how most of the J2EE agents can be used to enforce access control over protected resources in J2EE application servers. The specialized agents, on the other hand, are specific to application platforms such as PeopleSoft and SAP servers which allow single sign-on and policy enforcement over such specialized resources.

General Usage Examples

An Online Auction Application

Consider a web-based application that facilitates the auction of various merchandise between interested parties. A simple implementation for such an application will require the users to be in one of three abstract roles, namely Buyer, Seller or Administrator. Buyers in this application will have access to web pages that display the listed auction items, whereas the Sellers may have access to web pages that allow them to list their merchandise for new auctions. The Administrators may have access to yet another set of web pages that allow them to finalize or cancel existing auctions in whatever state they may be in.

Using the deployment descriptors, the application developer can express this intent by protecting such components using abstract security role names. These abstract role names in turn can be mapped to real principals in Sun ONE Identity Server using the policy agent. For example, the role Buyer may be mapped to a Sun ONE Identity Server role called Employee, the role Seller to a Sun ONE Identity Server role called Vendor, and the role Administrator to a Sun ONE Identity Server role called Admin.

The abstract role names used by the application developer may be used to protect the necessary web pages and any specialized Enterprise JavaBeans (EJB) components from unauthorized access by using declarative as well as programmatic security. Once this application is deployed and configured, the agent will ensure that only the authorized personnel get access to these protected resources. For example, access to the pages meant for Sellers to list their merchandise for auctions will be granted to the user Shariff only if this user belongs to the Sun ONE Identity Server role called Vendor. Similarly, users Navaneeth and Vasanth may place bids on this listed item only if they belong to the role called Buyer. Once the auction period expires, the auction can be finalized by the user Krishnendu only if he is in the role called Admin.

A Web-Based Commerce Application

A web-based commerce application may have a variety of specialized EJB components that offer a spectrum of services to the clients. For instance, there could be a specialized component that enables to create purchase orders. Similarly, there could be a specialized component that allows to approve a purchase order. While such components provide the basic business services for the application to function, the very nature of tasks that they accomplish requires a security policy to enforce appropriate use of such services.

Using the deployment descriptors, the application vendor or developer can express this intent by protecting such components using abstract security role names. For example, there can be a role called Buyer, which protects the component that allows to create a purchase order. Similarly, there can be a role called Approver, which protects the component that enables to approve a purchase order. While these roles convey the intent of the application vendor or developer to enforce such security policies, they will not be useful unless these abstract role names are mapped to real life principals such as actual users or actual roles that reside in Sun ONE Identity Server.

The agent provides the ability to the container to enforce such a runtime linkage of abstract security roles to real life principals. Once the agent is installed and configured, the application security roles can be mapped to real principals. For example, the role Buyer can be mapped to a Sun ONE Identity Server role called Staff, and the role Approver can be mapped to a Sun ONE Identity Server role called Manager. Thus when a user Arvind tries to access the application's protected resources to create a purchase order, the agent will allow this access only if this user is a member of the mapped role Staff. Similarly, a user Maya may wish to approve this purchase order, which will be allowed by the agent only if this user is a member of the mapped role Manager.

A Content-Based Web Application

A content-based web application can offer pay per-view services. The application may be partitioned into two domains: the public domain that is accessible to anonymous users, and the private domain that is accessible only to the subscribers of this particular service. Further, the protected domain of this application can also be subject to strict conditions based on how the user has authenticated, the time of the day, IP address-based conditions and so on.

Using Sun ONE Identity Server-based URL policies for web resources, the Administrator can specify such complex policies for the application resources, which will be evaluated by the policy agent in order to ensure that access to these resources is granted only when all conditions are satisfied. The Administrator can set policies that govern access to these resources at any level of granularity - such as that for a single user or for an entire organization.

For example, one such policy may govern access to certain resources in such a manner that the user must belong to a particular LDAP Group called Customer and that the time of the day be between 9:00 am and 5:00 pm. Thus, if a user Rajeev were to access this resource, the agent will allow this access only if this user is a member of the LDAP Group Customer, and that the time of the day is between 9:00 am and 5:00 pm.

Specialized Agent Usage Examples

Policy Agent for PeopleSoft Applications

Consider an enterprise where PeopleSoft human resources and payroll applications are deployed along with other web applications. The enterprise may want to achieve single sign-on across different applications including PeopleSoft applications. This means, that on successfully logging in with sufficient credentials, the user should get seamless access to all the applications without having to re-authenticate as long as he/she is authorized to access the resource.

For example, if a user Pradeep is trying to access PeopleSoft application, he will be redirected to Sun ONE Identity Server for authentication if he is not already authenticated. On successful login, Pradeep will be allowed to access his payroll information as well as personal information from the PeopleSoft human resource application.

Policy Agent for SAP Enterprise Portal

The J2EE Policy Agent allows seamless integration of SAP Enterprise Portal and its hosted portal applications and content with Sun ONE Identity Server and allows the administrators to enforce stricter access control policies, where necessary. It also allows for a very flexible mode of mapping Sun ONE Identity Server users to users as they exist in the SAP back-end system or Enterprise Portal user base. One way to map the Sun ONE Identity Server users with SAP Enterprise Portal users is to configure the agent to use the same user ID across both the systems. For example, if the user Rajesh signs on to Sun ONE Identity Server using a user ID rajesh, the agent when configured to map the same user IDs will log him into the SAP Enterprise Portal as rajesh.

In situations where it is not possible to map the same user ID across Identity Server and SAP Enterprise Portal, the agent may be configured to use a mapped user ID from the LDAP attribute of the Identity Server user. For instance, if a user Sushma has the value sushmac stored in a particular profile attribute, which the agent has been configured to read, then she will be logged into Enterprise Portal as user sushmac by the agent when she accesses the Enterprise Portal resources.

The agent also allows a third mode of mapping users of Identity Server to users in SAP Enterprise Portal, which is by using the value of a specified HTTP Header field. Thus if a user Amlan requests access to a protected Enterprise Portal resource, and this request carries with it a value amlanc in an HTTP header field that the agent has been configured to read, then the agent will log him into the SAP Enterprise Portal as user amlanc.

The agent for SAP Enterprise Portal can also be used to enforce URL Policies defined in Identity Server’s console to control access to the protected Enterprise Portal resources. For example the administrator may define a set of URL Policies in the Identity Server such that these policies will allow access to a particular URL resource in Enterprise Portal to the user Frances and not to the user Deepak. In this case, regardless of the access control set up within Enterprise Portal for the resource in question, the agent will only allow access to the user Frances for that particular resource and not for the user Deepak. Furthermore, the administrator can also set up URL policies with various conditions and authentication levels or scheme requirements for such resources. As an example, the administrator may create a policy for user Bill such that the access to a particular Enterprise Portal resource is restricted to a particular time of the day only. In this case, the user Bill will be allowed access to the given resource only during the allowed interval and will be denied access at all other times.

Policy Agent for SAP Enterprise Portal and Web Application Server

The Policy Agent for SAP Enterprise Portal and Web Application Server is similar to the Policy Agent for SAP Enterprise Portal in that they both:

However, Policy Agent for SAP Enterprise Portal and Web Application Server is different from Policy Agent for SAP Enterprise Portal since between the two only Policy Agent for SAP Enterprise Portal and Web Application Server allows the establishment of Identity Server principals within the applications hosted on the underlying SAP Web Application Server.

For example, when a user attempts to access an application that is hosted on SAP Web Application Server and is protected by Policy Agent for SAP Enterprise Portal and Web Application Server, the policy agent ensures user authentication and enforces any applicable URL policies defined within Identity Server. This authentication and enforcement by the agent establishes the principal within the SAP Web Application Server for the protected application. And yet, to ensure complete protection of hosted resources, the administrator of SAP Web Application Server needs to define the necessary protection domains, resource protection policies and constraints within the SAP Administrator as well as the deployed application.

Policy Agent for BEA WebLogic 8.1 Server/Portal

This J2EE agent was developed with the objective of protecting J2EE web applications deployed on BEA WebLogic 8.1 SP2/SP3 Server (BEA WebLogic SP2 Server or BEA WebLogic SP3 Server) and on BEA WebLogic 8.1 SP2/SP3 Portal (BEA WebLogic SP2 Portal or BEA WebLogic SP3 Portal). In this document, the agent is commonly referred to as WebLogic 8.1 Server/Portal Agent.

This particular section describes a few use cases for this agent when installed specifically on WebLogic 8.1 Portal. Users are allowed to access a WebLogic 8.1 Portal application if their user profile is present in both Identity Server and the WebLogic 8.1 Portal repository. Administrators must ensure that users who can log into the WebLogic Portal are also present in Identity Server. Users who are not present in either of the two repositories should be denied access to any resource they try to access.

Note that after installing and configuring the agent for a portal application, the content management of the portal application is still performed by the WebLogic 8.1 Portal framework. The J2EE agent simply achieves single sign on by authenticating the user with Identity Server and by establishing the user principal in the portal container. The agent also supports synchronization of the Identity Server and WebLogic 8.1 Portal sessions through a logout event trapping feature.

This agent allows for a very flexible mode of mapping Sun ONE Identity Server users to users as they exist in the WebLogic 8.1 Portal repository. One way to map the Sun ONE Identity Server users with WebLogic 8.1 Portal users is to configure the agent to use the same user ID across both systems. For example, if the user JinWon signs on to Sun ONE Identity Server using a user ID jinwon, the agent—when configured to map the same user ID—logs him into the WebLogic 8.1 Portal as jinwon.

In situations where it is not possible to map the same user ID across Identity Server and the WebLogic 8.1 Portal, the agent can be configured to use a mapped user ID from the LDAP attribute of the Identity Server user. For instance, if a user Gina has the value Ginak stored in a particular profile attribute that the agent has been configured to read then she will be logged into WebLogic 8.1 Portal as user Ginak by the agent when she accesses the WebLogic 8.1 Portal resources.

The agent also allows a third mode of mapping users of Identity Server to users in the WebLogic 8.1 Portal, by using the value of a specified HTTP Header field. Thus if a user BethAnn requests access to a protected WebLogic 8.1 Portal resource, and this request carries with it a value bethann in an HTTP header field that the agent has been configured to read, then the agent will log her into the WebLogic 8.1 Portal as user bethann.

The agent for the WebLogic 8.1 Portal can also be used to enforce URL Policies defined in Identity Server’s console to control access to the protected WebLogic 8.1 Portal. For example the administrator can define a set of URL Policies in the Identity Server such that these policies allow access to a particular URL resource in the WebLogic 8.1 Portal to the user Rachel and not to the user David. In this case, regardless of the access control set up within WebLogic 8.1 Portal for the resource in question, the agent only allows access to Rachel for that particular resource and not for David. Furthermore, the administrator can also set up URL policies with various conditions and authentication levels or scheme requirements for such resources.

How J2EE Policy Agents Work

J2EE Policy Agents contain two main components that together affect the operation of the application server as well as the behavior of the protected applications. These components are as follows:

Agent Realm

The agent realm is installed as an application server-specific platform component, which provides the ability to the application server to interact with principals stored in Sun ONE Identity Server. This component needs to be configured correctly in order that the agent can be used to enforce J2EE Security policies for the protected application. This component is needed for enforcing J2EE policies for the protected application.



Note	Because the agent realm component is installed as an application server-specific component, it may be named differently for different agents. For example, it is called custom registry for IBM WebSphere 5.0/5.1 agent, and agent authentication provider for BEA WebLogic 7.0 SP2 and 8.1 agents.

Agent Filter

The agent filter is installed within the protected application and facilitates the enforcement of the security policies governing the access to all resources within the protected application. Every application that has to be protected by the agent must have its deployment descriptors changed to reflect that it is configured to use the agent filter. Applications that do not have this setting will not be protected by the agent and may malfunction or become unusable if deployed on an application server where the agent realm is installed.



Note	For application servers that do not support Servlet Filters as defined in the Servlet 2.3 specification, the agent filter may be named and packaged differently. For example, the agent filter is referred to as the authfilter for the WebLogic front-end server used with PeopleSoft 8.3 server.

Together, the agent realm and agent filter work in tandem with Sun ONE Identity Server and enforce authentication and authorization for clients trying to access protected J2EE applications by enforcing the J2EE security policies as well as Sun ONE Identity Server-based URL policies where applicable.

The agent provides a fully configured and ready-to-use client installation of Sun ONE Identity Server SDK for the application server. This SDK offers a rich set of APIs supported by Sun ONE Identity Server that can be used to create security-aware applications that are tailored to work in the security framework offered by Sun ONE Identity Server. For more information on how to use Sun Java System Identity Server SDK, please refer to Sun Java System Identity Server Programmer’s Guide.

PeopleSoft 8.3/8.4/8.8 Agent Architecture

The policy agent for PeopleSoft 8.3, 8.4 and 8.8 protects web access to PeopleSoft applications using Sun ONE Identity Server security features such as authentication, single sign-on and policy.

PeopleSoft applications are web-enabled through PeopleSoft Internet Architecture (PIA) that involves deploying PeopleSoft servlets on a web/application server (WebLogic) tier, which fronts the PeopleSoft proprietary application server. The policy agent can either be installed on the web/application server or on a web container that acts as proxy to the PeopleSoft web/application server.

The policy agent for PeopleSoft is based on the Sign-on PeopleCode provided by PeopleSoft. For more information on this infrastructure, see Chapter 7 of the Security PeopleBook that is part of the PeopleSoft documentation.

The policy agent code on the user’s web/application server (either the proxy or the PeopleSoft-provided web/application server) works like a regular Sun ONE Identity Server web agent. It intercepts all the user-requests and is responsible for authenticating and authorizing web access to the PeopleSoft application based on the authentication schemes and policies defined in Sun ONE Identity Server.

The PeopleSoft configuration, required for the agent to work, involves the following three steps:

The rest of PeopleSoft configuration, specifically the existing PeopleSoft user repository, user profiles and PeopleSoft roles based access control do not need any changes, and work exactly like before.

The current implementation of identifying the user to PeopleSoft assumes that Sun ONE Identity Server and PeopleSoft separately maintain users, and a pre-determined LDAP attribute in the Sun ONE Identity Server user’s entry contains the PeopleSoft userid. User synchronization between the two user repositories is beyond the scope of Sun ONE Identity Server or the Sun ONE Identity Server Policy Agent. While continuing to support this form of mapping, future implementations will provide support for installations that have a single user LDAP repository shared between Sun ONE Identity Server and PeopleSoft.

Supported Servers

J2EE Policy Agents, versions 2.1 and 2.1.1 are available for the following servers. These versions of the agents work with Sun ONE Identity Server 6.0 SP1, 6.1 and 6.2. The agent supported on Solaris 8 is generally supported on Solaris 9 also and vice versa.


Note	J2EE Policy Agents support only specific versions of Oracle 9iAS and Oracle 10g application servers as listed in the following table. Hence, before installing the agent for Oracle 9iAS or Oracle 10g, be sure to check the exact version of the application server from the property named Version in the file ORACLE_HOME/config/ias.properties.

Table 1-1 Servers Supported by J2EE Policy Agents *(1 of 3)*
Server	Platform	Agent Version Available
Sun ONE Application Server 7.0	Solaris 8	2.1, 2.1.1
	Solaris 9	2.1, 2.1.1
	Microsoft Windows 2000	2.1, 2.1.1
	Red Hat Advanced Server 2.1	2.1, 2.1.1
BEA WebLogic Server 6.1 SP2	Solaris 8	2.1, 2.1.1
	Solaris 9	2.1, 2.1.1
	HP-UX 11	2.1, 2.1.1
	Microsoft Windows 2000	2.1, 2.1.1
BEA WebLogic Server 7.0 SP2	Solaris 8	2.1
	Solaris 9	2.1
	Red Hat Advanced Server 2.1	2.1
	HP-UX 11.11	2.1
IBM WebSphere Application Server 5.0	Solaris 8	2.1, 2.1.1
	Microsoft Windows 2000	2.1, 2.1.1
	AIX 5.1	2.1
	AIX 5.2	2.1.1
	Red Hat Advanced Server 2.1	2.1.1
PeopleSoft 8.3/8.4/8.8	Solaris 8	2.1
	HP-UX 11	2.1
BEA WebLogic Server 8.1	Solaris 8	2.1
	Solaris 9	2.1
	Red Hat Advanced Server 2.1	2.1
	HP-UX 11.11	2.1
Apache Tomcat Server 4.1.27	Solaris 8	2.1
	Solaris 9	2.1
	Red Hat Advanced Server 2.1	2.1
Oracle 9i Application Server Release 2 (version 9.0.3)	Solaris 8	2.1
SAP Enterprise Portal 6.0 SP2	Solaris 8	2.1
	Solaris 9	2.1
	AIX 5.2	2.1
Oracle Application Server 10g (versions 9.0.3 and 9.0.4)	Solaris 8	2.1
Macromedia JRun 4 Application Server	Solaris 8	2.1, 2.1.1
	Solaris 9	2.1, 2.1.1
	Red Hat Enterprise Linux 3.0	2.1, 2.1.1
SAP Enterprise Portal 6.0 SP2 and Web Application Server 6.20 SP1	Microsoft Windows Server 2003 Enterprise Edition	2.1
BEA WebLogic 8.1 SP2 Server/Portal	Solaris 8	2.1
	Solaris 9	2.1
BEA WebLogic 8.1 SP3 Server/Portal	Red Hat Enterprise Linux AS 3.0	2.1
	Solaris 8	2.1
	Solaris 9	2.1
IBM WebSphere Application Server 5.1	Solaris 8	2.1.1
Sun Java™ System Application Server 8.1	Solaris 8	2.1
	Solaris 9	2.1
	Solaris 10	2.1
	Solaris 9 x86	2.1
	Red Hat Advanced Server 2.1	2.1

What’s New in J2EE Policy Agents

J2EE Policy Agents support a variety of new features. Some of the features require application configuration as well as agent configuration in order to be used correctly. Make sure that you read the chapters on installation and agent configuration to ensure the proper usage of these features.

URL Policy Support

This release of J2EE Policy Agents provides complete support for Sun ONE Identity Server-based URL policies that can be used to protect web-tier resources such as URLs that may point to servlets, JSPs, HTML files, images and other types of web-tier resources.

Web-Tier Declarative Security Support

The web-tier declarative security implies the use of deployment descriptors to control access for various web-tier resources such as servlets, JSPs, HTML files, images and so on. The policy agents help enforce such access control in the application server by establishing linkage between abstract role names used in the deployment descriptors of such web applications with real principals as available in the Sun ONE Identity Server.

Other Features

This release of J2EE Policy Agents also has a host of other new features that can be used to better secure your deployed applications as well as customize the agent environment for best use in your deployment. Complete details of these features and how best to use them are available in the following chapters. A brief list of these features is as follows:

Differences Between J2EE Policy Agents and Web Policy Agents

If you have already used or are planning to use both J2EE Policy Agents and Web Policy Agents, you need to familiarize yourself with certain key differences between these two types of agents. Typically, the Web Policy Agents are used to protect resources hosted on web servers or enforce Single Sign-On with systems that use web servers as front-end in an environment secured by an Identity Server deployment. On the other hand, the J2EE Policy Agents are used to protect resources hosted on J2EE Application Servers or enforce Single Sign-On with systems that use J2EE Application Servers as their underlying infrastructure in an environment secured by an Identity Server deployment.

While the primary purpose of both these types of agents is to enforce authentication and authorization before a user can access a protected resource, they differ greatly in the kind of resources that they can protect, in the way they enforce such policy decisions, and in the way they can be configured to provide support for features that are solely applicable to the kind of servers they protect.

Differences in Protected Resources

The Web Policy Agents are capable of protecting resources that can be hosted on the web servers that they are installed on. This includes any resource that can be represented as a URI that is available on the protected web server. Such a protected URI can be resolved by the web server to static content files such as HTML files or dynamic content generation programs such as CGI scripts or servlets hosted by an embedded servlet engine. In other words, before a request is evaluated by the web server, the Web Policy Agent can evaluate the necessary credentials of a user and can allow or deny access for the requested resource. Once the request is granted access to the resource, it can be processed internally by the web server as applicable. In other words, the Web Policy Agent uses the request URL to enforce all policy decisions regardless of what that URL maps to internally in the web server. In cases where the request URL maps to a servlet which in turn invokes other servlets or JSPs, the Web Policy Agent will not intercept these subsequent resource requests unless such invocation involves a client side redirect.

On the other hand, a J2EE Policy Agent is capable of protecting web and enterprise applications hosted by the application server on which it is installed. These applications may include resources such as HTML pages, servlets, JSPs, and EJBs. Apart from these resources, any resource that can be accessed as a URI within a protected web application can also be secured by such agents. For example, images that are packaged within a web application can also be protected by the J2EE Policy Agents. These agents allow the evaluation of J2EE policies and can also enforce Identity Server based URL policies like a Web Policy Agent on the resources being requested by the user. Minimally the enforcement is done at the outermost requested URL, but can also be done on any intermediate URLs being chained to this resource on most application servers.

Default Scope of Protection

When installed, a Web Policy Agent automatically protects the entire set of resources available on the web server. However, in order to protect resources within a web application hosted on an application server, the web application must be configured to use the J2EE Policy Agent. Thus if multiple web applications are hosted on an application server on which a J2EE Policy Agent has been installed, only the web applications that have been specifically configured to use the J2EE Policy Agent will be protected by the agent. Other applications will remain unprotected and can potentially malfunction if they depend upon any J2EE security mechanism.

Further, the J2EE Policy Agent can only protect resources that are packaged within a web or enterprise application. Certain application servers provide an embedded web server that may be used to host non-packaged web content such as HTML files and images. Such content cannot be protected by a J2EE Policy Agent unless it is redeployed as a part of a web application.

Modes of Operation

The J2EE Policy Agents provide an explicit control over various modes of operation. Some of these modes such as SSO_ONLY and URL_POLICY are also achievable in Web Policy Agents, where as other modes of operation such as J2EE_POLICY and ALL modes do not apply to Web Policy Agents. In these later modes of operation, the J2EE Policy Agent enforces J2EE declarative policies as applicable for the protected application and also provide support for evaluation of programmatic security APIs available within the J2EE specifications.

Different Configuration Properties

The properties that control the operation of J2EE Policy Agents are different from the properties that control the operation of Web Policy Agents. While some properties facilitate the configuration of same or similar features, they may not share the same name, value or format of specification. Apart from the difference in property names, there may be properties that apply only to one type of agents and not to the other.