Configure Oracle HDR as a Document Repository

Configure Registry for Accepting Register Document Set-b Web Service Calls

The registry server URL has to be configured for enabling HDR to send Register Document Set-b request web service calls to external document registries.

The registry URL should be a valid web service endpoint URL implementing XDS.b Register Document Set-b specification.

The web service end point URL could be an http URL or secure https URL. In case of https connections to registry server, the necessary truststore and keystore files need to be generated and configured in <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/config/hdr/ihe_xdsb_config.xml under the REGISTRY_AUDIT_SERVER_SSL_CONFIG configuration name.

where, <weblogic_install_dir> is the file path where the WebLogic server has been installed. <weblogic_domain_name> represents the name of WebLogic domain.

Refer to: http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/keytool.html to learn more about digital certificates and using jdk's keytool to generate keystore and truststore.

Configure Repository for Syslog Audit Messages

HDR generates the following Syslog audit event messages:

Actor Start Audit Event
Actor Stop Audit Event
Local user authentication success or failure audit event
Security Alert Audit Event for change in System configurations
Register Document Set Audit Event
Provide and Register Document Set Audit Event
Retrieve Document Audit Event

HDR can be configured to send audit messages to syslog audit server over UDP or TLS protocol. The Syslog audit messages are per RFC 5424 standard.

You must configure the Syslog audit server host, port number, and transport protocol (UDP or TLS) profile options to enable HDR to send audit messages to Syslog audit server. The Syslog server host and port number should be a valid server host and port number.

Configure Repository Unique ID

You must configure the HDR Document Repository's Unique Id. This id will be added to the Register Document Set-b requests sent out by HDR to external registry. The Repository Unique Id should be a valid OID.

User Creation in 'myrealm' WebLogic Server realm for IHE XDS.b Web Services

Create the user IHE_XDS_USER in WebLogic default server realm'myrealm' for IHE XDS.b Web services.

Configure HDR as a Time Client Actor

Time synchronization is important for security and auditing purpose to provide a synchronized time trail in the logs. It is also important in Web service security where the client can send a timestamp. In this way, no one snooping the traffic on the wire can affect a replay of the packet being sent, as the server will report an error once the timestamp has expired.

The IHE Consistent Time Integration Profile provides a means to ensure that the system clocks and timestamps of many computers in a network are well synchronized. It specifically means the servers and clients in the system must have their system time synchronized with a Time Server. This can be achieved in a Linux server by setting up the Network Time Protocol (NTP) service to synchronize with the Time Server.

Once the machine starts, identify a Time Server with which you need to synchronize your machine, and perform the following steps:

Log in as root.
Change the time zone to your required location. For example, to change to a Central Time Zone, run the command:ln -sf /usr/share/zoneinfo/CST6CDT /etc/localtime
Edit /etc/ntp.conf by adding the following line, and save it:server 10.1.1.1 #Any Time Server you want to synchronize with.
Check whether the ntpd service is running using the following command:service ntpd status
If the ntpd service is not stopped, run the command:service ntpd stop
Make the first-time synchronization using the following command:ntpdate 10.1.1.1
Make the second and subsequent synchronizations (if required) by using the same command above until the offset shows 0.xxxx or -0.xxxx.
Now start the ntpd service using the following command:service ntpd start
To enable the ntpd service to run all the time even after restart, run the following command:chkconfig --level 2345 ntpd on
To query the time synchronization status, issue the following command:ntpq -p -n
Perform the above steps both on the HDR host OS.
Shut down the WebLogic Managed Server on which HDR is deployed to, and bring it up after the setup.

Configure HDR a Secure Node Actor

A Secure Node is a system unit that validates the identity of any user as well as any other node, and determines whether this user is allowed to access the system and exchange information with other nodes or not.

A Secure Application provides security features only for the application features. HDR's IHE XDS.b is a Secure Application. The difference between the Secure Node and the Secure Application is the extent to which the underlying operating system and other environments are secured. A Secure Node includes all aspects of user authentication, file system protections, and operating environment security. The Secure Application is a product that does not include the operating environment.

Set HDR for TLS Communication with Document Source and Document Consumer

HDR requires certificates to be loaded into the Keystore & Truststore of WebLogic Managed Server for TLS communication with Document Source actors and Document Consumer actors.

To configure the Identity and Trust for WebLogic Server, follow the steps provided in the link http://docs.oracle.com/middleware/1212/wls/SECMG/identity_trust.htm#i1196575.

Enable SSL to secure communication between client and the HDR application. For configuring the SSL, follow the steps provided in the link http://docs.oracle.com/middleware/1212/wls/SECMG/ssl.htm#i1194343. Under Advanced section of SSL configuration, set Hostname Verification to None, enable Use Server Cert’, and set Two Way Client Cert Behaviour option to Client Certs Requested and Enforced.

Set Up HDR for TLS Communication with Document Registry and Syslog Audit Server

Edit <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/config/hdr/ihe_xdsb_config.xml and enter the absolute paths to trustStore, keyStore and values for trustStorePassword, keyStorePassword, keyStoreType and cipherSuites that will be used for secure TLS communication with Document Registry and Syslog Audit Server under configuration item with name REGISTRY_AUDIT_SERVER_SSL_CONFIG. Enter comma seperated names of the cipher suites to be used for TLS communication for cipherSuites.

Configuration parameter netDebug can be set to any of the valid values application for JVM argument javax.net.debug

These configuration parameters will be used to set the java runtime arguments javax.net.ssl.trustStore, javax.net.ssl.keyStore, javax.net.ssl.trustStorePassword, javax.net.ssl.keyStorePassword, javax.net.ssl.keyStoreType, javax.net.debug and https.cipherSuites.

Generate Audit Event - OS Level Authentication Events

HDR provides the capability of logging OS Level Authentication Events to qualify as a Secure Node actor.

Perform the following steps on the remote machine where HDR is deployed:

Log in to the machine as root user and edit the file /etc/syslog.conf to add the following entry:authpriv.* |/var/log/syslog_auth.pipe
Create a named pipe 'syslog_auth.pipe' under the /var/log directory by using the mkfifo command, as follows:> cd /var/log > mkfifo syslog_auth.pipe
Change the owner and group of the pipe to <OS User>. Since the shell script that would read the content from this file will be somewhere in <OS User> home directory, change the owner and group of this file using the following commands:> chown <OS User> syslog_auth.pipe > chgrp <OS User> syslog_auth.pipe
Restart the syslog service using the following command:> service syslog restart

„Log in to the machine as <OS User>, and create a script, send_audit_event_for_user_authentication.sh. Copy the following content to that file. Also, ensure that Java 1.7 executable is in the path

#!/bin/sh  

#update the log file location
  
  logFile=/home/hiauser/atna.log
  
  
  
  #update the logging.properties file location
  
  log4JFile=/home/hiauser/logging.properties
  
  
  
  transportProtocol=""
  
  wlHost=""
  
  wlPort=""
  
  wlUserName=""
  
  wlPassword=""
  
  keystore=""
  
  keystore_password=""
  
  truststore=""
  
  truststore_password=""
  
  
  
  tmpPswd=somePswd
  
  tmpPswdCnfm=somePswd
  
  tmpInput=""
  
  
  
  
  
  function getPassword {
  
  read -s -p "Please enter $1: " tmpPswd
  
  echo
  
  read -s -p "Confirm password: " tmpPswdCnfm
  
  echo
  
  if [ "$tmpPswd" =  "$tmpPswdCnfm" ]
  
  then
  
  echo
  
  else
  
  echo "Entered password did not match, exiting."
  
  tmpPswd=""
  
  tmpPswdCnfm=""
  
  exit 1;
  
  fi
  
  }
  
  
  
  function getInput {
  
  for i in {1..3}
  
  do
  
  read -p "Please enter $1:" tmpInput
  
  echo
  
  if [ "$tmpInput" != "" ]
  
  then
  
  break
  
  fi
  
  
  
  if [ "$i" -eq 3 ]
  
  then
  
  echo "Did not get the input, exiting."
  
  exit 1;
  
  fi
  
  done      
  
  
  
  }
  
  
  
  #How do you want to send the audit messages to Audit Repository server, over TLS or UDP?
  
  getInput "TransportProtocol (UDP or TLS)"
  
  transportProtocol=$tmpInput
  
  
  
  # WebLogic Host
  
  getInput "Weblogic Managed Server Host"
  
  wlHost=$tmpInput
  
  
  
  # WebLogic Port
  
  getInput "Weblogic Managed Server Port"
  
  wlPort=$tmpInput
  
  
  
  # WebLogic Admin UserName
  
  getInput "Weblogic UserName"
  
  wlUserName=$tmpInput
  
  
  
  # WebLogic Adin User Password
  
  getPassword "Weblogic Password"
  
  wlPassword=$tmpPswd
  
  
  
  if [ "$transportProtocol" == "TLS" ]; then
  
  #The keystore file location.
  
  getInput "Absolute Path to Keystore File"
  
  keystore=$tmpInput
  
  
  
  #The keystore password
  
  getPassword "Keystore Password"
  
  keystore_password=$tmpPswd
  
  
  
  #The truststore file location.
  
  getInput "Absolute Path to Truststore File"
  
  truststore=$tmpInput
  
  
  
  #The truststore password
  
  getPassword "Truststore Password"
  
  truststore_password=$tmpPswd
  
  fi
  
  #<Weblogic home> - represents the WebLogic home and should be replaced with the actual file path where WebLogic is installed.
  
  #<HDR product install home> - represents the HDR product install home and should be replaced with the actual file where HDR product is installed.
  
  CLASSPATH=<Weblogic home>/oracle_common/modules/javax.ejb_3.2.0.jar:<HDR product install home>/weblogic/jars/hdrclnt.jar:<HDR product install home>/weblogic/jars/wlfullclient.jar
  
  
  
  if [ "$transportProtocol" == "UDP" ]; then
  
  JAVA_OPTIONS="-classpath $CLASSPATH -DLogFile=$logFile -Djava.util.logging.config.file=$log4Jfile -Dwl.user.name=$wlUserName  -Dwl.user.pass=$wlPassword -Dwl.host.address=$wlHost -Dwl.listen.port=$wlPort"
  
  else
  
  JAVA_OPTIONS="-classpath $CLASSPATH -DLogFile=$logFile -Djava.util.logging.config.file=$log4Jfile -Dwl.user.name=$wlUserName -Dwl.user.pass=$wlPassword -Dwl.host.address=$wlHost -Dwl.listen.port=$wlPort -Dkeystore=$keystore -Dkeystore_password=$keystore_password -Dtruststore=$truststore -Dtruststore_password=$truststore_password"
  
  fi
  
  ( 
  
  cat < /var/log/syslog_auth.pipe | while read entry
  
  do
  
  LoggedInUser=`echo $entry | grep 'Accepted' | awk '{print $9 }'`
  
  if [ "${LoggedInUser}" != "" ]; then
  
  java $JAVA_OPTIONS oracle.apps.ctb.ihe.xdsb.logger.audit.server.TLSSecureNodeAuditLogger $LoggedInUser Login
  
  
  
  fi
  
  
  
  LoggedOutUser=`echo $entry | grep 'session closed for user' | awk '{print $11 }'`
  
  if [ "${LoggedOutUser}" != "" ]; then
  
  java $JAVA_OPTIONS oracle.apps.ctb.ihe.xdsb.logger.audit.server.TLSSecureNodeAuditLogger $LoggedOutUser Logout
  
  
  
  fi
  
  done
  
  ) &

In the script, update the log4JFile and CLASSPATH variables with appropriate values, and then save it.
Change the permissions of the send_audit_event_for_user_authentication.sh file.> chmod 744 send_audit_event_for_user_authentication.sh
Start the following script and provide the input by following the prompts:> sh send_audit_event_for_user_authentication.sh.

Note:
The script runs a set of commands in the background mode once you start the script. The script prompts for the following values:
1. WebLogic Managed Server Host
2. WebLogic Managed Server Port
3. WebLogic Admin User Name
4. WebLogic Admin User Password
In case the user chooses tranportProtocol as TLS then the script prompts the following additional values:
1. Absolute Path to Keystore File
2. Keystore password
3. Absolute Path to Truststore File
4. Truststore password

Configure ITI-42 Timeouts for IHE XDS Registry Web Service Call

The IHE XDS configuration file /user_projects/domains//config/hdr/ihe_xdsb_config.xml contains two timeout configurations specific to IHE XDS registry web service call.

The name of the configuration is "WS_CLIENT_CONFIG" which has two components as follows:

httpConnTimeout
httpReadTimeout

httpConnTimeout

httpConnTimeout value is configured in milliseconds and this configuration controls how long the HDR will wait for the network connection to be made with the document registry. If a connection to the document registry cannot be established within this time, HDR will fail the entire PnR transaction and return a failure response to the client. The default value for this configuration is 3000 milliseconds. Set this value to a optimum value so that HDR can make a successful network connection with the document registry when available.

httpReadTimeout

httpReadTimeout value is configured in milliseconds and this configuration controls how long the HDR will wait for the document registry to respond with a success or failure. If the document registry does not respond with a response within this time, HDR will fail the entire PnR transaction and return a failure response to the client. The default value for this configuration is 5000 milliseconds. Set this value to a value greater than the configured document registry transaction timeout value (or JTA timeout) and less than the HDR's JTA transaction timeout value.

Add the following configuration in the IHE XDS configuration file:

<config name="WS_CLIENT_CONFIG"> <component name="httpConnTimeout" value="3000" /> <component name="httpReadTimeout" value="5000" /> </config>

Configure Registry for Accepting Delete Document Set ITI-62 Web Service Calls

The registry update server URL has to be configured for enabling HDR to send ITI-62 Delete Document Set request web service calls to external document registries.

HDR uses this configuration to delete the ITI-41 document entries from registries if there is any failure in committing the transaction in HDR after getting the SUCCESS response from registries. To do this, HDR uses the RegistryStoredQuery ITI-18 request to get all the registry objects associated with the XDSSubmissionSet uniqueId, and then HDR constructs the ITI-62 Delete Document Set request using all the registry objects received from ITI-18 response and call the registry for deleting them using the XDS registry update URL. Here HDR receives all the registry objects (associations, external identifiers, extrinsic objects, and so on) that are associated with the corresponding XDSSubmissionSet uniqueId using the ITI-18 call. This request will be sent from HDR only when there is a failure in committing the ITI-41 document after getting the SUCCESS call from the registry.

The web service end point URL could be an http URL or secure https URL. In case of https connections to registry server, the necessary truststore and keystore files need to be generated and configured in <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/config/hdr/ihe_xdsb_config.xml under the REGISTRY_AUDIT_SERVER_SSL_CONFIG configuration name.

where, <weblogic_install_dir> is the file path where the WebLogic server has been installed. <weblogic_domain_name> represents the name of the WebLogic domain.

For information about digital certificates and using JDK's keytool to generate keystore and truststore, visit http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/keytool.html.

Configure Profile Option for ITI-62 Delete Document Set Transaction

As in synchronous XDS.b web services, HDR exposes a set of configuration APIs to configure profile options. Use the ProfileOptionService EJB session bean to configure the profile options. Before deploying and running synchronous web services, configure the External Document Registry update server endpoint. To send Delete Document Set Transaction ITI-62 request to an external Document Registry actor, HDR should be configured with the Document Registry Update endpoint's URL. This URL must be a valid web service endpoint URL implementing XDS.b UpdateDocumentSet specification.

ProfileOptionService API: createProfileOption(ProfileOption profileOptionObject), setProfileOptionValue(ProfileOptionValue profileOptionValueObject)

ProfileOption Configuration Values: ProfileOptionCode: "CTB_XDS_B_REGISTRY_UPDATE_URL" ProfileOptionValue: "http://DOCUMENT_REGISTRY_HOST:PORT/UpdateServiceXYZ" ProfileOptionLevelCode: "SITE" ProfileOptionLevelValue: null

Asynchronous IHE XDS.b Web Services

HDR provides support for the Asynchronous Web Services Exchange option of the IHE XDS.b specification, specifically for the Document Repository actor. The asynchronous XDS.b profile uses the same set of transactions specified in the XDS.b profile. However, any transaction between two XDS.b actors is now decoupled into two separate one-way transactions - one for request and another for response. Please note the difference that in the synchronous XDS.b profile, both request and response are exchanged between two XDS.b actors as part of a single transaction.

HDR implements the following Asynchronous XDS.b web services:

Asynchronous Provide and Register Document Set-b
Asynchronous Retrieve Document Set

Asynchronous Provide and Register Document Set-b

The following figure illustrates the Asynchronous Provide & Register Doc-b Web Service:

Asynchronous Retrieve Document Set

This section contains the following topics:

Configure Profile Options for Asynchronous Web Services

As in synchronous XDS.b web services, HDR exposes a set of configuration APIs, to configure profile options. Use the IHEXDSConfigService EJB session bean to configure the profile options. Before deploying and running Asynchronous web services, configure the Asynchronous External Document Registry endpoint: In order to send asynchronous Register Document Set-b request web service calls to an external Document Registry actor, HDR should be configured with the Document Registry endpoint's URL. This URL must be a valid web service endpoint URL implementing XDS.b Asynchronous Register Document Set-b specification.

API: configureRegistryAsyncURL(String registryAsyncURL)

Sample value: http://DOCUMENT_REGISTRY_HOST:PORT/ServiceXYZ

Configure WLS for Asynchronous Web Services

HDR leverages WLS JMS queues to implement Asynchronous XDS.b web services. The WL server where HDR is to be deployed must create the required JMS queues that are used by the asynchronous web services.

HDR's Asynchronous Provide and Register Document Set-b web service uses two JMS Queues:

AsyncXDS_PnRbRequestQueue: All inbound 'Asynchronous Provide and Register Document Set-b' requests are saved in this queue, before getting dequeued and processed.
AsyncXDS_PnRbResponseQueue: All outbound 'Asynchronous Provide and Register Document Set-b' responses are saved in this queue before getting dequeued and transmitted to callback endpoints of respective Document Sources.

HDR's Asynchronous Retrieve Document Set uses two JMS Queues:

AsyncXDS_RetrieveDocbRequestQueue: All inbound Asynchronous Retrieve Document Set requests are saved in this queue, before getting dequeued and processed.
AsyncXDS_RetrieveDocbResponseQueue: All outbound Asynchronous Retrieve Document Set responses are saved in this queue before getting dequeued and transmitted to callback endpoint of the client (An XDS.b Document Consumer).

Configure Message Receipt Timeout Value for Asynchronous Web Services

Edit <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/config/hdr/ihe_xdsb_config.xml and enter the timeoutValue under configuration item with name JMS_MESSAGE_TIMEOUT. This timeoutValue represents how long the JMS Message Consumer will wait to receive response message from the AsyncXDS_PnRbResponseQueue or AsyncXDS_RetrieveDocbResponseQueue destinations before the timeout expires. The timeoutValue is in milliseconds, and default value is 180000 milliseconds.

Configure HDR To Accept Web Services Invocation Over http Protocol

By default, HDR installation enables client to invoke Web services over https protocol only. In case the user wants HDR to accept Web services invocation over http protocol, then a custom JVM argument EnableHTTPForWS=true has to be included to the value of the JAVA_OPTIONS variable in <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/bin/startManagedWebLogic.sh. where, <weblogic_install_dir> is the file path where the WebLogic server has been installed. <weblogic_domain_name> represents the name of the WebLogic domain.

Configure Credential Store

The password of IHE_XDS_USER is stored in SecretStore of Oracle Wallet. IHE Service uses the IHE_XDS_USER credentials for user authentication. Edit <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/config/hdr/ihe_xdsb_config.xml and enter the absolute path to Oracle Wallet as a value for the credentialStore under configuration item with name CREDENTIAL_STORE_CONFIG.

Configure MTOM/ XOP for the ITI-43 Transaction (Retrieve Document Set)

This configuration controls how HDR returns the MTOM/XOP response for the ITI-43 transaction. Edit <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/config/hdr/ihe_xdsb_config.xml and enter the optimizeMessage value under configuration item with name MTOM_XOP_CONFIG. Set optimizeMessage value to true to permit HDR to return optimized MTOM/XOP message. Else, set optimizeMessage value to false. For more information on optimized and non-optimized MTOM/XOP messages, refer to http://www.ihe.net/uploadedFiles/Documents/ITI/IHE_ITI_TF_Vol2b.pdf.