Article

(View Disclaimer)

Authors:

Anil kumar sekhara
K. Surya Satya Narayana

Contents:

• Overview
• Objective
• Prerequisites
• Configuring HTTPS for SSL Connection Between DSML Service and Identity Manager
• Configuring Mutual Authentication Between DSML Service and Identity Manager
• Conclusion

Overview

The Identity Manager engine uses XDS, a specialized form of XML, to represent events in the Identity Vault. Identity Manager passes the XDS to the driver policy, which consists of basic policies, DirXML script, and XSLT style sheets. On the subscriber channel, the SOAP driver policy translates the XDS to XML. On the publisher channel, the SOAP driver policy translates other forms of XML into XDS.

The SOAP driver shim receives the XML from the driver policy. Generally, SOAP driver shim uses HTTP to communicate with the Web service. In advance, IDM can be also configured to have HTTPS to transfer the XML data in secure channel. Along with secure XML data transfer, the SOAP services should be able to identify the SOAP clients.

HTTPS with SSL provides:

1. Message confidentiality
2. Handshaking which may be done by using key pair algorithm, for end point authentication
3. Encryption which is generally done by using secret key
4. Message Transport which includes message integrity
5. Support of digital signatures with SHA1+RSA

Using SSL during authentication process makes very powerful instrument in the arsenal against attackers. The main advantage of SSL (or TLS) is that this is protocol independent.

IDM SOAP driver supports SSL-based data transfer and mutual authentication to support secure data transfer and data integrity. Mutual authentication is explained as the need for IDM SOAP driver to authenticate itself to Novell SOAP-DSML web service that can be established on the SOAP-DSML web service side.

This appnote describes the process of configuring:

1. Novell SOAP-DSML web service for:
   
   1. HTTPS authentication
   2. Mutual authentication
2. Configuring IDM SOAP driver for:
   
   1. HTTPS authentication
   2. Mutual authentication

This AppNote makes use of "Security Best Practices of Identity Manager Security" guide, and recommends customers to configure SOAP driver for the best security practices.

Objective

The objective is to transfer data over SSL between Identity manager and Novell SOAP-DSML services, configure Novell SOAP-DSML web service and IDM 3.6 SOAP driver for mutual authentication.

Prerequisites

• eDirectory 883 having IDM 3.6 with SOAP driver
• eDirectory 88x as LDAP server
• Apache-tomcat-4.1.37-LE-jdk1.4 (with Java 1.4 or later) with DSML v2 for eDirectory deployment
• Novell certificate server installed with eDirectory 88x

Configuring HTTPS for SSL Connection Between DSML Service and Identity Manager

DSML v2 web service should be configured with a X509 digital certificate to establish SSL connection between DSML v2 web service and Identity manager. The digital certificate can be obtained by:

1. Generating a Certificate Signing Request (CSR)
2. Submitting the CSR to the Novell certificate server.

The certificate server that has been used to issue digital certificate to DSML v2 web service should be trusted by Identity manager and keystore of DSML v2 web services.

Reasons for trusting CA certificate by Identity Manager are:

• Public key cryptography requires access to public keys of end entities. End entities can be LDAP users, LDAP servers, Application servers, or web servers. This appnote considers 1. Novell eDirectory LDAP server 2. Apache Tomcat server and administrator of Apache tomcat server 3. IDM SOAP DSML driver as end entities. In a large-scale networked environment, it is impossible to guarantee that prior relationships between communicating entities have been established or that a trusted repository exists with all used public keys. X509 digital certificates are solution to this public key distribution problem.
• Certification Authority (CA) can act as a trusted third party. CAs are entities (for example, businesses) that are trusted to sign (issue) certificates for other entities like LDAP servers, application servers, and so on. It is assumed that CAs only create valid and reliable certificates because they are bound by legal agreements. This appnote uses Novell Certificate authority as certificate issuing authority. You can also run your own Certification Authority using products such as the Netscape/Microsoft Certificate Servers or the Entrust CA product for your organization, based on your organization's policies.

Therefore, to perform cryptographic operations like data encryption, digital signatures with Apache tomcat DSML v2 web service, the certificate of CA, which issued Apache tomcat DSML v2 web service certificate, should be trusted and imported into trusted root store.

Configuring Mutual Authentication Between DSML Service and Identity Manager

After SSL is established between DSML web service and SOAP driver, verification of IDM SOAP driver at DSML v2 web service provides better security by means of "authentication". Also it enables IDM SOAP driver to digitally sign the body of a SOAP envelope and include the signature information in the envelope header. When DSML web service receives the digital signature from the IDM SOAP driver, it verifies whether the SOAP envelope received is tampered.

For SOAP driver authentication at Apache Tomcat web server side, SOAP driver should be configured with a X509 client certificate.

Because Apache tomcat web server gets authenticated to SOAP driver, SOAP driver gets authenticated to Apache Tomcat web server, this process can be called as "X509 certificate based mutual authentication". The certificate server that has been used to issue digital certificate to IDM SOAP driver should be trusted by Novell DSML web service.

Setup process

Setup diagram

The following diagram shows different components required for setting up environment to make use of this appnote.

Click to view.

Figure 1: Components required to configure SOAP driver with mutual authentication

After configuring "X509 certificate based mutual authentication", when SOAP driver has started, "Mutual authentication" happens between SOAP driver and SOAP based web service and SSL tunnel is established between them. The following diagram describes detailed data flow between different components when SOAP driver is deployed.

Click to view.

Figure 2: Data flow between different components using SOAP driver

1. HTTPS communications between SOAP driver and SOAP based web service

   Communication process between IDM SOAP driver and SOAP based DSML v2 web service uses HTTPS with SSL, while performing SOAP operations like DSML requests and responses.

   This includes:

   1. Novell SOAP web service authentication to IDM SOAP driver
   2. Client IDM SOAP driver authentication to Novell SOAP web service
   3. SSL/TLS protocol based communications between IDM SOAP driver and Novell SOAP web service
2. LDAP/LDAPS communication between SOAP based web service and application store(eDir 88x LDAP server)

Communication process between Tomcat with Novell DSML v2 web services and eDir 88x can use either LDAP or LDAPS, while performing LDAP operations like LDAP bind, LDAP search, LDAP add, and so on.
Security best practices suggest to use LDAP bind to authenticate a user, and to ensure the connection is not just public or anonymous.

User can authenticate to eDirectory by providing user name and password. LDAP user authentication can be more secure when mutual authentication is configured between application store(eDirectory 88x LDAP server) and SOAP based web service.

During mutual authentication process between Application store (eDir88x LDAP server) and SOAP web service:

• Application store's (eDir 88x LDAP server) digital certificate authentication happens at SOAP based web service.
• SOAP based web service digital certificate authentication happens at application store (eDir 88x LDAP server side).
• TLS/SSL protocol based communications between SOAP web service and Application store (eDir 88x LDAP server).

LDAPS communications are optional to make use of this appnote. But LDAPS communications provide secure communications between Application store (eDir 88x LDAP server) and SOAP based web service(LDAP client).

For configuring SSL and mutual authentication in eDirectory 88x, refer Section 14.6, Authentication and Security of Novell eDirectory 883 Administration guide.

The basic steps in the setup process are explained as below :-

Step 1: Configuring SSL and Mutual Authentication for SOAP Web Service:

Tomcat with Novell DSML v2 services should be installed and configured in order to configure SSL for Tomcat SOAP web service.

Tomcat application server software can be downloaded from http://jakarta.apache.org/tomcat.

Novell DSML v2 services software can be downloaded from http://developer.novell.com/wiki/index.php/DSML_for_eDirectory_(SOAP).

Documentation for deployment and configuration of Novell DSMLv2/SOAP can be obtained from same location.

1. After successfully deploying SOAP, configure SOAP web service for SSL.
   
   1. Run the keytool at command prompt, as shown below:
      

      keytool -genkey -alias mykey -keystore .keystore

      Java key tool uses the default "DSA" key generation algorithm to create the keys, both 1024 bits long.

      But Novell security standards suggest and enforces to make use of "RSA" key generation algorithm to create the keys.

      So, while performing cryptographic operations, Identity manager and its components make use of RSA" key generation algorithm.

      An example of the run is shown below.

      stdir-c3c-125:/opt/jdk1.5.0_13/bin # export PATH=/opt/jdk1.5.0_13/bin:$PATH
      stdir-c3c-125:/opt/jdk1.5.0_13/bin # keytool -genkey -keyalg RSA -keysize 1024 -alias mykey -keystore /root/.keystore
      Enter keystore password: novell
      What is your first and last name?
      	 [Unknown]: stdir-c3c-125
      What is the name of your organizational unit?
      	 [Unknown]: STEG
      What is the name of your organization?
      	 [Unknown]: Novell
      What is the name of your City or Locality?
      	 [Unknown]: Bangalore
      What is the name of your State or Province?
      	 [Unknown]: Karnataka
      What is the two-letter country code for this unit?
      	 [Unknown]: IN
      Is CN=stdir-c3c-125, OU=STEG, O=Novell, L=Bangalore, ST=Karnataka, C=IN correct?
      	 [no]: yes
      Enter key password for <my>
      	   (RETURN if same as keystore password): novell.	
      		
      

   2. Run the keytool at command prompt to generate CSR as below
      

      keytool -certreq -file <filename_csr>.csr

      An example of the run is shown below :-

      stdir-c3c-125:~ # keytool -certreq -file stdir-c3c-125.csr

      Enter keystore password: novell.

      A certificate signing request file should be created in the location where the keytool is run.

   3. Now, submit the CSR generated in step (ii) to Novell certificate server. This can be processed by login into eDirectory and browsing to Novell certificate server -->issue certificates.

      An example of the issuing certificate for SOAP web services is shown below.

   

   Click to view.

   Figure 3: Browse the certificate signing request file and click on next button.

   

   Click to view.

   Figure 4: Specification of key usage for SOAP web service certificate

   

   Click to view.

   Figure 5: Specification of certificate parameters for SOAP web service server certificate

   

   Click to view.

   Figure 6: Downloading SOAP web service certificate from Novell PKI server

   4. Import Certificate authorities certificate and SOAP web service server certificate.
      
      1. Obtain the Novell certificate server certificate as shown in following diagrams
      

      Click to view.

      Figure 7: Obtaining Novell CA certificate from Novell PKI server

      

      Click to view.

      Figure 8: Obtaining Novell CA certificate from Novell PKI server contd...

      

      Click to view.

      Figure 9: Obtaining Novell CA certificate from Novell PKI server contd...

   5. After obtaining CA certificate from Novell certificate server, import it into trusted CA store of SOAP web services.

      To import, run the keytool at command prompt as follows:

      keytool -import -file <filename> -keystore <keystore_location> -alias <Name>

      An example of the run is shown below.

      stdir-c3c-125:~ # keytool -import -file /root/TrustedCA.b64 -keystore /root/.keystore -alias ApacheCA
      Enter keystore password: novell
      Owner: O=T162, OU=Organizational CA
      Issuer: O=T162, OU=Organizational CA
      Serial number: 21c11ffa4d5e6a3a500cf8d5e01ffb38163891df23744a8e581ac5c09ed0202020d7a73
      Valid from: Wed Aug 20 00:19:39 IST 2008 until: Mon Aug 20 00:19:39 IST 2018
      Certificate fingerprints:
         MD5: 7E:BA:A1:97:36:2E:5F:88:CD:34:F0:00:17:F2:9B:BA
         SHA1: B1:8D:F5:34:5B:B3:7E:6D:B3:E0:23:D6:A3:4A:17:08:06:E3:D1:46
      Trust this certificate? [no]: yes
      Certificate was added to keystore	
      	
      

   6. Now import the SOAP web service certificate.

      To import run the keytool at command prompt as shown below

      keytool -import -file <filename> -keystore <keystore_location> -alias <Name>

      An example of the run is shown below

      stdir-c3c-125:~ # keytool -import -file /root/stdir-c3c-125.b64 -keystore /root/.keystore -alias mykey
      Enter keystore password: novell
      Certificate reply was installed in keystore
      
      

	<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
	port="8443" enableLookups="true" scheme="https" secure="true"
	acceptCount="100"
	 	keystoreFile="/root/.keystore"
		keystorePass="novell"
		keyAlias="mykey"
	        truststoreFile="/root/.keystore"
		truststorePass="novell"
	useURIValidationHack="false" disableUploadTimeout="true"
	clientAuth="true" sslProtocol="TLS" />>
	

After configuring SOAP web service for SSL connection, restart the SOAP web service.

To do so, browse /<Apache Server installation directory> /apache-tomcat-4.1.37-LE-jdk1.4/bin. Use shutdown.sh and startup.sh.

Example to restart the SOAP web service is shown below.

           	export JAVA_HOME=/opt/jdk1.5.0_13
          	 cd /root/apache2/apache-tomcat-4.1.37-LE-jdk1.4/bin/
          	./shutdown.sh
         	 ./startup.sh
		

After SOAP web service is restarted, Novell DSML v2 SOAP web service can be accessed from web browser as:https://<host name or IP Address>:8443/novell-dsml/index.html.

An example for accessing the web services is shown below.

Click to view.

Figure 10: Accessing Novell DSML Services from web browser

[Optional] Step for configuring LDAPS based mutual authentication between SOAP web service and application store (eDir 88x LDAP server):

If you want to configure LDAPS based mutual authentication between Novell DSML v2 web service and Novell edirectory 88x LDAP server. Following changes have to be done on Apache tomcat web service machine:

Open /<Apache Tomcat_Installation location>/apache-tomcat-4.1.37-LE-jdk1.4/<Novell DSML web service deployment directory>/WEB-INF/web.xml.

Add the following:

	<context-param> 
	<param-name>ldapKeystore</param-name> <paramvalue>
	</param-value>keystore Location</context-param> 
	   

Restart the web service.

An example of this is shown below.

	<!-- contains the path to the TLS (SSL) Keystore -->
	<context-param>
	<param-name>ldapKeystore</param-name>
	<param-value>/root/.keystore</param-value>
	</context-param>
		

Step 2: Configuring SOAP DSML Driver for SSL communications using Sample SOAP/DSML Configuration File

For SSL communications, SOAP driver is designed to make use of either Java-based keystore or Novell-based certificate management and KMO store. So, IDM Administrator can configure SSL by using Java based keystore or Novell certificate server and Novell certificate access.

Why should we use either java based keystore or Novell based KMO? While establishing web service based SSL, web service server's digital certificate should be verified by SOAP driver. While server certificate gets verified, IDM driver validates it based on 1) Validity period of certificate 2). Trusted certificate chain 3). Subject name of certificate. While validating trusted certificate chain, SOAP driver checks whether the Novell SOAP web service certificate is issued by trusted CA . So, before trusted certificate chain validation, the CA certificate that is used to issue certificate to Novell SOAP web service, should be explicitly trusted by IDM SOAP driver.

Also, when Mutual authentication is configured, SOAP Driver uses its public/private key pair along with client certificate for secure SSL communications. So, in order to generate keys and manage keys along with certificates, the key store or Novell certificate access store is used. Hence configuring Java-based keystore or Novell-based KMO store is required on SOAP driver machine.

Following process explains configuring keystore on SOAP driver machine.

1. Creating a java key store and importing trusted CA certificate into java key store on IDM meta directory machine.

When SOAP/ DSML driver is configured for SSL connection using HTTPS protocol, SOAP/DSML server sends its server certificate to SOAP/DSML server. This SOAP/DSML server certificate is issued by Novell certificate server. In order to validate the the SOAP/DSML server certificate, SOAP/DSML driver should trust the certificate server. The trust is established by importing CA certificate into keystore using java keystore tool.

To generate SOAP driver keys and certificate, follow Step 1. After generating SOAP driver client certificate, the Trusted CA that issed certificate to Novell SOAP web service should be imported into trusted root store.

To import run the keytool at command prompt as follows:

keytool -import -file <filename> -keystore <keystore_location> -alias <Name>

An example of the run is shown below.

	stdir-d2g-161:~ # keytool -import -file /root/TrustedCA.b64 -keystore /root/.keystore -alias ApacheCA
	Enter keystore password: novell
	Owner: O=T162, OU=Organizational CA
	Issuer: O=T162, OU=Organizational CA
	Serial number: 21c11ffa4d5e6a3a500cf8d5e01ffb38163891df23744a8e581ac5c09ed0202020d7a73
	Valid from: Wed Aug 20 00:19:39 IST 2008 until: Mon Aug 20 00:19:39 IST 2018
	Certificate fingerprints:
      	  MD5: 7E:BA:A1:97:36:2E:5F:88:CD:34:F0:00:17:F2:9B:BA
         	SHA1: B1:8D:F5:34:5B:B3:7E:6D:B3:E0:23:D6:A3:4A:17:08:06:E3:D1:46
	Trust this certificate? [no]: yes
	Certificate was added to keystore
	

The Novell certificate server's certificate is now successfully imported into java key store on to server that IDM metadirectory.

2. Using iManager 2.7 or Designer 3.0, configure SOAP/DSML driver:

   When we configure IDM SOAP/DSML driver for SSL connections with mutual authentication, we should configure:

   1. a)Subscriber-based mutual authentication parameters
   2. b)Publisher-based mutual authentication parameters
3. Publisher channel provides options for one of the following:

   To make use of Novell Based PKI certificate (KMO object) for client authentication at Novell SOAP Web service.

   The Private key/Public key certificate(in general mykey) , that gets generated using Java key tool, for client authentication at Apache tomcat Web service IDM SOAP/DSML driver.

   This appnote describes publisher channel configuration using Java keystore.
   Subscriber channel makes use of Private key/Public key certificate (in general mykey), that is generated using Java key tool.

   While configuring,

   1. Provide URL of the remote DSML server as https://<host name of Apache server>:8443/novell-dsml/stream. Note that host name of Apache server should match with the subject name of X509 certificate of the server that is generated and issued in step 1.
      Example: https://stdir-c3c-125:8443/novell-dsml/stream.
   2. Specify the authentication ID for remote DSML server.
      Example:- cn=admin,o=novell.
   3. Specify authentication Password for ID.
   4. Specify the authentication ID to validate incoming DSML requests.
      Example: cn=admin,o=novell.
   5. Specify authentication Password for ID.
   6. In subscriber settings, set Truststore file = "location of key store file".
      Example Truststore file = \root\.keystore
   7. Set mutual authentication parameters : show.
   8. In subscriber settings, Keystore file= = "location of key store file".
      Example Keystore file= \root\.keystore
   9. Specify Keystore password.
   10. In publisher settings, specify Listening IP address and port.
       Example: 164.99.178.161:18180
   11. Specify Authentication ID.
       Example: cn=admin,o=novell.
   12. Specify Authentication Password.
   13. Set Require mutual authentication to "required".
   

   Click to view.

   Figure 11: Configuring SOAP/DSML driver using iManager

   

   Click to view.

   Figure 12: Configuring SOAP/DSML driver using iManager contd..

   

   Click to view.

   Figure 13: Subscriber and Publisher configuration settings for mutual authentication

4. After deploying the IDM SOAP/DSML driver, start the driver. When data synchronization starts, Apache tomcat server and driver mutually authenticate each other. SSL connection is established, then data between eDirectory and connected SOAP application server, and then to directory 88x LDAP server.
   SSL related information can be observed in trace. The following figure shows some information related to SSL Connection.
   

   Click to view.

   Figure 14: Information related to SSL Connection in Driver trace

   When certificate related information for Identity manager is not properly provided, the following possible error messages in identity manager's trace can be seen.

   1. Received fatal alert: bad_certificate: Possible causes for this error are 1). Keystore file and keystore password provided in subscriber channel settings are wrong or blank. 2).KMO name or Keystore file provided in publisher channel settings are wrong or blank. "Wrong certificate" can be a valid certificate that has been issued by untrusted CA also

      Solution: Provide correct keystore name, keystore password or KMO in corresponding settings.

   2. No subject alternative names present: Possible cause for this error is host name in URL of the remote DSML server name in SOAP Driver configuration setting is not matched with the subject name of Apache tomcat web service certificate.

      Solution: Provide host name in URL of the remote DSML server name in SOAP Driver configuration that is same as subject name of Apache tomcat web service certificate.

   3. Could not find trusted certificate: Possible causes for this error is CA certificate has not been imported into respective java keystore.

      Solution: Import correct CA certificates and its certificate chain into java key store.

Conclusion

We hope you now understand more about securing IDM SOAP driver and SOAP Web Services using SSL and mutual authentication. This is just an implementation and deployment to distribute data using SSL and X509 digital certificates for SOAP DSML driver. This AppNote can be a base for deploying SOAP driver with SSL for secure data transfer. Also this AppNote is base for configuring SSL using enhanced methods like Novell PKI and so on.

Disclaimer: As with everything else at Cool Solutions, this content is definitely not supported by Novell (so don't even think of calling Support if you try something and it blows up).

It was contributed by a community member and is published "as is." It seems to have worked for at least one person, and might work for you. But please be sure to test, test, test before you do anything drastic with it.