source: TI12-security/trunk/java/axis2/xmlbWsseEchoClient/src/wssecurity/test/security/ndg/README.txt @ 4088

Subversion URL:
Revision 4088, 5.7 KB checked in by cbyrom, 13 years ago (diff)

Add README.txt doc with details on setting up java client to use
webservice with webservice security - using rampart.

1Instructions for getting a working Java client
41. Download and unpack axis2-1.4 (
52. Download and unpack rampart1.3 (
63. Ensure that the AXIS2_HOME environment variable is set correctly then
7run 'ant' in the $RAMPART_HOME/samples dir - this will copy the required rampart
8files into the axis2 install
94. Download wss4j-1.5.3.jar ( and add to the $AXIS2_HOME/lib dir
105. Create a java project in eclipse
116. In the top level directory of this project, run the following command:
13%AXIS2_HOME%\bin\WSDL2Java -uri <service>.wsdl -p -d adb -s
15NB: '-uri' should point to the wsdl to create the service against (can use
16absolute file path if the wsdl if available locally)
17 '-p' specifies the package to create
18 '-d' specifies the databindings to create - here we use the Axis Data Binding default - which is a simple, but not too flexible approach
19 (other options are available: xmlbeans -; and
20 JiBX -
21 '-s' specifies synchronous invocation - i.e. the client will wait for a response - use '-a' for
22 asynch clients - i.e. with callback handlers)
24 7. Refresh the project in eclipse to import the generated stub file - which will be called
25 <service> (NB, if other binding types are used there will likely be many more
26 stub files produced)
27 8. Open the <service> file and correct the package name, if need be.  Also make
28 use of eclipse's auto formatting function (ctrl-F) to tidy up the code.
29 9. Add the contents of $AXIS2_HOME/lib to the build classpath - this should then remove all
30 the errors displayed in eclipse for the stub file.
31 10. Create a new class - <service> - in the same package as the stub file.
32 11. The new class should be based on the example client jar in this folder - i.e. EchoClient.jar
33 12. Download geronimo-j2ee_1.4_spec-1.0.jar and add this to the classpath (otherwise you end up with
34 a org.apache.axis2.deployment.DeploymentException: javax/jms/JMSException error when running the client)
35 13. Copy the $AXIS2_HOME\repository\modules directory to the top level of the project
36 14. Copy the $AXIS2_HOME\conf directory to the top level of the project
37 15. Copy the file from this project into the top level project directory
38 16. Set up security keys to use:
39        a) $JAVA_HOME\bin\keytool -genkey -alias client -keystore client.jks -keypass apache -storepass apache -keyalg RSA
40        (NB, can adjust names, but key needs to be RSA format to be accepted by the python ZSI webservice library also,
41        best to use the default keystore type of 'JKS' - since 'PKCS12' doesn't allow trusted certificates to be stored - so
42        it is not possible to store the service key - i.e. step (c), below)
44        b) The key now needs to be signed by a Certificate Authority (CA) (to allow ZSI processing to complete successfully):
45                i) Firstly generate a certificate request via:
47$JAVA_HOME\bin\keytool -certreq -keystore client.jks -storepass apache -alias client -file client.cert.req
49                ii) Now, to get hold of a Certificate Authority key pair, copy the index.txt. openssl.cnf and serial files from
50                axis2/xmlbWsseEchoclient/opensslFiles/ (originally from
51                iii) Run,
53openssl req -x509 -newkey rsa:1024 -keyout cakey.pem -out cacert.pem -config openssl.cnf
54                (NB, some of the DN data that you input whilst running this command will need to match the DN
55                data of the generated key that you want to sign - so try and ensure the data is similar - especially, avoid
56                using the default values since these are not the 'Unknown' values that the keytool provides)
58                iv) Create new certificates signed by the CA key using:
60openssl ca -config openssl.cnf -out client.pem -infiles client.cert.req
61                (NB, this command will fail if the DN data between the CA cert and the generated key mismatches significantly - as described in (iii)
63                v) To import the new signed key into the keystore, need to put into binary format:
65openssl x509 -outform DER -in client.pem -out client.cert
67                and do the same for the CA certificate:
69openssl x509 -outform DER -in cacert.pem -out cacert.cert
71                vi) Lastly, import both the CA certificate and the new key (NB, the CA cert needs to be imported first)
73$JAVA_HOME\bin\keytool -import -file cacert.cert -keystore client.jks -storepass apache -alias ca
74$JAVA_HOME\bin\keytool -import -file client.cert -keystore client.jks -storepass apache -alias client
76        c) The last thing to do is import the public key of the service into the client keystore:
78%JAVA_HOME%\bin\keytool -import -alias service -file service.cert -keystore client -storepass apache
8017. Edit the contents of to ensure the file and password properties are set correctly.
8118. Edit the contents of $AXIS2_HOME\conf\axis2.xml adjusting the rampart set up as appropriate.  NB, the
82example file included in this codebase (axis2/xmlbWsseEchoclient/conf/axis2.xml) should be sufficient for
83the purposes here.  The README.txt file in axis2/xmlbWsseEchoclient/conf/ gives a more detailed explanation
84of the various configurations of this file.
8519. Include a password callback class, if this is set in axis2.xml, in the source code structure - NB, the
86basic, included in this directory, can be used as a starting point.
8720. Start up the service associated with the wsdl used in step 6. and run the client as a
88java app - with luck the service should return without a problem.
Note: See TracBrowser for help on using the repository browser.