Installation Instructions for Unix

Follow the steps listed below to install and run Soap Authentication module.

1)  First of all you need a servlet container, it can be any servlet container but I am assuming you are using Tomcat 3.2.1(or above). If you don't have  tomcat already, you can download it by clicking here. I'm assuming that you installed Tomcat in '/usr/local' directory so you have folder 'Tomcat-3.2.1' in '/usr/local' directory . You need to set TOMCAT_HOME and JAVA_HOME environment variables in '.bash_profile'. Tomcat installation instructions are available at  the above given link. 

2) Install Apache 1.3.22(or above) on your machine. However Apache comes bundled with Linux installation but incase you have not opted for Apache to be installed on your machine then please install it separately. Binaries of apache(apache_1.3.22-i686-whatever-linux22.tar.gz) can be downloaded by clicking here. I am assuming that you installed apache in '/usr/local' directory so you have folder 'Apache' in '/usr/local/'. 

3) Also since the method of authentication works using both an apache module and a servlet, Tomcat needs to be bridged to Apache. To connect Tomcat to Apache using mod_jk you need to do the following
a) Download 'mod_jk-3.3-ap20.so' by clicking here.
b) Place 'mod_jk-3.3-ap20.so' in '/usr/local/Apache/modules' directory available in Apache installation folder.
c) Open file "hhtpd.conf" available in ''usr/local/Apache/conf' directory. At the last line of this file write 
Include /usr/local/Tomcat-3.2.1/conf/mod_jk.conf-auto
d) Open file(an xml file)"server.xml" available in '/usr/local/conf' directory. Add tag <ApacheConfig /> in the 'ContextManager' tag so that it looks something like this 

<ContextManager >
<ApacheConfig />
</ContextManager>

For more information on how to connect Tomcat to Apache using mod_jk, go to http://jakarta.apache.org/tomcat or http://jakarta.apache.org/tomcat/tomcat-3.2-doc/mod_jk-howto.html if you have installed tomcat 3.2 version.

4) 'Soap Authentication module'(mod_soap_auth_XMLsign_bin-unix.zip)  can be downloaded by clicking here. It contains the following files:

a) An Apache module DSO file "mod_soap_auth.so"
b) A dynamic link library "libcrypto.so.0.9.6"
c) A file "soapauthentication.war" containing the servlet and related files.
d) The servlet properties file "SoapAuthenticationServlet.properties" used by the servlet.
e) A certificate file "myPkcs.p12"
f) A "sampleAccess.xml" file. 
g) A configuration file "signature.conf" used by the client application.
h) A folder 'soapclasses' which contains four class files( for signing the soap request).
i) A folder 'exampleclasses' which contains a web service example along with the client application.

5) Place the 'mod_soap_auth.so' file in '/usr/local/Apache/modules' directory available in Apache installation folder.

6) To add this module in the apache server you need to edit '/usr/local/Apache/conf/httpd.conf' file. Open this file in an editor. Add lines
 LoadModule soap_auth_module modules/mod_soap_auth.so (A lot of modules are already been loaded in apache, search for word LoadModule , you will it find it somewhere at line 192, add the above line there ) and
 AddModule mod_soap_auth.c (Add this line few lines below the above line i.e alongwith other AddModules(line 240))

7) Create a group.txt file wherein you will specify the group who is authorized to access a particular service or it's methods. You can specify the usernames as well but this 'Soap Authentication module' will not use these usernames. These usernames are required when you want to use Apache's Authentication module whereas this 'Soap Authentication module' authenticates a user from a certificate file. More than one groups should be specified in seperate lines. e.g.

 group1: user1 user2
 group2: user3 user4

8) Create a folder 'resources' in '/usr/local/Apache/ directory. Copy files group.txt (created in above step), 'sampleAccess.xml' and 'myPkcs.p12' in this resource directory. 

9) Now to enable authentication and authorization we have to make some changes in the file '/usr/local/Apache/conf/httpd.conf' 

In the Directory Configuration section which is shown below

<Directory />
Options FollowSymLinks
AllowOverride None
</Directory>

add the following lines inside the <Directory> tags.

 SoapAuthenticationServletURI /soapauthentication/servlet/authorize

This is used by the module to call the authentication servlet included along with the module. The authentication and authorization
process is actually handled by the servlet and the servlet should have been installed in a servlet container
like Tomcat bridged to Apache.

The result should look like

<Directory />
Options FollowSymLinks
AllowOverride None
SoapAuthenticationServletURI /soapauthentication/servlet/authorize
</Directory>

10) For installing the servlet you need to do the following
a) Copy the file 'soapauthentication.war' available in 'Soap Authentication module' in '/usr/local/Tomcat-3.2.1/webapps' directory.
b) Next create a directory "configFiles" in '/usr/local/Tomcat-3.2.1\bin' if it doesn't already exist and copy the file 'SoapAuthenticationServlet.properties' available in 'Soap Authentication module' into this directory.
c) Open up the file "SoapAuthenticationServlet.properties" in a suitable editor. Set the parameters in it as shown below if they are not already set

soapURI = http://localhost:80/soap/servlet/rpcrouter
accessFileName = /usr/local/Apache/resources/sampleAccess.xml
groupFileName = /usr/local/Apache/resources/group.txt

"soapURI" is the URI that represents your soap RPCRouter.
"accessFileName" represents the web services access file which the servlet uses to authorize the soap request.
Details of this file will be discussed shortly.
"groupFileName" is the group file you created above.

Set these parameters according to your configuration. 

d) Also make sure that the following jar files are included in the classpath of your tomcat
XML parsers                                     - xerces.jar jaxp.jar xalan.jar
Servlet API                                        - servlet.jar
IBM security suit for XML signatures - IBMJCEProvider.jar xss4j.jar
IAIK for XML signatures                   - iaik_jce.jar

You can put all these jars in your Tomcat's lib directory in which case Tomcat will load them automatically. However note that servlet needs xerces.jar ahead of all the other jars in the Tomcat's classpath. So edit 'tomcat.bat' available in Tomcat's bin folder. Search for line
set CP=%TOMCAT_HOME%\classes 
and add  set CP=%CP%;%TOMCAT_HOME%/lib/xerces.jar after this line.
e) Open file "server.xml" available in '/usr/local/Tomcat-3.2.1/conf' directory. Add the following
    <Context path="/soapauthentication"   docBase="webapps/soapauthentication"    crossContext="true"  debug="0" reloadable="true" trusted="false" > 
    </Context>

between <ContextManager></ContextManager> tag.

11) THE WEBSERVICES ACCESS FILE (sampleAccess.xml )

The access file is basically an XML file containing access information. The servlet is informed of its presence
through the "accessFileName" parameter in the file "SoapAuthenticationServlet.properties".

Its structure is shown below in an example situation:

<WebServices>
        <AccessRights>
                <Allow mode="Listed">
                        <User>raj</User>
                        <Group>group1</Group>
                </Allow>
                <Allow mode="Listed">
                        <User>Induslogic Xintegrate</User>
                        <Group>group2</Group>
                </Allow>
                <Deny mode="Listed">
                        <User>vinay</User>
                        <Group>group3</Group>
                </Deny>
        </AccessRights>
        <Service name="urn:demo1:exchange">
                <AccessRights>
                        <Allow mode="Listed">
                                <User>raj</User>
                                <Group>group1</Group>
                        </Allow>
                        <Deny mode="Listed">
                                <User>vinay</User>
                                <Group>group3</Group>
                        </Deny>
                </AccessRights>
                <Method name="getRate">
                        <AccessRights>
                                <Allow mode="Listed">
                                        <User>vinay</User>
                                        <Group>group3</Group>
                                </Allow>
                                <Deny mode="Listed">
                                        <User>raj</User>
                                        <Group>group1</Group>
                                </Deny>
                        </AccessRights>
                </Method>
        </Service>
</WebServices>

The file consists of the main root <WebServices> representing all the webservices and <Service> children of the root
representing each individual webservice. Each <Service> has <Method> children representing the methods available
in the service.

<Service> and <Method> have a "name" attribute that contains the name of the respective service and method.

All these tags have a child called <AccessRights> which defines the rights of
users and groups. /WebServices/AccessRights defines the rights that apply for all the webservices, 
/WebServices/Service/AccessRights does so for each individual service and /WebServices/Service/Method/AccessRights
for each method.

Each AccessRights element has two children <Allow> and <Deny>. They can be used in two modes, "Listed" and "All".
<Allow mode="Listed> means that the users and/or groups that will be allowed will be enumerated,
while <Allow mode="All"> means that all users and groups are allowed. The same applies to <Deny>.
Each <Allow> or <Deny> in listed mode has multiply occurring <User> and <Group> elements enumerating the allowed
or denied entities.

The file is interpreted in the following manner. The <Deny> directive has precedence over <Allow> and parents
have precedence over children. That is, if a user/group is to be authenticated for a method, access rights of the 
topmost parent is checked (which is the root), if the entity is denied there then the result is a deny, else if it is
allowed then the child enclosing the requested method is checked in the same manner, and then the particular method
is also checked in the same manner and the entity is thus finally allowed or denied. If the entity cannot be found at
all then it is interpreted as a deny.

12) Now for sending and receiving soap messages you need to have Apache soap.

a) Download it's binary(soap-bin-2.2.tar.gz) from here  if you don't have it already.  
b) Unzip the above zip file. It contains soap.jar file in the lib directory and soap.war file in it's webapps directory. Copy the soap.war file in '/usr/local/Tomcat-3.2.1/webapps' directory.
c) We have made changes to apache soap package so that the soap request being sent is digitally signed. For this unzip soap.jar file. Copy all the class files available in "Soap Authentication module's" soapclasses folder to 'org.apache.soap.transport.http' package (created after unzip) and create the jar again. This jar will be used by the client application.

13) Copy the 'libcrypto.so.0.9.6' file available in 'Soap Authentication module' in your '/usr/lib/' directory. 

14) Deploying a web service:(An example)

a) Web service classes(IExchange.class and  Exchange.class) are given in "Soap Authentication module's" exampleclasses folder. Add these classes in Tomcat's classpath. One way of doing this is to copy these classes in Tomcat's bin directory.
b) First start up Tomcat or whatever servlet container you are using. This is important as Tomcat is bridged to Apache using mod_jk and Tomcat writes a config file "mod_jk.conf-auto" after starting which is included in the file httpd.conf and is used by Apache while starting up. Next start up Apache.You should now have the module up and running.Then type the URL http://localhost:80/soap into your browser and click on Run the admin client when you see the welcome screen. You should see the following screen.

c) To deploy the Exchange service, click on the deploy option and fill in the fields as shown in the following figure. Leave the other fields as they are not required by this example.

 
d) Once you've entered the fields, scroll down and click the deploy button at the bottom of the window. You should see a screen that indicates that the service has been deployed. If you click on the List button, you'll see the URN of your Web service is listed. Click on its link and you should see the information as shown in the following figure

 

15) Run the client(Client.class) to access the method(getRate) of the above deployed service.

Also make sure that the following jar files are included in the classpath of your client
XML parsers                                     - xerces.jar jaxp.jar xalan.jar
Servlet API                                        - servlet.jar
IBM security suit for XML signatures - IBMJCEProvider.jar xss4j.jar
IAIK for XML signatures                   - iaik_jce.jar
For SOAP Requests                          - soap.jar (modified jar file created after adding class files available in the module) mail.jar activation.jar

Note1 : File "signature.conf" available in the module should also be included in the classpath of your client. The soap request being sent is first signed as per the property values of  this "signature.conf" property file. It's one property 'pkcs12.stream' points to the user's certificate file. For the details of other properties please refer the file.

Note 2 : Access to a particular service and method can be changed in sampleAccess.xml file. The  Soap Authentication servlet first reads the Signed SoapRequest and determines the user who signed it. It then parses this sampleAccess.xml  to check whether the user is authorized to access  a particular service and it's methods.

The sampleAccess.xml file supplied allows user 'Induslogic Xintegrate' of 'group2' to access the deployed service and it's only method 'getRate'. The supplied "signature.conf" file  has been created by the user 'Induslogic Xintegrate'. It property  'pkcs12.stream' points to '/usr/local/Apache/resources/myPkcs.p12', the certificate file supplied with the module. In order to successfully run your client application and access the above deployed webservice, make sure that you have created a group.txt file which contains a group 'group2' and that you have placed this group file alongwith the 'sampleAccess.xml' and 'myPkcs.p12' in the '/usr/local/Apache/resources' directory. If all these files are placed in a different location, then edit 'signature.config'  for the location of 'myPkcs.p12' and 'SoapAuthenticationServlet.properties' for group.txt and sampleAccess.xml.