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 theINFO
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. Theasant
(orant)
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
anduser-pass-authenticate-server.xml
enable the following tasks: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 thebuild.xml
file of thejaas-sample
under therun-sample
target as asysproperty
. 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 passwordCallback
objects passed to it by the XWS-Security run-time. A differentSecurityEnvironmentHandler
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. TheJAASValidator.java
class in the same directory does the actual JAAS authentication by creating aLoginContext
and calling theLoggingContext.login()
method. TheUserPassLoginModule
makes use of a username-password XML database located at<JWSDP_HOME>
/xws-security/etc/userpasslist.xml
when performing the actual authentication in itslogin()
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:
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. Thebuild.xml
file for thejaas-sample
example includes the following line under therun-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 thebuild.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,
- Build and run the application from a terminal window or command prompt.
Note: To run the sample against a remote server containing the deployed endpoint, use the
run-remote-sample
target in place of therun-sample
target. In this situation, make sure that theendpoint.host
,endpoint.port
,http.proxyHost
,http.proxyPort
, andservice.url
properties are set correctly in thebuild.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 aSubjectAccessor
to access and print the authenticatedSubjects
principal from within the business methodPing()
.You can view similar messages in the server logs: