J2EE Policy Agents Guide |
Appendix B
Sample Application ScenarioThis appendix is divided into two broad sections:
The sample application presented in this section consists of a web module and an EJB Module.
The web module consists of the following two servlets:
The EJB Module consists of a single EJB with two methods:
Standard Deployment DescriptorsThe following deployment descriptors are common to all J2EE servers:
web.xml
Note
Concerning the Filter Class in the web.xml File
- The filter class for Sun ONE Application Server 7.0, BEA WebLogic Server 6.1 SP2, BEA WebLogic Server 7.0 SP2, BEA WebLogic Server 8.1 and Macromedia JRun 4 is as follows: com.sun.identity.agents.filter.AmAgentFilter.
- The following filter class applies to both IBM WebSphere Application Server 5.0 and 5.1: com.sun.identity.agents.websphere.AmWAS50AgentFilter.
Note
Concerning the Dispatcher Element in the web.xml File
If you are using Sun Java System Application Server 8.1 as your application server, be aware that this application server supports the Java Servlet Specification version 2.4, which requires you to update the standard deployment descriptors for the Agent for Sun Java System Application Server 8.1.
A new dispatcher element has been added to the filter-mapping element in servlet 2.4. The agent filter requires the dispatcher element with values REQUEST, FORWARD, INCLUDE, and ERROR in the Sun Java System Application Server 8.1 Agent. See the Post Installation Tasks section, specifically "Agent for Sun Java System Application Server 8.1" for more information.
The following is a sample Servlet 2.4 compliant web.xml descriptor with the <filter>, <filter-mapping>, and <dispatcher> elements added:
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
<display-name>...</display-name>
<description>...</description>
<filter>
<filter-name>Agent</filter-name>
<display-name>Agent</display-name>
<description>Sun Java System Access Manager Policy Agent Filter </description>
<filter-class>com.sun.identity.agents.filter.AmAgentFilter</filter-class>
</filter>
<filter-mapping id="FilterMapping_PolicyAgent">
<filter-name>Agent</filter-name>
<dispatcher>REQUEST</dispatcher>
<dispatcher>INCLUDE</dispatcher>
<dispatcher>FORWARD</dispatcher>
<dispatcher>ERROR</dispatcher>
<url-pattern>/*</url-pattern>
</filter-mapping>
...
...
</web-app>
ejb-jar.xml
Code Example B-2 ejb-jar.xml
<?xml version="1.0"?>
<!DOCTYPE ejb-jar PUBLIC
"-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN"
"http://java.sun.com/dtd/ejb-jar_2_0.dtd">
<ejb-jar id="ID_ejb_jar">
<enterprise-beans>
<session id="Session_ReportEJB">
<ejb-name>ReportEJB</ejb-name>
<home>com.example.reportapp.ReportEJBHome</home>
<remote>com.example.reportapp.ReportEJB</remote>
<ejb-class>com.example.reportapp.ReportEJBImpl</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
</session>
</enterprise-beans>
<assembly-descriptor>
<security-role id="ID_MANAGER_ROLE">
<role-name>MANAGER-ROLE</role-name>
</security-role>
<security-role id="ID_EMPLOYEE_ROLE">
<role-name>EMPLOYEE-ROLE</role-name>
</security-role>
<method-permission>
<role-name>MANAGER-ROLE</role-name>
<method>
<ejb-name>ReportEJB</ejb-name>
<method-intf>Remote</method-intf>
<method-name>doDetailedReport</method-name>
<method-params/>
</method>
</method-permission>
<method-permission>
<role-name>MANAGER-ROLE</role-name>
<role-name>EMPLOYEE-ROLE</role-name>
<method>
<ejb-name>ReportEJB</ejb-name>
<method-intf>Remote</method-intf>
<method-name>doSummaryReport</method-name>
<method-params/>
</method>
</method-permission>
</assembly-descriptor>
</ejb-jar>
application.xml
Code Example B-3 application.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE application PUBLIC
"-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN"
"http://java.sun.com/dtd/application_1_3.dtd" >
<application id="APP_REPORTAPP">
<display-name>Sample Report Application</display-name>
<description>Sample Report Application to illustrate J2EE Security</description>
<module id="em_reportapp">
<ejb>reportapp.jar</ejb>
</module>
<module id="wm_reportapp">
<web>
<web-uri>reportapp.war</web-uri>
<context-root>ReportApp</context-root>
</web>
</module>
<security-role id="ID_MANAGER_ROLE">
<role-name>MANAGER-ROLE</role-name>
</security-role>
<security-role id="ID_EMPLOYEE_ROLE">
<role-name>EMPLOYEE-ROLE</role-name>
</security-role>
</application>
Assembly DescriptorsThis section provides samples of descriptors for:
Sun ONE Application Server 7.0
The following are samples of deployment descriptors to support Declarative (at Web and EJB tier) and Programmatic security for Sun One Application Server 7.0:
These samples are not exhaustive and the user should refer to Sun ONE Application Server reference documentation to learn the details on how these descriptors may be edited to create the role-to-principal mappings:
http://docs.sun.com/source/816-7149-10/index.html
sun-web.xml
Code Example B-4 sun-web.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7.0 Servlet 2.3//EN' 'http://www.sun.com/software/sunone/appserver/dtds/sun-web-app_2_3-0.dtd'>
<!-- Copyright 2002 Sun Microsystems, Inc. All rights reserved. -->
<sun-web-app>
<security-role-mapping>
<role-name>MANAGER-ROLE</role-name>
<group-name>manager</group-name>
</security-role-mapping>
<security-role-mapping>
<role-name>EMPLOYEE-ROLE</role-name>
<group-name>employee</group-name>
</security-role-mapping>
</sun-web-app>
sun-ejb-jar.xml
Code Example B-5 sun-ejb-jar.xml
<?xml version="1.0"?>
<!DOCTYPE sun-ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7.0 EJB 2.0//EN' 'http://www.sun.com/software/sunone/appserver/dtds/sun-ejb-jar_2_0-0.dtd'>
<sun-ejb-jar>
<enterprise-beans>
<ejb>
<ejb-name>ReportEJB </ejb-name>
<jndi-name>ReportEJB </jndi-name>
</ejb>
</enterprise-beans>
</sun-ejb-jar>
sun-application.xml
Code Example B-6 sun-application.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-application PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7.0 J2EE Application 1.3//EN' 'http://www.sun.com/software/sunone/appserver/dtds/sun-application_1_3-0.dtd'>
<sun-application>
<security-role-mapping>
<role-name>MANAGER-ROLE</role-name>
<group-name>manager</group-name>
</security-role-mapping>
<security-role-mapping>
<role-name>EMPLOYEE-ROLE</role-name>
<group-name>employee</group-name>
</security-role-mapping>
</sun-application>
BEA WebLogic 6.1 SP2
The following are samples of deployment descriptors to support declarative (at Web and EJB tier) and programmatic security for BEA WebLogic 6.1SP2.
These samples are not exhaustive and the user should refer to the BEA WebLogic 6.1SP2 reference documentation to learn the details on how these descriptors may be edited to create the role-to-principal mappings:
http://e-docs.bea.com/wls/docs61/programming.html
weblogic.xml
Code Example B-7 weblogic.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE weblogic-web-app PUBLIC "-//BEA Systems, Inc.//DTD Web Application 6.0//EN" "http://www.bea.com/servers/wls600/dtd/weblogic-web-jar.dtd">
<weblogic-web-app>
<description>WebLogic Descriptor</description>
<security-role-assignment>
<role-name>MANAGER-ROLE</role-name>
<principal-name>manager</principal-name>
</security-role-assignment>
<security-role-assignment>
<role-name>EMPLOYEE-ROLE</role-name>
<principal-name>employee</principal-name>
</security-role-assignment>
</weblogic-web-app>
weblogic-ejb-jar.xml
Code Example B-8 weblogic-ejb-jar.xml
<?xml version="1.0"?>
<!DOCTYPE weblogic-ejb-jar PUBLIC '-//BEA Systems, Inc.//DTD WebLogic 6.0.0 EJB//EN' 'http://www.bea.com/servers/wls600/dtd/weblogic-ejb-jar.dtd'>
<weblogic-ejb-jar>
<weblogic-enterprise-bean>
<ejb-name>ReportEJB </ejb-name>
<jndi-name>ReportEJB </jndi-name>
</weblogic-enterprise-bean>
<security-role-assignment>
<role-name>MANAGER-ROLE</role-name>
<principal-name>manager</principal-name>
</security-role-assignment>
<security-role-assignment>
<role-name>EMPLOYEE-ROLE</role-name>
<principal-name>employee</principal-name>
</security-role-assignment>
</weblogic-ejb-jar>
IBM WebSphere Application Server 5.0/5.1
The following are samples of deployment descriptors to support declarative (at Web and EJB tier) and programmatic security for IBM WebSphere Application Server 5.0/5.1:
These samples are not exhaustive and the user should refer to the IBM WebSphere Application Server 5.0/5.1 reference documentation to learn how these descriptors may be edited to create the role-to-principal mappings:
http://publib7b.boulder.ibm.com/webapp/wasinfo1/index.jsp?deployment=ApplicationServer&lang=en
ibm-web-bnd.xmi
Code Example B-9 bm-web-bnd.xmi
<?xml version="1.0" encoding="UTF-8"?>
<webappbnd:WebAppBinding xmi:version="2.0"
xmlns:xmi="http://www.omg.org/XMI"
xmlns:webappbnd="webappbnd.xmi"
xmlns:webapplication="webapplication.xmi"
xmi:id="WebAppBinding_1"
virtualHostName="default_host">
<webapp href="WEB-INF/web.xml#WEBAPP_REPORT"/>
</webappbnd:WebAppBinding>
ibm-web-ext.xmi
Code Example B-10 ibm-web-ext.xmi
<?xml version="1.0" encoding="UTF-8"?>
<webappext:WebAppExtension xmi:version="2.0"
xmlns:xmi="http://www.omg.org/XMI"
xmlns:webappext="webappext.xmi"
xmlns:webapplication="webapplication.xmi"
xmi:id="WebAppExtension_1">
<webApp href="WEB-INF/web.xml#WEBAPP_REPORT"/>
<extendedServlets xmi:id="Servlet_SummaryReport_Ext">
<extendedServlet href="WEB-INF/web.xml#Servlet_SummaryReport"/>
</extendedServlets>
<extendedServlets xmi:id="Servlet_DetailedReport_Ext">
<extendedServlet href="WEB-INF/web.xml#Servlet_DetailedReport"/>
</extendedServlets>
</webappext:WebAppExtension>
ibm-ejb-jar-bnd.xmi
Code Example B-11 ibm-ejb-jar-bnd.xmi
<?xml version="1.0" encoding="UTF-8"?>
<ejbbnd:EJBJarBinding xmi:version="2.0"
xmlns:xmi="http://www.omg.org/XMI"
xmlns:ejbbnd="ejbbnd.xmi"
xmlns:ejb="ejb.xmi"
xmi:id="EJBJarBinding_1">
<ejbJar href="META-INF/ejb-jar.xml#ID_ejb_jar"/>
<ejbBindings xmi:id="Session_ReportEJB_Bnd" jndiName="ReportEJB">
<enterpriseBean xmi:type="ejb:Session"
href="META-INF/ejb-jar.xml#Session_ReportEJB"/>
</ejbBindings>
</ejbbnd:EJBJarBinding>
ibm-ejb-jar-ext.xmi
Code Example B-12 ibm-ejb-jar-ext.xmi
<?xml version="1.0" encoding="UTF-8"?>
<ejbext:EJBJarExtension xmi:version="2.0"
xmlns:xmi="http://www.omg.org/XMI"
xmlns:ejbext="ejbext.xmi"
xmlns:ejb="ejb.xmi"
xmi:id="EJBJarExtension_1">
<ejbExtensions xmi:type="ejbext:SessionExtension"
xmi:id="SessionExtension_1"
name="SessionExtension_1">
<enterpriseBean xmi:type="ejb:Session"
href="META-INF/ejb-jar.xml#Session_ReportEJB"/>
</ejbExtensions>
<ejbJar href="META-INF/ejb-jar.xml#ID_ejb_jar"/>
</ejbext:EJBJarExtension>
ibm-application-bnd.xmi
Code Example B-13 ibm-application-bnd.xmi
<?xml version="1.0" encoding="UTF-8"?>
<applicationbnd:ApplicationBinding xmi:version="2.0"
xmlns:xmi="http://www.omg.org/XMI"
xmlns:applicationbnd="applicationbnd.xmi"
xmlns:common="common.xmi"
xmlns:application="application.xmi"
xmi:id="ApplicationBinding_1">
<authorizationTable xmi:id="AuthorizationTable_1">
<authorizations xmi:id="RoleAssignment_1">
<role href="META-INF/application.xml#ID_EMPLOYEE_ROLE"/>
<groups xmi:id="Group_1" name="employee"/>
</authorizations>
<authorizations xmi:id="RoleAssignment_2">
<role href="META-INF/application.xml#ID_MANAGER_ROLE"/>
<groups xmi:id="Group_2" name="manager"/>
</authorizations>
</authorizationTable>
<application href="META-INF/application.xml#APP_REPORTAPP"/>
</applicationbnd:ApplicationBinding>
ibm-application-ext.xmi
Code Example B-14 ibm-application-ext.xmi
<?xml version="1.0" encoding="UTF-8"?>
<applicationext:ApplicationExtension xmi:version="2.0"
xmlns:xmi="http://www.omg.org/XMI"
xmlns:applicationext="applicationext.xmi"
xmlns:application="application.xmi"
xmi:id="ApplicationExtension_1">
<moduleExtensions xmi:type="applicationext:EjbModuleExtension"
xmi:id="EjbModuleExtension_1"
altRoot="ALT-INF/reportapp.jar">
<module xmi:type="application:EjbModule"
href="META-INF/application.xml#em_reportapp"/>
</moduleExtensions>
<moduleExtensions xmi:type="applicationext:WebModuleExtension"
xmi:id="WebModuleExtension_1"
altRoot="ALT-INF/reportapp.war">
<module xmi:type="application:WebModule"
href="META-INF/application.xml#wm_reportapp"/>
</moduleExtensions>
<application href="META-INF/application.xml#APP_REPORTAPP"/>
</applicationext:ApplicationExtension>
BEA WebLogic Server 7.0 SP2 and BEA WebLogic Server 8.1
The following are samples of deployment descriptors to support declarative (at Web and EJB tier) and programmatic security for BEA WebLogic Server 7.0 SP2 or BEA WebLogic Server 8.1:
These samples are not exhaustive and the user should refer to the BEA WebLogic Server reference documentation to learn how these descriptors may be edited to create the role-to-principal mappings.
BEA WebLogic Server 7.0 related documentation:
http://e-docs.bea.com/wls/docs70/programming.html
BEA WebLogic Server 8.1 related documentation
http://e-docs.bea.com/wls/docs81/index.html
weblogic.xml
Code Example B-15 weblogic.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE weblogic-web-app PUBLIC "-//BEA Systems, Inc.//DTD Web Application 7.0//EN" "http://www.bea.com/servers/wls700/dtd/weblogic700-web-jar.dtd">
<weblogic-web-app>
<description>WebLogic Descriptor</description>
<security-role-assignment>
<role-name>MANAGER-ROLE</role-name>
<principal-name>manager</principal-name>
</security-role-assignment>
<security-role-assignment>
<role-name>EMPLOYEE-ROLE</role-name>
<principal-name>employee</principal-name>
</security-role-assignment>
</weblogic-web-app>
weblogic-ejb-jar.xml
Code Example B-16 weblogic-ejb-jar.xml
<?xml version="1.0"?>
<!DOCTYPE weblogic-ejb-jar PUBLIC '-//BEA Systems, Inc.//DTD WebLogic 7.0.0 EJB//EN' 'http://www.bea.com/servers/wls700/dtd/weblogic-ejb-jar.dtd'>
<weblogic-ejb-jar>
<weblogic-enterprise-bean>
<ejb-name>ReportEJB </ejb-name>
<jndi-name>ReportEJB </jndi-name>
</weblogic-enterprise-bean>
<security-role-assignment>
<role-name>MANAGER-ROLE</role-name>
<principal-name>manager</principal-name>
</security-role-assignment>
<security-role-assignment>
<role-name>EMPLOYEE-ROLE</role-name>
<principal-name>employee</principal-name>
</security-role-assignment>
</weblogic-ejb-jar>
Apache Tomcat Server 4.1.27
The following is a sample of deployment descriptors to support Declarative and Programmatic security for Apache Tomcat Server 4.1.27.
Tomcat Server 4.1.27 does not include an EJB Container hence there is no support for EJBs. All security constraints and role-to-principal mappings are contained within the web application descriptor file. A separate role-to-principal mapping file is not needed for Tomcat Server. These samples are not exhaustive and the user should refer to the standard J2EE security guide at the following location for additional details.
http://java.sun.com/j2ee/tutorial/1_3-fcs/doc/Security.html
web.xml
Code Example B-17 web.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<servlet id="SampleServlet">
<servlet-name>SampleServlet</servlet-name>
<display-name>SampleServlet</display-name>
<description>A Sample Servlet</description>
<servlet-class>test.SampleServlet</servlet-class>
<security-role-ref>
<role-name>MANAGER-ROLE</role-name>
<role-link>manager</role-link>
</security-role-ref>
</servlet>
<security-constraint>
<web-resource-collection>
<web-resource-name>Protected</web-resource-name>
<url-pattern>*.jsp</url-pattern>
<url-pattern>*.html</url-pattern>
</web-resource-collection>
<auth-constraint>
<!-- Anyone with one of the listed roles may access this area -->
<role-name>manager</role-name>
</auth-constraint>
</security-constraint>
<security-role id="MANAGER-ROLE">
<description> The role that is required to access this sample application </description>
<role-name>manager</role-name>
</security-role>
</web-app>
Macromedia JRun 4
The standard deployment descriptors defined in the section Standard Deployment Descriptors to support Declarative and Programmatic security will work for Macromedia JRun 4 and a separate role-to-principal mapping file is not required.
Oracle 9iAS R2 and Oracle 10g
The following are samples of deployment descriptors to support declarative (at Web and EJB tier) and programmatic security for Oracle 9iAS R2 and Oracle 10g.
These samples are not exhaustive and the user should refer to Oracle documentation to learn the details on how these descriptors may be edited to create the role-to-principal mappings:
http://otn.oracle.com/documentation/ias.html
orion-web.xml
Code Example B-18 orion-web.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE orion-web-app PUBLIC "-//Evermind//DTD Orion Web Application 2.3//EN" "http://xmlns.oracle.com/ias/dtds/orion-web.dtd">
<orion-web-app deployment-version="1.0.2.2"
jsp-cache-directory="./persistence"
temporary-directory="./temp"
servlet-webdir="/servlet/">
</orion-web-app>
orion-ejb-jar.xml
Code Example B-19 orion-ejb-jar.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE orion-ejb-jar PUBLIC "-//Evermind//DTD Enterprise JavaBeans 1.1 runtime//EN" "http://www.orionserver.com/dtds/orion-ejb-jar.dtd">
<orion-ejb-jar>
<enterprise-beans>
<session-deployment name="ReportEJB" location="ReportEJB" />
</enterprise-beans>
</orion-ejb-jar>
orion-application.xml
Code Example B-20 orion-application.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE orion-application PUBLIC "-//Evermind//DTD J2EE Application runtime 1.2//EN" "http://xmlns.oracle.com/ias/dtds/orion-application.dtd">
<orion-application deployment-version="1.0.2.2">
<web-module id="WebTestSuite" path="War_File_Name.war" />
<ejb-module id="EJBTestSuite" path="EJB_File_Name.jar" />
<security-role-mapping name="MANAGER-ROLE">
<group name="manager" />
</security-role-mapping>
<security-role-mapping name="EMPLOYEE-ROLE">
<group name="employee" />
</security-role-mapping>
<persistence path="persistence"/>
<user-manager class="com.sun.identity.agents.oracle.AmOracleUserManager">
</user-manager>
<log>
<file path="application.log"/>
</log>
<namespace-access>
<read-access>
<namespace-resource root="">
<security-role-mapping name="<jndi-user-role>">
<group name="administrators"/>
</security-role-mapping>
</namespace-resource>
</read-access>
<write-access>
<namespace-resource root="">
<security-role-mapping name="<jndi-user-role>">
<group name="administrators"/>
</security-role-mapping>
</namespace-resource>
</write-access>
</namespace-access>
</orion-application>
Note
If the user does not add the custom User Manager tag, it will be added by default when deploying the application through Enterprise Manager.
Sun Java System Application Server 8.1
The following are samples of deployment descriptors to support Declarative (at Web and EJB tier) and Programmatic security for Sun Java System Application Server 8.1:
Update the DTD files in each of these deployment descriptors for Sun Java System Application Server 8.1. Keep in mind, that these samples are not exhaustive and the user should refer to Sun Java System Application Server Developer’s Guide to learn the details of how these descriptors can be edited to create the role-to-principal mappings.
sun-web.xml
Code Example B-21 sun-web.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Application Server 8.1 Servlet 2.4//EN' 'http://www.sun.com/software/appserver/dtds/sun-web-app_2_4-1.dtd'>
<!-- Copyright 2002 Sun Microsystems, Inc. All rights reserved. -->
<sun-web-app>
<security-role-mapping>
<role-name>MANAGER-ROLE</role-name>
<group-name>manager</group-name>
</security-role-mapping>
<security-role-mapping>
<role-name>EMPLOYEE-ROLE</role-name>
<group-name>employee</group-name>
</security-role-mapping>
</sun-web-app>
sun-ejb-jar.xml
Code Example B-22 sun-ejb-jar.xml
<?xml version="1.0"?>
<!DOCTYPE sun-ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD
Application Server 8.1 EJB 2.1//EN'
'http://www.sun.com/software/appserver/dtds/sun-ejb-jar_2_1-1.dtd'>
<sun-ejb-jar>
<enterprise-beans>
<ejb>
<ejb-name>ReportEJB </ejb-name>
<jndi-name>ReportEJB </jndi-name>
</ejb>
</enterprise-beans>
</sun-ejb-jar>
sun-application.xml
Code Example B-23 sun-application.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-application PUBLIC '-//Sun Microsystems, Inc.//DTD Application Server 8.1 J2EE Application 1.4//EN' 'http://www.sun.com/software/appserver/dtds/sun-application_1_4-0.dtd'>
<sun-application>
<security-role-mapping>
<role-name>MANAGER-ROLE</role-name>
<group-name>manager</group-name>
</security-role-mapping>
<security-role-mapping>
<role-name>EMPLOYEE-ROLE</role-name>
<group-name>employee</group-name>
</security-role-mapping>
</sun-application>