Download FAQ History

API Search Feedback

Understanding and Running the 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 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 may be viewed using stdout.

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.

Understanding 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 the Application Server For the Examples 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>
        com.sun.xml.wss.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. The username and password are obtained by reading a system property username.password. The default value for this property has been configured inside the build.xml file of the jaas-sample under the run-sample target as a sysproperty. 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 samples 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;
};

Running the JAAS-Sample Application

To run the simple 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.
Modify the build.properties file to set up the security configuration that you want to run for the client and/or server. See Sample Security Configuration File Options for more information on the security configurations options that are already defined for the sample application.
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  

Download FAQ History

API Search Feedback

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.