1 | Instructions for getting a working Java client |
---|
2 | ------------------------------- |
---|
3 | |
---|
4 | 1. Download and unpack axis2-1.4 (http://ws.apache.org/axis2/download/1_4/download.cgi#std-bin) |
---|
5 | 2. Download and unpack rampart1.3 (http://ws.apache.org/rampart/download/1.3/download.cgi) |
---|
6 | 3. Ensure that the AXIS2_HOME environment variable is set correctly then |
---|
7 | run 'ant' in the $RAMPART_HOME/samples dir - this will copy the required rampart |
---|
8 | files into the axis2 install |
---|
9 | 4. Download wss4j-1.5.3.jar (http://mirror.fubra.com/ftp.apache.org/ws/wss4j/) and add to the $AXIS2_HOME/lib dir |
---|
10 | 5. Create a java project in eclipse |
---|
11 | 6. In the top level directory of this project, run the following command: |
---|
12 | |
---|
13 | %AXIS2_HOME%\bin\WSDL2Java -uri <service>.wsdl -p ndg.security.client -d adb -s |
---|
14 | |
---|
15 | NB: '-uri' should point to the wsdl to create the service against (can use |
---|
16 | absolute 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 - http://ws.apache.org/axis2/1_4/userguide-creatingclients-xmlbeans.html; and |
---|
20 | JiBX - http://ws.apache.org/axis2/1_4/userguide-creatingclients-jibx.html) |
---|
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) |
---|
23 | |
---|
24 | 7. Refresh the project in eclipse to import the generated stub file - which will be called |
---|
25 | <service>ServiceStub.java (NB, if other binding types are used there will likely be many more |
---|
26 | stub files produced) |
---|
27 | 8. Open the <service>ServiceStub.java 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>Client.java - 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 client.properties 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) |
---|
43 | |
---|
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: |
---|
46 | |
---|
47 | $JAVA_HOME\bin\keytool -certreq -keystore client.jks -storepass apache -alias client -file client.cert.req |
---|
48 | |
---|
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 http://wso2.org/library/174) |
---|
51 | iii) Run, |
---|
52 | |
---|
53 | openssl 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) |
---|
57 | |
---|
58 | iv) Create new certificates signed by the CA key using: |
---|
59 | |
---|
60 | openssl 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) |
---|
62 | |
---|
63 | v) To import the new signed key into the keystore, need to put into binary format: |
---|
64 | |
---|
65 | openssl x509 -outform DER -in client.pem -out client.cert |
---|
66 | |
---|
67 | and do the same for the CA certificate: |
---|
68 | |
---|
69 | openssl x509 -outform DER -in cacert.pem -out cacert.cert |
---|
70 | |
---|
71 | vi) Lastly, import both the CA certificate and the new key (NB, the CA cert needs to be imported first) |
---|
72 | |
---|
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 |
---|
75 | |
---|
76 | c) The last thing to do is import the public key of the service into the client keystore: |
---|
77 | |
---|
78 | %JAVA_HOME%\bin\keytool -import -alias service -file service.cert -keystore client -storepass apache |
---|
79 | |
---|
80 | 17. Edit the contents of client.properties to ensure the file and password properties are set correctly. |
---|
81 | 18. Edit the contents of $AXIS2_HOME\conf\axis2.xml adjusting the rampart set up as appropriate. NB, the |
---|
82 | example file included in this codebase (axis2/xmlbWsseEchoclient/conf/axis2.xml) should be sufficient for |
---|
83 | the purposes here. The README.txt file in axis2/xmlbWsseEchoclient/conf/ gives a more detailed explanation |
---|
84 | of the various configurations of this file. |
---|
85 | 19. Include a password callback class, if this is set in axis2.xml, in the source code structure - NB, the |
---|
86 | basic PWCBHandler.java, included in this directory, can be used as a starting point. |
---|
87 | 20. Start up the service associated with the wsdl used in step 6. and run the client as a |
---|
88 | java app - with luck the service should return without a problem. |
---|