Home | PDF | API | FAQ | Search | Feedback | History

JAAS Sample Application

The Java Authentication and Authorization Service (JAAS) is a set of APIs that enable services to authenticate and enforce access controls upon users. It implements a Java technology version of the standard Pluggable Authentication Module (PAM) framework, and supports user-based authorization.

The <JWSDP_HOME>/xws-security/samples/jaas-sample application demonstrates the following functionality:

Obtaining a user name and password at run-time and sending it in a Web Services Security (WSS) UsernameToken to the server.
Using JAAS authentication to authenticate the user name and password in the server application.
Accessing the authenticated sender's subject from within the endpoint implementation methods.

The application prints out both the client and server request and response SOAP messages. The output from the server may be viewed in the appropriate container's log file. The output from the client is sent to stdout or whichever stream is used by the configured log handler. Messages are logged at the INFO level.

In this example, server-side code is found in the /jaas-sample/server/src/jaas-sample/ directory. Client-side code is found in the /jaas-sample/client/src/jaas-sample/ directory. The asant (or ant) targets build objects under the /build/server/ and /build/client/ directories.

JAAS Sample Security Configuration Files

The security configuration pair user-pass-authenticate-client.xml and user-pass-authenticate-server.xml enable the following tasks:

Client adds a username-password token and sends a request.
Server authenticates the username and password against a username-password database.
Server sends response.

The username-password database must be set up before this security configuration pair will run properly. Refer to Setting Up For the JAAS-Sample for instructions on setting up this database.

The user-pass-authenticate-client.xml file looks like this:

<xwss:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">

    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <xwss:UsernameToken digestPassword="false"/>
        </xwss:SecurityConfiguration>
    </xwss:Service>

    <xwss:SecurityEnvironmentHandler>
        sample.ClientSecurityEnvironmentHandler
    </xwss:SecurityEnvironmentHandler>

</xwss:JAXRPCSecurity> 

If you compare this security configuration file to the similar one in the simple sample, as discussed in Adding a Username Password Token, you'll see that this security configuration file does not hard-code the user name and password. In this example, the username and password are obtained by reading a system property, username.password, that is configured in the build.xml file of the jaas-sample under the run-sample target as a sysproperty. The properties and a section of the target from this example are configured like this:

<target name="run-sample" 
          depends="clean, prepare, build-server, deploy-forced, 
build-client"
          description="Runs the example client">
    <echo message="Running the ${client-class} program...."/>
    <java fork="on" classname="${client-class}">
      <sysproperty key="java.endorsed.dirs" 
value="${java.endorsed.dirs}"/>
      <sysproperty key="endpoint.host" value="${endpoint.host}"/
>
      <sysproperty key="endpoint.port" value="${endpoint.port}"/
>
      <sysproperty key="service.url" value="${service.url}"/>
      <sysproperty key="username.password" value="Ron noR"/> 

The client-side SecurityEnvironmentHandler of this sample is the entity that actually reads the system property at run-time and populates the username and password Callback objects passed to it by the XWS-Security run-time. A different SecurityEnvironmentHandler can be plugged into this sample to obtain the username and password at run-time from a different source (possibly by popping up a dialog box where the user can enter the username and password).

This sample's server-side SecurityEnvironmentHandler makes use of a JAAS login module that takes care of authenticating the user name and password. The sample demonstrates how JAAS authentication can be plugged into applications that use the XWS-Security framework. The source of the JAAS login module, UserPassLoginModule.java, is located at <JWSDP_HOME>/xws-security/samples/jaas-sample/src/com/sun/xml/wss/sample directory. The JAASValidator.java class in the same directory does the actual JAAS authentication by creating a LoginContext and calling the LoggingContext.login() method. The UserPassLoginModule makes use of a username-password XML database located at <JWSDP_HOME>/xws-security/etc/userpasslist.xml when performing the actual authentication in its login() method.

Setting Up For the JAAS-Sample

Before the sample application will run correctly, you must have completed the tasks defined in the following sections of this addendum:

Setting System Properties
Setting Build Properties

In addition, follow the steps in this section that are specific to the jaas-sample application.

Stop the Application Server.
Set the user name and password for the example.

Because the samples are run using ASAnt tasks, the user name and password for this example are set as a system property. The build.xml file for the jaas-sample example includes the following line under the run-sample target that uses a user name and password supplied in the <JWSDP_HOME>/xws-security/etc/userpasslist.xml file.

<sysproperty key="username.password" value="Ron noR"/>

The JAAS login module also makes use of the userpasslist.xml file, so make sure that this file exists and contains the user name and password specified in the build.xml file.

Add the following JAAS policy to the JAAS policy file of the Application Server. This file can be found at <SJSAS_HOME>/domains/domain1/config/login.conf. Add the following code near the end of the file:

/** Login Configuration for the Sample Application **/
XWS_SECURITY_SERVER{com.sun.xml.wss.sample.UserPassLoginModule REQUIRED debug=true;
};

Add the following permissions to the server policy file of the Application Server. This file can be found at <SJSAS_HOME>/domains/domain1/config/server.policy. Add the following code near the end of the file:

grant codeBase "file:${com.sun.aas.instanceRoot}/applications/j2ee-modules/jaassample/WEB-INF/-" {
permission javax.security.auth.AuthPermission "modifyPrincipals";
permission javax.security.auth.AuthPermission "modifyPrivateCredentials";
permission javax.security.auth.PrivateCredentialPermission "* * \"*\"","read";
permission javax.security.auth.AuthPermission "getSubject";
      permission javax.security.auth.AuthPermission
         "createLoginContext.XWS_SECURITY_SERVER";
};

Save and exit all files.
Restart the Application Server.

Running the JAAS-Sample Application

To run the jaas-sample application, follow these steps:

Follow the steps in Setting Up For the JAAS-Sample.
Start the selected container and make sure the server is running. To start the Application Server,
From a Unix machine, enter the following command from a terminal window: asadmin start-domain domain1
From a Windows machine, choose StartProgramsSun MicrosystemsApplication ServerStart Default Server.
Build and run the application from a terminal window or command prompt.
On the Application Server, the command to build and run the application is: asant run-sample
On the other containers, the command to build and run the application is: ant run-sample

---

Note: To run the sample against a remote server containing the deployed endpoint, use the run-remote-sample target in place of the run-sample target. In this situation, make sure that the endpoint.host, endpoint.port, http.proxyHost, http.proxyPort, and service.url properties are set correctly in the build.properties file (as discussed in Setting Build Properties) before running the sample.

---

If the application runs successfully, you will see a message similar to the following:

     [echo] Running the sample.TestClient program....
     [java] Service URL=http://localhost:8080/jaassample/Ping
     [java] Username read=Ron
     [java] Password read=noR
     [java] INFO: ==== Sending Message Start ====
     [java] <?xml version="1.0" encoding="UTF-8"?>
     [java] <env:Envelope xmlns:env="http://
schemas.xmlsoap.org/soap/envelope/" xmlns:enc="http://
schemas.xmlsoap.org/soap/encoding/" xmlns:ns0="http://
xmlsoap.org/Ping" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     [java] <env:Header>
     [java] <wsse:Security xmlns:wsse="http://docs.oasis-
open.org/wss/2004/01/oasis-200401-
     wss-wssecurity-secext-1.0.xsd" env:mustUnderstand="1">
     [java] <wsse:UsernameToken>
     [java] <wsse:Username>Ron</wsse:Username>
     [java] <wsse:Password>****</wsse:Password>
     [java] <wsse:Nonce EncodingType="http://docs.oasis-
open.org/wss/2004/01/oasis-
     200401-wss-soap-message-security-
     1.0#Base64Binary">qdKj8WL0U3r21rcgOiM4H76H</wsse:Nonce>
     [java] <wsu:Created xmlns:wsu="http://docs.oasis-open.org/
wss/2004/01/oasis-200401-
     wss-wssecurity-utility-1.0.xsd">2004-11-05T02:07:46Z</
wsu:Created>
     [java] </wsse:UsernameToken>
     [java] </wsse:Security>
     [java] </env:Header>
     [java] <env:Body>
     [java] <ns0:Ping>
     [java] <ns0:ticket>SUNW</ns0:ticket>
     [java] <ns0:text>Hello !</ns0:text>
     [java] </ns0:Ping>
     [java] </env:Body>
     [java] </env:Envelope>
     [java] ==== Sending Message End ====
 
     [java] INFO: ==== Received Message Start ====
     [java] <?xml version="1.0" encoding="UTF-8"?>
     [java] <env:Envelope xmlns:env="http://
schemas.xmlsoap.org/soap/envelope/"
     xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:ns0="http://xmlsoap.org/
     Ping" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     [java] <env:Body>
     [java] <ns0:PingResponse>
     [java] <ns0:text>Hello !</ns0:text>
     [java] </ns0:PingResponse>
     [java] </env:Body>
     [java] </env:Envelope>
     [java] ==== Received Message End ====  

The server code in server/src/sample/PingImpl.java makes use of a SubjectAccessor to access and print the authenticated Subjects principal from within the business method Ping().

You can view similar messages in the server logs:

<SJSAS_HOME>/domains/<domain-name>/logs/server.log 
<TOMCAT_HOME>/logs/launcher.server.log 
<SJSWS_HOME>/<Virtual-Server-Dir>/logs/errors  

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.