Note: In the following, <tomcat> refers to the directory where you installed the Apache Tomcat server being used for your XMC Cat server. The Axis2 web service is deployed in the webapps folder of your tomcat, and the expanded directory for that war in your webapps folder is referred to as <axis2> in this section. Your XMC Cat server is deployed in the services directory of your <axis2>/WEB-INF/services directory in a folder named "CatalogService". The CatalogService folder within that services directory is referred to here as <xmccat>.
Step 1: Setting up the certificate You need to have a certificate for your XMC Cat service. Please refer to the following link that discusses creating and installing a certificate that a tomcat server can use:
Step 2: Make the following changes server.xml in <tomcat>/conf/:
- Comment out the non-ssl connection in server.xml
- Define an SSL HTTP/1.1 connector on the port you wish to use to setup the secure connection to your XMC Cat. For example:
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreFile="/home/mycertificate" keystorePass="password" keystoreType="PKCS12" keyAlias="tomcat"/>
The above example for setting up a secure connection is based on version 6 of Apache Tomcat. Different versions of Tomcat may require different parameter settings.
Step 3: Deploying Apache Rampart: If you installed XMC Cat using the war file installation that wraps XMC Cat within Axis2, then you can skip this step; these modules are already included in the modules folder of the Axis2 that was installed. Transport-level security using Apache Rampart has been tested with XMC Cat based on version 1.5.1 of Rampart, but should work with later versions.
- Download the Apache Rampart standard binary distribution from here and copy the two module files rampart-1.5.1.mar and rahas-1.5.1.mar from the modules directory of the distribution into the <axis2>/WEB-INF/modules directory of your tomcat.
- Copy all of the jars from the lib folder of the Apache Rampart standard binary distribution to the <axis2>/WEB-INF/lib folder.
- After deploying the Rampart modules and jar dependencies, Tomcat should be restarted to check whether Apache Rampart was successfully deployed. To check if Rampart was deployed successfully, point your web browser to https://<server name:port number>/axis2/ and in the page that is displayed, log in to axis2 as admin with the password axis2 and select the system components/available modules option in admin web console. Both "rampart" and "rahas" should be listed as available modules, if they were successfully deployed.
Step 4: Configuring Axis2 to use Rampart security:
- Comment out the following line in your <axis2>/WEB-INF/conf/axis2.xml file (about 1/3 of the way through the file):
<transportReceiver name="http" class="org.apache.axis2.transport.http.AxisServletListener"/>
- Add the following lines where you commented out the above line:
<transportReceiver name="http" class="org.apache.axis2.transport.http.AxisServletListener"> <parameter name="port">8080</parameter> </transportReceiver>
<transportReceiver name="https" class="org.apache.axis2.transport.http.AxisServletListener"> <parameter name="port">8443</parameter> </transportReceiver>
If you installed XMC Cat using the war file installation that wraps XMC Cat within Axis2, then the above two lines will already be in your axis2.xml file but will be commented out since the default installation is without security enabled. In that case, just comment out the line mentioned in the first bullet point above, then uncomment these lines and change the port settings as discussed below.
If you have a non-secure port setup on your server, put that port address in the http transportReceiver above instead of port 8080. If you do not have a nonsecure port setup, then omit adding the http transportReceiver listed above (or comment it out for now). In the https transportReceiver, set the parameter value to the port you identified as the port for the secure (SSL) connection in step 2 above instead of port 8443.
Step 5: Enabling security in XMC Cat
- Engage the required modules by uncommenting the following module references near the top of the services.xml file in the <xmccat>/META-INF/ directory.
<module ref="rampart"/> <module ref="addressing"/>
- Also in the <xmccat>/META-INF/services.xml file are parameters for the port, serviceUrl, and deliveryUrl. If you setup your secure connection on a different port, then the port setting in all three of these parameters needs to be updated. Also, protocol in the serviceUrl, and deliveryUrl parameters needs to be changed to "https" instead of "http".
- Restart your Tomcat server and the XMC Cat service will be enabled as a secure service.
Step 6: Define trusted services as users
For each service that you want to add as a trusted service, a user name and password needs to be added to the registered_services table in XMC Cat. The password is saved as a hashed value. To define a new user, at the command line in your XMC Cat database run the spRegisterService stored procedure:
Replace the "name" and "password" values with the name and password for the trusted service you are setting up as a user. Since both parameters are being passed in the stored procedure as string values, they should be enclosed in single quotes as shown above.
Each user name must be unique, so an SQL error will be thrown if the user ID is already defined.