Setting Up Web Services

You must apply the Oracle Clinical web services to a computer running Oracle Fusion Middleware, which can be the Oracle Clinical Middle-tier server, the SOA Suite server, or any other server running Oracle Fusion Middleware.

The Oracle Clinical web services are installed in OPA_HOME\webservices\X\OracleClinical.ear, where the X represents the currently installed version. For example, 11g.

For more information, see:

• Prerequisites
  
• Installing the Oracle Clinical Web Services
  
• Configuring Certificates
  

Prerequisites

Before you begin to set up the web services, you should check that you meet the following requirements:

• Have administrative access to the AIA server so that you can perform setup tasks in the SOA Home.
• Have administrative access to the Oracle Clinical or RDC web server.
• Have an X.509 and root certificate from a trusted certificate authority.

  Note:

  The steps in this chapter generate a self-validating certificate, not a trusted certificate. Oracle does not recommend that you secure your system with generated, self-signed certificates, but instead recommends that you obtain an X.509 and root certificate from a trusted certificate authority. Allow some time for the certificate to be issued.
• Have downloaded the Oracle Repository Creation Utility (RCU).
• Have downloaded OpenSSL for Windows.

Installing the Oracle Clinical Web Services

You should apply the Oracle Clinical web services to a computer running Oracle Fusion Middleware. Alternately, you can use the Oracle Clinical Middle-tier server for this purpose.

If you are upgrading to Oracle Clinical Release 5.2 web service usage, you must set up the web service client with the oracle/wss11_x509_token_with_message_protection_client_policy assertion to sign messages before the Study, Subject, and Visit Synch for the Siebel Clinical - Oracle Clinical PIP can call the Oracle Clinical web services. To enforce this policy for the client, follow the instructions in step 5 of Client Side Configuration

To install the Oracle Clinical web services, follow the high-levels steps below, in the given order.

1. Run the Oracle Repository Creation Utility (RCU) to create a metadata repository. Oracle Web Service Manager (OWSM) uses this repository to secure policies.

   RCU requires access to a database and you can use any compatible database.

2. Install the Oracle Web Service Manager (OWSM) on the Oracle RDC Middle-tier web server.

   See Installing the Oracle Web Service Manager (OWSM) for more information on how to complete this step.

3. Install the Oracle Clinical web services in the WebLogic server.

   See Installing the Oracle Clinical Web Services in the Oracle WebLogic Server for more information on how to complete this step.

4. Configure the certificates between the Oracle Clinical web service server and the AIA server.

   See Configuring Certificates for more information on how to complete this step.

   You need to request a certificate from a Certificate Authority (CA) vendor such as Thawte, Entrust, or Verisign. Once you have obtained the X.509 certificate, install it for use by the Oracle Clinical web server. Allow some time for the certificate to be issued.

5. Create the keystore and credential store on the Oracle Clinical web service server.
6. Add the WSDL definition information to the AIA system.

   See Client Side Configuration for more information on how to complete this step.

For more information, see:

• Installing the Oracle Web Service Manager (OWSM)
  
• Installing the Oracle Clinical Web Services in the Oracle WebLogic Server
  

Installing the Oracle Web Service Manager (OWSM)

The Oracle Web Service Manager (OWSM) applies server policies on the Oracle Clinical web service application. OWSM requires access to a database and you can use any compatible database.

You can install OWSM from the Quick Start installation program that installs the Oracle Enterprise Manager.

Caution:

The Oracle Repository Creation Utility (RCU) must be run prior to installing the Oracle Web Service Manager (OWSM).

To install OWSM:

1. Click on the Windows Start button and select All Programs.
2. Find and click on the Oracle WebLogic folder and select QuickStart.
   The WebLogic Platform Quick Start screen opens.
3. Click on Getting started with WebLogic Server 10.3.6.
   The Fusion Middleware Configuration Wizard opens to the Welcome page.
4. Select Create a new WebLogic domain and click Next.
   The Select Domain Source page opens.

   Note:

   If you already have a domain, you can extend the existing domain to install OWSM. To do so, for this step select the Extend an existing WebLogic domain checkbox and proceed to the next step.
5. Select Generate a domain configured automatically to support the following products and then select the checkboxes for Oracle Enterprise Manager - 11.1.1.0 [oracle_common] and Oracle WSM Policy Manager - 11.1.1.0 [oracle_common]. Oracle JRF - 11.1.1.0 [oracle_common] is automatically selected, leave it as is.

   Click Next.

   The Specify Domain Name and Location page opens.
6. Replace the default values with your domain name and location.

   Note:

   Save the entered domain name and location. This information is required in later steps.

   Click Next.

   The Configure Administrator User Name and Password page opens.
7. Enter your username and password, and then click Next.
   The Configure Server Start Mode and JDK page opens.
8. Select Production Mode in the left pane and Available JDKs in the right pane.

   Click Next.

   The Configure JDBC Component Schema page opens.
9. Fill in the fields with your information. This information should match the information used to run the RCU.

   The Driver information is set by default. Leave it at the default setting.

   Click Next.

   The JDBC Component Schema page opens. This page confirms that the information on the previous page is correct to use when installing the OWSM Policy Manager.
10. Click Next.
    The Select Optional Configuration page opens.
11. If you are installing in a WebLogic server that was installed for Oracle Clinical RDC, select the Administration Server and Managed Servers, Clusters and Machines checkboxes to change the default port numbers for the servers.

    Otherwise, click Next on the following screens without making any changes until you reach the Configuration Summary page, then continue with step 15.

12. Click Next.
    The Configure the Administration Server page opens.
13. Change the default listen port and then click Next.

    Note:

    The port you use must be different from the ones used for any other running servers.
    The Configure Managed Servers page opens.
14. Change the default listen port and then click Next.
    The Configuration Summary page opens.
15. Verify the details of the domain and components that you selected for installation, and then click Create to continue the installation.
    The Creating Domain page opens.
16. When progress reaches 100%, click Done to complete the installation and exit the wizard.

You can access the admin server console for the new domain at http://middletier_name:admin_server_port/console.

Installing the Oracle Clinical Web Services in the Oracle WebLogic Server

To install the Oracle Clinical Wrb Services in the Oracle WebLogic Server:

1. Log into the Oracle WebLogic Server console as a WebLogic user.
2. In the Domain Configurations panel, under the Deployed Resources section, select Deployments.

   The system displays all of the applications currently deployed on this server.

3. Click Install to deploy all of the options.
4. Click the Upload your file(s) option to upload the .ear file from your local machine.
5. Click Next.
6. Click Next and then choose the option Install this deployment as an application.
7. Click Next.
8. Choose from the available targets, such as soa_server1, and click Next.
9. Set OracleClinical-WS as the name of the application. Then click Next.

   Note:

   Do not change any of the other default values.

   The system displays your configuration details. You can edit the details by navigating back through the screens.

10. Click Finish.

To confirm that the web services deployed successfully:

1. Go to the list of Deployments and verify that the OC Webservices project is in the Active state.

   If it is in the New state, start the managed server from Environment, then Servers.

2. Click on the application and select the Testing tab. There should be three Test Points available to check the three web services: InvestigatorService, Site Service, and StudySite Service.

   Before you can test these web services, you must create a data source. See below for instructions on how to do this. You can create the data source in the current session.

3. Once the data source is created, select the link Test Client under Test Point for each web service to check that it is working properly.

To create a data source:

1. In the same console screen from the previous section, under Domain Structure, click Services, and then click Data Sources.

   The system displays all existing data sources.

2. Click New.

   Three options are available.

3. Select the Generic Data Source option.
4. In the Create Screen, name the datasource OracleClinicalCoreDS.
5. In the JNDI Name column, enter jdbc/OracleClinicalCoreDS.

   Note:

   Do not change any other settings from their default values.
6. Click Next.
7. Click Next.
8. Click Next and enter the database name, host name, and port of your Oracle Clinical database. You must enter rxa_ws as the username and the password for the rxa_ws user.
9. Click Next.
10. Select your SOA server as the target. For example, select soa_server1.
11. Click Finish. The data source is created and deployed on the target server.
12. Verify that the data source was successfully created in the list of data sources. Click on the data source and go to the Monitoring tab.
13. Select the Testing tab and test the data source.

Configuring Certificates

Configuring the certificates between the Oracle Clinical web service server and the AIA SOA server involves populating keystores and generating public certificates that you copy between the servers.

In the WebLogic server, a keystore is used to store credentials, such as certificates. The Credential Store Framework (CSF) provides a way to store, retrieve, and delete credentials for a web service and other applications. OWSM uses the CSF to manage the credentials in a secure form, for example, by retrieving alias names and passwords for keys in the Java keystore or usernames and passwords used for authentication.

Keytool is a utility that Oracle delivers with Java. The system uses this utility to manage the import and export of certificates from the keystores. You must have access to the Keytool utility to continue with the installation. If it isn't already, you need to add it to your environment variable path, the JDK path up to bin.

When using WSS11 policies, configuration is required on both sides, as follows:

• On the service side, where the Oracle Clinical web service is deployed, set up private keys and define them as the encryption key alias in the OWSM Keystore Configuration screen.
• On the client side, the AIA server, you need to configure the client-side trust by obtaining the server's certificate.

Obtaining a CA Certificate

You need to request a certificate from a Certificate Authority (CA) vendor such as Thawte, Entrust, or Verisign, then include it in the keystore.

To get the certificate, you must create a certificate request and submit it to the CA. The CA authenticates the certificate requestor and creates a digital certificate based on the request. Allow some time for the certificate to be issued.

Note:

If you do not have an X.509 certificate, you can generate a certificate using the Keytool utility, but Oracle does not recommend that you secure your system with generated self-signed certificates.

Sample Configuration

The Server Side Configuration and Client Side Configuration sections that follow serve as an example of how to set up and implement AIA to call an Oracle Clinical web service in a different domain. The process also involves securing the AIA client and web service using a policy that is created based on the oracle/wss11_x509_token_with_message_protection_service_policy, and changing its configuration to only sign the header and not the encryption.

For more information, see:

• Server Side Configuration
  
• Client Side Configuration
  

Server Side Configuration

In this sample configuration we are using the OpenSSL certificate management tool to demonstrate the process.

1. Download OpenSSL for Windows from https://code.google.com/p/openssl-for-windows/downloads/list
2. Install the application in C:\OpenSSL and place the executables in the C:\OpenSSL\bin folder instead of the Windows system folder.

   You can install the application in another folder, but the above path is recommended.

3. Once the installation is complete, add the new bin folder to your system path as follows:
   1. Right-click on My Computer and select Properties.
   2. Go to the Advanced tab and click Environment Variables.
   3. Under System Variables, select Path and click Edit.
   4. If the Path value does not end with a semicolon, add one.
   5. Add a path to the bin folder. For example, C:\OpenSSL\bin.
   6. Click OK three times to finish.
4. Generate the certificate authority as shown in the steps below, which are performed in the Command Prompt. In the example, the alias webservice is used.
   1. Create directories in which to store the certificates using the below commands:

      mkdir client
      mkdir server
      mkdir ca
      

   2. Generate an RSA private key for the certificate, called ca.key.

      Openssl genrsa -des3 -out ca/ca.key 4096
      

      When the message Enter pass phrase for ca/ca.key: is displayed, type in a password. For example, welcome.

   3. Create the master certificate, called ca.cer, using the key generated before.

      openssl req -new -x509 -days 365 -key ca/ca.key -out ca/ca.cer -subj "/CN=HSGBUSupportCA/OU=HSGBU/O=Oracle/L=Burlington/ST=Massachusetts/C=US" -config OpenSSLpath\openssl.cnf
      

      OpenSSLpath stands for the path for the directory where OpenSSL was installed at step 2.

      When the message Enter pass phrase for ca/ca.key: is displayed, type in the password used for the above step.

5. Generate server certificates by following the steps below:
   1. Use the keytool command -genkeypair to generate the key pair for the alias servercer. The key pair is used for SSL configuration on the server.

      keytool -genkey -keyalg RSA -alias servercer -keypass welcome -keystore server/server_keystore.jks -storepass welcome -dname "CN=<servername>,OU=HSGBU,O=Oracle,L=Burlington,ST=Massachusetts,C=US" -validity 365
      

   2. Generate the certificate request for servercer using the -certreq command. This generates a certificate request for the servercer alias and a certificate signing request (CSR) named server/servercer.csr.

      keytool -certreq -alias servercer -sigalg "SHA1withRSA" -file server/servercer.csr -storetype jks -keystore server/server_keystore.jks -storepass welcome
      

   3. Sign the CSR file using the CA created above. Run the command:

      keytool -list -v -alias servercer -keystore server/server_keystore.jks -storepass welcome
      

      The response for the above command also returns the certificate serial number, which is needed for the following step. You can find it in the line starting with Serial Number.

   4. Submit the CSR file to a CA, which authenticates the request and returns a certificate or certificate chain.

      openssl x509 -req -days 365 -in server/servercer.csr -CA ca/ca.cer -CAkey ca/ca.key -set_serial 0x<serial number from above step> -out server/servercerIssuedByCA.cer
      

   5. Import the CA root certificate, which authenticates the CA's public key.

      keytool -importcert -alias 'oracleHsgbuca' -trustcacerts -file ca/ca.cer -keystore server/server_keystore.jks -storepass welcome
      keytool -list -keystore server/server_keystore.jks -storepass welcome
      

   6. Replace the self-signed certificate with the trusted CA certificate issued by the CA in response to the certificate request using the -importcert keytool command. This replaces the self-signed certificate servercer with the trusted CA certificate named server/servercerIssuedByCA.cer.

      keytool -importcert -trustcacerts -alias servercer -file server/servercerIssuedByCA.cer -keystore server/server_keystore.jks -storepass welcome
      keytool -list -keystore server/server_keystore.jks -storepass welcome
      

      The HSGBUSupportCA (trustedCertEntry) and the servercer (PrivateKeyEntry) certificates are stored in the server/server_keystore.jks. The server/server_keystore.jks file is used to configure web services for the WebLogic server.

6. Generate certificates for the client, the AIA server, by following these steps:
   1. Use the keytool command -genkeypair to generate the key pair for the alias webservice, which is later used for encryption.

      keytool -genkey -keyalg RSA -alias webservice -keypass welcome -keystore client/client_keystore.jks -storepass welcome -dname "CN=webservice" -validity 365
      

   2. Use the -importcert keytool command to import the trusted CA root certificate, named ca/ca.cer here, using the alias ocalehsgbuca, into the client-keystore.jks keystore.

      keytool -importcert -alias "oracleHsgbuca" -trustcacerts -file ca/ca.cer -keystore client/client_keystore.jks -storepass welcome
      

   3. Generate the certificate request using the -certreq keytool command. The below command generates a certificate request for the webservice alias and a CSR named client/webservice.csr.

      keytool -certreq -alias webservice -sigalg "SHA1withRSA" -file client/webservice.csr -storetype jks -keystore client/client_keystore.jks -storepass welcome
      

   4. Get the serial number for the certificate, which is needed in the following step.

      keytool -list -v -alias webservice -keystore client/client_keystore.jks -storepass welcome
      

   5. Submit the CSR file to a CA for authentication. The CA returns a certificate or certificate chain.

      openssl x509 -req -days 365 -in client/webservice.csr -CA ca/ca.cer -CAkey ca/ca.key -set_serial 0x<serial number from above step> -out client/webserviceIssuedByCA.cer
      

   6. Use the -importcert keytool command to replace the self-signed certificate with the trusted CA certificate issued by the CA in response to the certificate request. The following command replaces the self-signed certificate for the alias webservice with the trusted CA certificate named client/webserviceIssuedByCA.cer.

      keytool -importcert -trustcacerts -alias webservice -file client/webserviceIssuedByCA.cer -keystore client/client_keystore.jks -storepass welcome
      

   7. List the content of the keystore client/client_keystore.jks.

      keytool -list -keystore client/client_keystore.jks -storepass welcome
      

   8. Import the public server certificate for the encryption.

      keytool -importcert -trustcacerts -alias servercer -file server/servercerIssuedByCA.cer -keystore client/client_keystore.jks -storepass welcome
      

   9. List the content of the keystore client/client_keystore.jks and server_keystore.jks.

      Keytool -list -keystore client/client_keystore.jks -storepass welcome
      Keytool -list -keystore server_keystore.jks -storepass welcome
      

7. Configure the security provider on Enterprise Manager for the OCWebService domain by following the below steps.
   1. Log into the Fusion Middleware control for the domain at http\\servername:port)\em.
   2. Right-click on the domain you are configuring and select Security, then Security Provider Configuration.
   3. In the Keystore section, click Configure.
   4. Fill in the fields with the below information:
      • Keystore Type: JKS
      • Keystore Path: C:/x509/server/server_keystore.jks (server keystore location used for step 4)
      • Keystore Password: welcome (used in the commands to create the keystore)
      • Signature Key Alias: servercer (created using the keytool command)
      • Alias Password: welcome (created using the keytool command)
      • Encryption Key Alias: servercer (created using the keytool command)
      • Alias Password: welcome (created using the keytool command)
   5. Click OK.
8. Configure the credentials for the web service server as shown below.
   1. Right-click on the domain you are configuring and select Security, then Credentials.
   2. Make sure there is an entry under the Credentials tree with the name oracle.owsm.security.

      The content of these entries must be based on the information used in the previous step. The same passwords apply.

   3. Add a new realm from the administration console at http\\servername:port)\console.

      To do so, under Domain, click on Security Realms and select the default realm. Select the Users and Groups tab and click New. Provide the required information, making sure that the name is the same one that was used to generate the certificate on the client side. Click OK.

   4. Once the configuration is complete:
      • Restart all the affected managed servers for the new configurations to take effect.
      • Restart the admin server.

Client Side Configuration

Configuring the client side can be performed by uploading a new WSDL file to the SOA server. In the AIA layer, the Enterprise Business Service (EBS) calls the Oracle Clinical provider using routing rules defined in the EBS. Web Services Description Language (WSDL) requires web services to communicate between Oracle Clinical and the EBS. For details on how to configure EBS and web services, see the Oracle Study, Subject, and Visit Synchronization Integration Pack for Siebel Clinical and Oracle Clinical Implementation Guide, available at http://docs.oracle.com/cd/E51618_01/doc.111/e36156/toc.htm.

After you complete the Oracle Clinical web service installation process, verify that the security policy is configured for web services and save the WSDL files in order to upload them to the client. The Oracle Clinical Web Services Description Language (WSDL) files can be located by accessing the deployed Oracle Clinical web service through any web browser. You can display the WSDL of the web service in your browser to ensure that it has deployed correctly using the following URL:

http://host:port/contextPath/serviceUri?WSDL

Where:

• host refers to the computer on which the Oracle Clinical web service, deployed on the WebLogic server is running.
• port refers to the port number on which the WebLogic Server is listening.
• contextPath refers to the context root of the web service.
• serviceUri refers to the value of the serviceUri attribute, such as InvestigatorService, SiteService, or StudySiteService.

Note:

For an Oracle Clinical web service associated with an oracle/wss11_x509_token_with_message_protection_service_policy policy file, published as an attachment to the WSDL by default, the static WSDL file in the web service archive file (JAR or WAR) is different from the dynamic WSDL of the deployed web service because only the latter includes specific <SecurityToken> elements.

To configure the client side:

1. Navigate to $AIA_HOME/AIAMetaData/AIAComponents/ApplicationObjectLibrary/OracleClinical/V1/wsdls.
2. Take the backup of InvestigatorService.wsdl, SiteService.wsdl, and StudySiteService.wsdl.
3. Copy the updated WSDL file.
4. Upload the new WSDL file to the MDS following the instructions below.
   1. Navigate to the $AIA_INSTANCE/config directory.
   2. Create a backup of UpdateMetaDataDp.xml.
   3. Edit UpdateMetaDataDp.xml file as follows:

      <?xml version="1.0" standalone="yes"?>
      <DeploymentPlan component="Metadata" version="3.0">
        <Configurations>
          <UpdateMetadata wlserver="fp" >
            <fileset dir="${AIA_HOME}/AIAMetaData">
              <include name="AIAComponents/ApplicationObjectLibrary/OracleClinical/V1/wsdls/*.wsdl"/>
            </fileset>
          </UpdateMetadata>
        </Configurations>
      </DeploymentPlan>
      

   4. Navigate to the $AIA_INSTANCE/bin directory.
   5. Execute one of the following commands:
      For Windows, execute aiaenv.bat.

      ant -f %AIA_HOME%\Infrastructure\Install\config\UpdateMetaData.xml
      

      For Linux, source aiaenv.sh.

      ant -f $AIA_HOME/Infrastructure/Install/config/UpdateMetaData.xml
      

   6. Once the build completes, restart the SOA server.

   Note:

   The SOA server should be restarted every time a new WSDL file is uploaded.
5. Attach the oracle/wss11_x509_token_with_message_protection_client_policy policy to the client side.
   1. Log into the SOA control panel for the domain at http\\SOAservername:port\em.
   2. Under SOA, right-click on UpdateClinicalStudyOCHealthSciencesProvABCSImpl and select Service/References Properties, then select the name of the web service.
   3. Go to the Policies tab and then click Attach/Detach.
      A new window opens.
   4. In the Available Policies pane, find and select the client policy, then click Attach.
   5. Repeat the above steps as necessary to attach the policy to other services.
6. Configure the security provider on Enterprise Manager for the client.
   1. Log into the SOA control for the domain.
   2. Right-click on the domain you want to configure and select Security, then Security Provider Configuration.
   3. In the Keystore section, click Configure.
   4. Provide the information generated in the first section of the document.
      • Keystore Type: JKS
      • Keystore Path: /slot/ems6679/oracle/Keystore/x509_latest/client/client_keystore.jks (path for the client keystore, used for step 6 of Server Side Configuration)
      • Keystore Password: welcome (used in the commands to create the keystore)
      • Signature Key Alias: webservice (created using the keytool command)
      • Alias Password: welcome (created using the keytool command)
      • Encryption Key Alias: webservice (created using the keytool command)
      • Alias Password: welcome (created using the keytool command)
   5. Click OK.
   6. On the client machine, navigate to the directory /slot/ems6679/oracle/Middleware/user_projects/domains/soa_domain/bin/.
   7. Open the startWebLogic.sh file.
   8. Change the line SAVE_JAVA_OPTIONS ="${JAVA_OPTIONS}" into SAVE_JAVA_OPTIONS="${JAVA_OPTIONS} -Djavax.net.ssl.trustStore=full path to keystore".
7. Configure the credentials for the client server.
   1. Right-click on the domain you are configuring and select Security, then Credentials.
   2. Check that there is an entry called oracle.owsm.security under the Credentials tree.
      If the entry doesn't exist, redo step 6.
8. Add a new realm on the client server.
   1. Go to the administration console at http\\servername:port\console.
   2. Select Security Realms and then click on the default realm.
   3. Select the Users and Groups tab and then click on New in the Users pane.
      The Create a New User page opens.
   4. Set up the details for the new user.

      Note:

      Provide the same alias as used to generate the client side certificate. In this case, webservice.
   5. Click OK.