Sun OpenSSO Enterprise Policy Agent 3.0 Guide for JBoss Application Server 4.x/5.x

Optional Post-Installation Tasks for the JBoss Application Server 4.x/5.x Agent

Changing the Password for an Agent Profile

After you install the agent, you can change the agent profile password, if required for your deployment.

ProcedureTo Change the Password for an Agent Profile

  1. On the OpenSSO Enterprise server:

    1. Login into the OpenSSO Administration Console.

    2. Click Access Control, realm-name, Agents, J2EE, and then the name of the agent profile you want to update.

      The Console displays the Edit page for the agent profile.

    3. Enter and confirm the new unencrypted password.

    4. Click Save.

  2. On the server where the JBoss Application Server 4.x/5.x agent is installed:

    1. In the agent profile password file, replace the old password with the new unencrypted password.

    2. Change to the PolicyAgent-base/bin directory.

    3. Encrypt the new password using the agentadmin --encrypt command following this syntax.

      agentadmin --encrypt agent-instance password-file

      For example:

      # ./agentadmin --encrypt Agent_001 jbossagentpw

      The agentadmin --encrypt command returns the new encrypted password. For example:

      ASEWEJIowNBJHTv1UGD324kmT==

    4. In the agent-instance/config/OpenSSOAgentBootstrap.properties file, set the following property to the new encrypted password from the previous step. For example:

      com.iplanet.am.service.secret=ASEWEJIowNBJHTv1UGD324kmT==

    5. Restart the JBoss Application Server instance that is being protected by the policy agent.

Creating the Necessary URL Policies

If the JBoss Application Server 4.x/5.x agent is configured to operate in the URL_POLICY or ALL filter mode, you must create the appropriate URL policies. For instance, if the agent is available on port 8080 using the HTTP protocol, you must create at minimum, a policy to allow access to the following resource:


http://myhost.mydomain.com:8080/agentsample

where agentsample is the context URI for the sample application.

If no policies are defined and the agent is configured to operate in the URL_POLICY or ALL filter mode, then no user is allowed access to the resources protected by the JBoss Application Server 4.x/5.x agent.

For more information, see:

Enabling Programmatic Web Logins for the JBoss Application Server 4.x/5.x Agent

JBoss Application Server 4.2.3 and later supports programmatic web logins, which allows the agent to programmatically authenticate against the JBoss Application Server web container. This feature uses the org.jboss.web.tomcat.security.login.WebAuthentication class. For more information, see http://community.jboss.org/wiki/WebAuthentication.

The JBoss Application Server 4.x/5.x agent uses the com.sun.identity.agents.config.jboss.webauth.available property to enable or disable this feature. The default is false.

For the JBoss Application Server 4.x/5.x agent, set this property depending on the agent configuration:

ProcedureTo Enable Programmatic Web Logins for the JBoss Application Server 4.x/5.x Agent in the Console

  1. Log in to the OpenSSO Enterprise Administration Console.

  2. Click Access Control, realm-name, Agents, J2EE, and then the name of the JBoss Application Server 4.x/5.xJBoss Application Server 4.x/5.x agent.

  3. Enable programmatic web logins, depending on your version of OpenSSO Enterprise:

    • For OpenSSO Enterprise 8.0 RTM, under the JBoss Application Server 4.x/5.x agent profile name, click Advanced, and then Custom Properties. Add the following property and click Save.

      com.sun.identity.agents.config.jboss.webauth.available=true

    • In later builds of OpenSSO Enterprise 8.0, under the JBoss Application Server 4.x/5.x agent profile name, click Advanced and then JBoss Application Server. Check Enabled for Web Authentication Available and then click Save.

    The com.sun.identity.agents.config.jboss.webauth.available property is hot-swappable, so you do not need to restart the OpenSSO Enterprise web container for the value to take effect.

Deploying the Java EE Policy Agent Sample Application

Deploying the policy agent sample application is optional. However. after you install the JBoss Application Server 4.x/5.x agent, consider deploying the sample application to help you better understand the key features, functions, and configuration options of Java EE agents, including:

The sample application can be especially useful if you are writing a custom agent application.

After you install the JBoss Application Server 4.x/5.x agent, the sample application is available as:

PolicyAgent-base/sampleapp/dist/agentsample.ear

For information about compiling, deploying, and running the sample application, see the readme.txt file in the /sampleapp directory.

Configuring Web Services Security for the JBoss Application Server 4.x/5.x Agent

The JBoss Application Server 4.x/5.x agent supports Web Services Security (WSS) for web service providers. A web service provider (WSP) deployed on JBoss Application Server protected by the agent can have additional security provided by the agent. For example, you can configure the JBoss Application Server 4.x/5.x agent and OpenSSO Enterprise server to support various WSS profiles, including Username token, X509 token, and SAML2 token.


Note –

During testing of the agent with JAX-WS web services, it was observed the JBoss Application Server has an implementation of JAX-WS that is not compatible with the com.sun.identity.wss.security.handler.SecureSOAPMessage implementation. To use WSS, you must integrate compatible JAX-WS JAR files into your deployment, or you will get a org.jboss.ws.core.soap.SOAPPartImpl.normalize() Not Implemented exception.


About the Examples. The examples in this section use /opt as the download and installation directory. However, if you prefer, you can use a different directory. These examples are also intended for a Solaris or Linux system. If you are running on another platform such as Windows, you will need to make changes for the paths and filenames.

ProcedureTo Download Compatible JAX-WS JAR Files

You must first download and install the JAX-WS JAR files from the JAX-WS Reference Implementation (RI) project.

  1. Download and unzip JBoss Application Server 4.x/5.x in the /opt directory.

  2. Download jaxws-ri.zip from the following site: https://jax-ws.dev.java.net/

  3. Unzip jaxws-ri.zip in /opt.

  4. On Solaris and Linux systems, set the JAX-WS RI shell scripts to be executable. For example:

    cd /opt/jaxws-ri/bin
    chmod +x *.sh

Configuring the StockService and StandAloneStockClient Samples

This section describes how to configure the StockService sample as the WSP and the StandAloneStockClient as the WSC. Use these samples as models to configure your own WSS applications.

ProcedureTo Configure the StockService Sample

  1. Create the wsp directory under /opt.

  2. Download openssowssproviders.zip from the WSS Agent link on https://opensso.dev.java.net/public/use/index.html.

  3. Unzip openssowssproviders.zip in /opt/wsp/.

  4. Create the jboss directory under /opt/wsp/samples for the JBoss Application Server files. For example:

    cd /opt/wsp/samples
    mkdir jboss
  5. Copy the GlassFish sample files to the new jboss directory:

    cp -r /opt/wsp/samples/glassfish/* /opt/wsp/samples/jboss/
  6. Rename glassfish.properties for JBoss Application Server:

    cd /opt/wsp/samples/jboss/
    mv glassfish.properties jboss.properties
  7. In /opt/wsp/samples/jboss/jboss.properties, remove the GlassFish properties and add the following:

    wsp.home=/opt/wsp
    jaxws.home=/opt/jaxws-ri
    jaxws.lib.dir=/opt/jaxws-ri/lib
  8. Edit /opt/wsp/samples/jboss/StockService/build.xml, as shown in the next example.


    Tip –

    To create a new JBoss Application Server build.xml file, just copy the following XML statements.


    <?xml version="1.0" encoding="UTF-8"?> 
    <project name="StockQuoteService" default="all" basedir=".">
      <description>Builds, tests, and runs the project stockclient.</description>
      <property file="../jboss.properties"/>
      <condition property="wsimport-script-suffix" value=".bat">
        <os family="windows"/>
      </condition>
      <condition property="wsimport-script-suffix" value=".sh">
        <not>
          <os family="windows"/>
        </not>
      </condition>
      <path id="build.class.path">
      <pathelement location="build/classes"/>
        <fileset dir="${jaxws.lib.dir}">
          <include name="**/*.jar"/>
        </fileset>
      </path>
      <target name="-pre-compile">
        <mkdir dir="build/classes"/>
        <mkdir dir="web/WEB-INF/classes"/>
        <exec executable="${jaxws.home}/bin/wsimport${wsimport-script-suffix}">
        <arg line="-verbose -d build/classes web/WEB-INF/wsdl/StockService/stockservice.wsdl"/>
        </exec>
        <copy file="src/java/handlers.xml" todir="web/WEB-INF/classes"/> 
      </target> 
      <target name="compile" depends="-pre-compile"> 
        <javac fork="true" destdir="build/classes" srcdir="src/java"> 
          <classpath refid="build.class.path" />
        </javac> 
      </target> 
      <target name ="war" depends="compile">
          <mkdir dir="dist"/> 
        <copy todir="web/WEB-INF/classes"> 
          <fileset dir="build/classes" /> 
        </copy>
        <copy todir="web/WEB-INF/lib"> 
          <fileset dir="${jaxws.lib.dir}"/> 
        </copy>
        <war destfile="dist/StockService.war" webxml="web/WEB-INF/web.xml"> 
          <zipfileset dir="web" />
        </war> 
      </target> 
      <target name="all">
        <antcall target="war" /> 
      </target> 
    </project> 
  9. In the following file, change any references to localhost and port 8080, depending on your deployment:

    /opt/wsp/samples/jboss/StockService/web/WEB-INF/wsdl/StockService/stockservice.wsdl
  10. Remove /opt/wsp/samples/jboss/StockService/web/WEB-INF/sun-web.xml. For example:

    cd /opt/wsp/samples/jboss/StockService/web/WEB-INF
    rm sun-web.xml
  11. In the same directory, create sun-jaxws.xml with the following content:

    <?xml version="1.0" encoding="UTF-8"?>
    <endpoints
      xmlns='http://java.sun.com/xml/ns/jax-ws/ri/runtime'
      version='2.0'>
      <endpoint
        name='StockService'
        implementation='com.samples.StockService'
        url-pattern='/StockService' />
    </endpoints>
  12. In the same directory, in web.xml, add the agent <filter>, <filter-mapping>, <listener>, <servlet>, and <servlet-mapping> entries, as follows:

    <?xml version="1.0" encoding="UTF-8"?>
    <web-app xmlns="http://java.sun.com/xml/ns/javaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
    http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
        version="2.5">
    
      <filter>
        <filter-name>Agent</filter-name>
        <filter-class> com.sun.identity.agents.filter.AmAgentFilter </filter-class>
      </filter>
      <filter-mapping>
        <filter-name>Agent</filter-name>
        <url-pattern>/*</url-pattern>
        <dispatcher>REQUEST</dispatcher>
       <dispatcher>INCLUDE</dispatcher>
        <dispatcher>FORWARD</dispatcher>
        <dispatcher>ERROR</dispatcher>
      </filter-mapping>
    
      <session-config>
        <session-timeout>
          30
        </session-timeout>
      </session-config>
      <welcome-file-list>
        <welcome-file>
          index.jsp
        </welcome-file>
      </welcome-file-list>
    
      <listener>
        <listener-class>
          com.sun.xml.ws.transport.http.servlet.WSServletContextListener
        </listener-class>
      </listener>
    
      <servlet>
        <description>JAX-WS endpoint</description>
        <display-name>The JAX-WS servlet</display-name>
        <servlet-name>jaxws</servlet-name>
        <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>
      </servlet>
      <servlet-mapping>
        <servlet-name>jaxws</servlet-name>
        <url-pattern>/StockService</url-pattern>
      </servlet-mapping>
    </web-app>
  13. Build the StockService WAR file. For example, using ant:

    cd /opt/wsp/samples/jboss/StockService
    /share/builds/components/ant/1.6.5/bin/ant -f build.xml

ProcedureTo Install the JBoss Application Server 4.x/5.x Agent and Setup the WSP and WSC

  1. Install and configure the JBoss Application Server 4.x/5.x agent, as described in this guide.

    As noted, the examples in this guide use /opt as the installation directory.

  2. Follow the general steps to configure the web service provider (WSP) and web service client (WSC) in Web Services Security Support for J2EE Agents in Policy Agent 3.0 in Sun OpenSSO Enterprise Policy Agent 3.0 User’s Guide for J2EE Agents.

  3. Configure and deploy your WSP application.

    If you are deploying new web services that uses JAX-WS, this guide uses the StockService and StandAloneStockClient samples as examples to follow for your web services.

    If your application is already deployed and using WSS with JAX-WS, you might need only to add the agent filter in the web.xml file.

  4. Start the JBoss Application Server web container.

ProcedureTo Configure the StandAloneStockClient Sample

  1. Change to the StandAloneStockClient directory:

    cd /opt/wsp/samples/jboss/StandAloneStockClient
  2. Edit the src/com/samples/SecuringWS.java file as follows:.

    • Change any references to localhost and 8080, depending on your deployment

    • Change the providerNamestring to "wsc".

  3. In the /opt/wss/samples/jboss/StandAloneStockClient directory, modify build.xml for JBoss Application Server rather than GlassFish:

    <?xml version="1.0" encoding="UTF-8"?>
    <project name="StandAloneStockClient" default="default" basedir=".">
      <description>Builds, tests, and runs the project stockclient.</description>
      <property file="../jboss.properties"/>
      <property name="is.java-client.module" value="true"/>
      <target name="default" depends="run"/>
      <target name="build" depends="clean">
        <mkdir dir="build/classes"/>
        <javac srcdir="src"
        destdir="build/classes"
        classpath="xyz.jar"
        debug="on">
        <classpath>
          <pathelement location="${wsp.home}/lib/openssowssproviders.jar"/>
          <pathelement location="${wsp.home}/lib/webservices-rt.jar"/>
          <pathelement location="${wsp.home}/lib/openssoclientsdk.jar"/>
          <pathelement location="${wsp.home}/lib/xalan.jar"/>
          <pathelement location="${wsp.home}/lib/xercesImpl.jar"/>
          <pathelement location="${wsp.home}/lib/j2ee.jar"/>
          <pathelement location="${wsp.home}/lib"/>
          <pathelement path="build/classes"/>
        </classpath>
        </javac>
    </target>
    
    <target name="run" depends="build">
        <echo>java.home=${java.home}</echo>
      <java classname="com.samples.SecuringWS" fork="true">
        <classpath>
          <pathelement location="${wsp.home}/lib/openssowssproviders.jar"/>
          <pathelement location="${wsp.home}/lib/ldapjdk.jar"/>
          <pathelement location="${wsp.home}/lib/webservices-rt.jar"/>
          <pathelement location="${wsp.home}/lib/openssoclientsdk.jar"/>
          <pathelement location="${wsp.home}/lib/xalan.jar"/>
          <pathelement location="${wsp.home}/lib/xercesImpl.jar"/>
          <pathelement location="${wsp.home}/lib/j2ee.jar"/>
          <pathelement location="${wsp.home}/lib"/>
          <pathelement path="build/classes"/>
        </classpath>
        </java>
      </target>
    
      <target name="clean">
        <delete dir="dist"/>
        <delete dir="build"/>
      </target>
    </project>
  4. Modify /opt/wsp/lib/AMConfig.properties depending on your setup, so that the StandAloneStockClient sample sends a secure web service request:

    com.iplanet.services.debug.level=error
    com.iplanet.services.debug.directory=/tmp/wss
    com.iplanet.am.naming.url=http://opensso-host:port/opensso/namingservice
    com.sun.identity.agents.app.username=amadmin
    com.iplanet.am.service.password=amadmin-password
    com.iplanet.am.service.secret=
    am.encryption.pwd=
    com.sun.identity.client.encryptionKey=
    com.iplanet.am.server.protocol=http
    com.iplanet.am.server.host=opensso-host
    com.iplanet.am.server.port=port
    com.iplanet.am.services.deploymentDescriptor=/opensso
    com.iplanet.am.cookie.name=iPlanetDirectoryPro
    com.sun.identity.saml.xmlsig.keystore=/opt/wsp/resources/keystore.jks
    com.sun.identity.saml.xmlsig.storepass=/opt/wsp/resources/.storepass
    com.sun.identity.saml.xmlsig.keypass=/opt/wsp/resources/.keypass
    com.sun.identity.saml.xmlsig.certalias=cert-alias
    com.sun.identity.loginurl=http://your-opensso-hostname:port/opensso/UI/Login
    com.sun.identity.liberty.authnsvc.url=http://opensso-host:port/opensso/Liberty/authnsvc
  5. Execute the StandAloneStockClient. For example:

    /share/builds/components/ant/1.6.5/bin/ant -f build.xml.

    You should see the requests and responses. Also, check the JBoss Application Server agent debug file.