Oracle® Health Sciences Information Manager Policy Engine Installation and Configuration Guide Release 1.2 E22759-01 |
|
|
PDF · Mobi · ePub |
This chapter provides the instructions to install and configure the Policy Engine VM template. Also, it provides the instructions on how to configure CONNECT software on OHIG Adapter/Gateway VMs to make use of openSSO-based Policy Engine.
This chapter includes the following sections:
"Installing OHIG Adapter and Gateway VM Certificates on Policy Engine VM"
"Configuring CONNECT Software on OHIG Adapter VM for OpenSSO Policy Engine"
"Configuring CONNECT Software on OHIG Gateway VM for OpenSSO Policy Engine"
The OHIM Policy Engine template uses the "Paravirtualized" virtualization method. The template is distributed as a compressed tar file (*.tgz
). The compressed tar file contains two binary files and a text file. The binary files are the disk images taken from a fully configured and functional VM. The text file is a VM configuration file.
The contents of the compressed tar file is listed below:
Disk Image with Oracle Software
/appliance.img
Disk Image with Operating System
/System.img
VM Configuration File
/vm.cfg
The VM consists of the following pre-installed software:
Oracle Enterprise Linux 5 (as in System.img
)
http://www.oracle.com/technetwork/topics/linux/whatsnew/index.html
OHIM specific software (as in appliance.img
)
Apache Ant 1.8.1
Install directory: /home/common/ant
Java Development Kit 1.6.0_X
Install directory: /home/common/java/latest
(symbolic link to JDK 1.6.0_X)
For hiauser only:
OHIM Ant Configuration Utility
Install directory: /home/hiauser/config
Netbeans 6.7.1
Install directory: /home/hiauser/netbeans-6.7.1
Glassfish Enterprise Server 2.1.1
Install directory: /home/hiauser/SUNWappserver
Admin user
- Username: admin
- Password: adminadmin
Admin Console
- http://
<VM_IP or VM_HOST_NAME >
:4848
OpenSSO 8.0 Update 2
Install directory: /home/hiauser/opensso
OpenSSO Admin user
- Username: amAdmin
- Password: adminadmin
OpenSSO Admin Console
- http://
<VM_IP or VM_HOST_NAME >
:8080/opensso
VM Memory Settings:
2 GB (2048 MB) of RAM
Note:
The RAM memory setting can be changed after installation in VM Manager.16 GB of Disk Space
Linux Users:
Root user
Username: root
Linux Group: root
Password: ovsroot
OHIM specific user
Username: hiauser
Linux Group: hiauser
Password: hiapass
Tip:
For security purposes, it is recommended that you change the default passwords after installation.To import the OHIM Policy Engine VM template:
Copy the OHIM Policy Engine VM template .tgz
file to the /OVS/seed_pool
directory of your Oracle VM Server machine.
Uncompress the .tgz
file:
> tar -zxvf
<FILENAME>
.tgz
This step creates a directory with the name of the template.
Example:
> cd /OVS/seed_pool > tar -zxvf /OVS/seed_pool/OVM_HIMV12_X86_POLICYENGINE_PVM.tgz
Creates the directory:
/OVS/seed_pool/OVM_HIMV12_X86_POLICYENGINE_PVM
Note:
If you are using 64 bits, you would useOVM_HIMV12_X86_64_POLICYENGINE_PVM
.Log in to the Oracle VM Manager
Note:
The default location for the Oracle VM Manager log in screen ishttp://<VM_MANAGER_HOST_NAME>:8888/OVS
.From the Oracle VM Manager console:
Click the Resources tab. The Virtual Machine Templates screen is displayed.
Click the Import button. The Source screen is displayed.
Choose the Select from Server Pool (Discover and register) radio button.
Click Next. The General Information screen is displayed.
Enter or select the following general information:
- The server pool on which the virtual machine will be located.
Server Pool Name: <SERVER_POOL_NAME
>
- The operating system of the Virtual Machine Operating System:
Oracle Enterprise Linux 5
- The Oracle VM template to be imported.
Virtual Machine Template Name: <VM_TEMPLATE_NAME>
- The username used to log in to the Virtual Machine.
Virtual Machine System Username: root
- The password used to log in to the Virtual Machine.
Virtual Machine System Password: ovsroot
Click Next. The Confirm Information screen is displayed.
Click Confirm. The Virtual Machine Template screen is displayed with a message to confirm the VM template has been imported.
Click the Resources tab to see the list of available VM templates.
To make the Virtual Machine template available for use, select the Virtual Machine template and click Approve, moving the VM template from the "Pending" state to the "Active" state.
The VM template is imported and ready for use in Oracle VM Manager.
To create the OHIM Policy Engine VM from the VM template:
Create a new VM using the Policy Engine VM template just installed by following the instructions in the VM Manager 2.2 User's Guide (refer to Section 6.3.1, "Creating Virtual Machine from a Template").
To power on the Virtual Machine select the Virtual Machines tab, select the Virtual Machine Name, and click Power On.
In the VM Manager Console ensure that the Policy Engine VM is now in the running state (Status=Running).
This section provides instructions for configuring the OHIM Policy Engine VM.
To VNC into a VM:
Note:
To enable the VNC Port link in the VM Manager follow the instructions in "Installing OVM Console" athttp://oss.oracle.com/oraclevm/manager/RPMS/README-console
.Expand the details of the VM by clicking the + on Show. You can VNC into the box from the VM Manager by clicking on the VNC Port link under the VM details, or you can use a VNC client to log in using the address:
<VM_SERVER_HOST_NAME>:<VM_VNC_PORT>
To configure the VM to use static IP:
Note:
The VM is configured by default to use DHCP to assign an IP address.If you are using DHCP addressing you can skip the following steps.
To configure the VM to use static IP, log in as the root user (default password: ovsroot
) and set the IP using the following steps:
Select System, Administration, and then Network.
Choose Devices, click Edit, select the Statically Set IP Address radio button, and then enter the following values:
- Address: <VM_IP>
- Subnet mask: <SUBNET_MASK>
- Default Gateway address: <DEFAULT_GATEWAY_ADDRESS>
- From the Ethernet Device panel, select the Hardware Device tab, and then click the Probe button that corresponds to "Bind to MAC address".
This sets the correct MAC address for this machine.
Note:
Make certain that you a record the MAC address.Click OK.
Choose File and then click Save.
Click the DNS tab and then enter the following values:
- Hostname: <VM_HOST_NAME>
- Primary DNS: <PRIMARY_DNS>
- Secondary DNS: <SECONDARY_DNS>
- Tertiary DNS: <TERTIARY_DNS>
- DNS search path: <VM_NAME_SUFFIX>
Choose Next and then click Save.
Choose the Hosts tab, click New, and then enter the following values:
- Address: <VM_IP>
- Hostname: <VM_HOST_NAME>
- Aliases: <VM_NAME_PREFIX>
hostname
Click OK.
Choose File and then click Save.
Restart Network Services from a terminal window.
> service network restart
Check the output for <VM_IP>
.
> ifconfig
Check the output for <VM_HOST_NAME>
.
> hostname
Check the success of:
> ping
<VM_IP>
Check the success of:
> ping
<VM_HOST_NAME>
Note:
(Optional) In order to preserve the static IP address when the OVM is powered off, follow below steps, but only if the linevif = ['mac=AA:BB:CC:DD:AA:CC,bridge=xenbr0']
does not match what you have in the vm.cfg
file (see below).
Power off the Virtual Machine by selecting the Virtual Machines tab in the VM Manager, choose the Virtual Machine Name, and click Power Off.
Edit the vm.cfg
file that is found on the VM Server under /OVS/seed_pool/
<template_name> by replacing the line:
vif = ['bridge=xenbr0,type=netfront']
with the MAC corresponding to that virtual machine:
vif = ['mac=AA:BB:CC:DD:AA:CC,bridge=xenbr0']
where AA:BB:CC:DD:AA:CC
is the MAC corresponding to the created OVM noted above.
To configure the OHIM Policy Engine VM:
Log in to the VM as hiauser
(default password: hiapass
).
Start the application server using the following commands
> cd /home/hiauser/SUNWappserver/bin
> asadmin start-domain domain1
Navigate to the directory: /home/hiauser/config
.
Run the script import-policyengine-svc-cfg.sh
to import the service configuration data to the opensso configuration datastore, and to update the bootstrap file which is used by opensso to retrieve configuration data to bootstrap itself.
Note:
You can runifconfig
on your VM to determine the ip address.Example:
>sh import-policyengine-svc-cfg.sh – The VM_IP address of your Policy Engine Virtual Machine Enter policy_engine_host_ip: <POLICY_ENGINE_VM_IP> - The VM_IP address of your Gateway Virtual Machine Enter gateway_host_ip: <GATEWAY_VM_IP> - For the commnad, "Directory Service contains existing data. Do you want to delete it? [y|N]" Provide y as the option, and hit Enter key. You will see the following message on the console Please wait while we import the service configuration... Upon successful completion of the service configuration import, you will see the message Service Configuration was imported.
Stop the application server using the following commands:
> cd /home/hiauser/SUNWappserver/bin
> asadmin stop-domain domain1
Navigate to the directory: /home/hiauser/config
.
Note:
Before proceeding to the next step, make sure that the hostname does not return a fully configured name for the Virtual Machine. Please check the following commands before proceeding:> hostname
(should return just the hostname)
> hostname -f
(should return a fully configured hostname)
> hostname -d
(should return the domain)
The following step produces a self-signed certificate for use during initial installation and testing. Use appropriate signed certificates for production use.
Run the script create-and-import-selfsigned-certs.sh
to install the self-signed certificate. It does the following things.
Creates the keystore for the private internal key
Exports the certificate that will authenticate the internal key
Imports the trusted certificates into the truststore
Provides these certificates to appserver
to use for authentication purposes
>sh create-and-import-selfsigned-certs.sh
Log in to the Adapter VM as hiauser
(password: hiapass
)
Stop the application server using the following commands:
> cd /home/hiauser/SUNWappserver/bin
> asadmin stop-domain domain1
Navigate to the directory /home/hiauser/config/scripts
using the following command:
> cd /home/hiauser/config/scripts
Run the script create-and-import-selfsigned-certs.sh
to install the self-signed certificate. It does the following things:
Creates the keystore for the private internal key
Exports the certificate that will authenticate the internal key
Imports the trusted certificates into the truststore
Provides these certificates to appserver
to use for authentication purposes
> sh create-and-import-selfsigned-certs.sh
Install the certificates from the other components that will communicate with the Adapter (Gateway, OHMPI, Record Locator, Policy Engine, and so on). Copy the certificate of the component VM <VM_HOSTNAME.cer>
to the /home/hiauser/SUNWappserver/domains/domain1/config
folder. Navigate to and run the scripts /home/hiauser/config/scripts/import-others-cert.sh
. When prompted by the scripts, enter the VM hostname (it should match with the cert file you copied to the config
folder without ".cer" suffix).
>bash import-others-cert.sh
Log in to the Gateway VM as hiauser
(password: hiapass
)
Stop the application server using the following commands:
> cd /home/hiauser/SUNWappserver/bin
> asadmin stop-domain domain1
Navigate to the directory /home/hiauser/config/scripts
using the following command:
> cd /home/hiauser/config/scripts
Run the script create-and-import-selfsigned-certs.sh
to install the self-signed certificate. It does the following things:
Creates the keystore for the private internal key
Exports the certificate that will authenticate the internal key
Imports the trusted certificates into the truststore
Provides these certificates to appserver
to use for authentication purposes
> sh create-and-import-selfsigned-certs.sh
Install the Adapter VM certificate. Copy the certificate of Adapter VM <ADAPTER_ VM_HOSTNAME.cer>
to the /home/hiauser/SUNWappserver/domains/domain1/config
folder. Navigate to and run the scripts /home/hiauser/config/scripts/import-others-cert.sh
. When prompted by the scripts, enter the Adapter VM hostname (it should match with the cert file you copied to the config folder without ".cer" suffix).
>bash import-others-cert.sh
Log in to the Policy Engine VM as hiauser
(password: hiapass
)
Ensure that the application server is not running. If it is running, stop it using the following commands:
> cd /home/hiauser/SUNWappserver/bin
> asadmin stop-domain domain1
Navigate to the directory /home/hiauser/config
using the following command:
> cd /home/hiauser/config
Note:
Before proceeding to the next step, copy the certificate of the Adapter VM<ADAPTER_VM_HOSTNAME.cer>
to the /home/hiauser/SUNWappserver/domains/domain1/config
folder.To install the Adapter VM certificate, run the script import-others-cert.sh
:
> sh import-others-cert.sh
The hostname of the Adapter VM whose certificate is being imported into the appserver's truststore
Enter the hostname of the machine whose certificate is being imported into appserver's truststore:
<ADAPTER_VM_HOSTNAME>
Note:
Before proceeding to the next step, copy the certificate of the Gateway VM<GATEWAY_VM_HOSTNAME.cer>
to the /home/hiauser/SUNWappserver/domains/domain1/config
folder.To install the Gateway VM certificate, run the script import-others-cert.sh
:
> sh import-others-cert.sh
The hostname of the Gateway VM whose certificate is being imported into the appserver's truststore
Enter the hostname of the machine whose certificate is being imported into the appserver's truststore:
<GATEWAY_VM_HOSTNAME>
Start the application server using the following commands:
> cd /home/hiauser/SUNWappserver/bin
> asadmin start-domain domain1
Log in to the Adapter VM as hiauser
(password: hiapass
).
Get the /home/hiauser/config/ada_gw_pe_config.zip
file from the Policy Engine VM using hiauser
(password: hiapass
).
Ensure that the application server is not running. If it is running, stop it using the following commands:
> cd /home/hiauser/SUNWappserver/bin
> asadmin stop-domain domain1
Navigate to the directory /home/hiauser/config
using the following command:
> cd /home/hiauser/config
Unzip the ada_gw_pe_config.zip
file to the config
folder
> unzip
<FILE_PATH>
/ada_gw_pe_config.zip
Note:
FILE_PATH
should be replaced with the absolute path to which the ada_gw_pe_config.zip
file was downloaded.Run the script config-adapter-policyengine.sh
to configure the CONNECT Adapter which enables it to interact with openSSO-based Policy Engine.
Note:
You can runifconfig
on your Policy Engine VM to determine the ip address.> sh config-adapter-policyengine.sh
The VM_IP
address of your Policy Engine Virtual Machine
Enter policy_engine_host_ip:
<POLICY_ENGINE_VM_IP>
The HTTP Port of the GlassFish Application Server which is installed on Policy Engine Virtual Machine
Enter policy_engine_http_port:
<GF_HTTP_PORT>
Start the application server using the following commands:
> cd /home/hiauser/SUNWappserver/bin
> asadmin start-domain domain1
Log in to the Gateway VM as hiauser
(password: hiapass
).
Get the /home/hiauser/config/ada_gw_pe_config.zip
file from the Policy Engine VM using hiauser
(password: hiapass
).
Ensure that the application server is not running. If it is running, stop it using the following commands:
> cd /home/hiauser/SUNWappserver/bin
> asadmin stop-domain domain1
Navigate to the directory /home/hiauser/config
using the following command:
> cd /home/hiauser/config
Unzip the ada_gw_pe_config.zip
file to the config
folder
> unzip
<FILE_PATH>
/ada_gw_pe_config.zip
Note:
FILE_PATH
should be replaced with the absolute path to which the ada_gw_pe_config.zip
file was downloaded.Run the script config-gateway-policyengine.sh
to configure the CONNECT Gateway which enables it to interact with openSSO-based Policy Engine.
Note:
You can runifconfig
on your Policy Engine VM to determine the ip address.> sh config-gateway-policyengine.sh
The VM_IP
address of your Policy Engine Virtual Machine
Enter policy_engine_host_ip:
<POLICY_ENGINE_VM_IP>
The HTTP Port of the GlassFish Application Server which is installed on Policy Engine Virtual Machine
Enter policy_engine_http_port:
<GF_HTTP_PORT>
Start the application server using the following commands:
> cd /home/hiauser/SUNWappserver/bin
> asadmin start-domain domain1
This section assumes the following have already been setup, and applications/services on the OHIG Adapter and Gateway are ready to test from the SoapUI project.
OpenSSO Instance has been installed and configured on Policy Engine VM
GlassFish Application Server on Policy Engine VM is up and running
OHIG Gateway and Adapter are configured to interact with Policy Engine VM for authentication/authorization services
GlassFish Application Servers on OHIG Gateway VM, and OHIG Adapter VM are up and running
A test machine with SoapUI application installed on it
If the GlassFish Application Server is not running on any of the VMs, start it by using the following commands:
> cd /home/hiauser/SUNWappserver/bin
> asadmin start-domain domain1
Launch the SoapUI application on the test machine.
Copy the /home/hiauser/config/files/opensso/soapui/AdapterPEPWS-soapui-project.xml
file from Policy Engine VM to a directory on the test machine.
From the File menu, click the Import Project sub-menu. This will display the "Select soapUI Project Files dialog" window
Enter <FILEPATH>
/AdapterPEPWS-soapui-project.xml
as the filename.
Note:
FILE_PATH
represents the absolute path to which the AdapterPEPWS-soapui-project.xml
file has been copied.Click the Open button. The AdapterPEPWS-soapui-project.xml
file is imported into your soapUI application.
Open the test by selecting AdapterPEPWS -> AdapterPIPBindingSoap -> StorePtConsent -> StorePatientConsent1.
Note:
While testing using the default CONNECT Adapter provided Master Patient Index (mpi.xml
), use the Patient ID: D123401
.To ensure that the patient consent is not changed during SoapUI testing, make the following changes to the endpoint URL. Perform the following for this step (StorePatientConsent1) and step 11 (StorePatientConsent2).
Note:
If you use a database-based repository, you do not need to change the endpoint URL for either step.To update internalConnectionInfo.xml
from the OHIG Adapter and Gateway servers, replace:
<service><name>adapterxdsbdocrepository</name><description>Adapter Document Retrieve</description><endpointURL>http://<hig_adapter_IP>:8080/CONNECTAdapterDocReposSoap12/AdapterDocRepository2Soap12Service</endpointURL></service>
with
<service><name>adapterxdsbdocrepository</name><description>Adapter Document Retrieve</description><endpointURL>http://<hig_adapter_IP>:8080/CONNECTAdapter/DocumentRepository_Service</endpointURL></service>
After performing this update, restart the OHIG Adapter and Gateway GlassFish servers.
In the StorePatientConsent1 window, using the edit current option, set the endpoint URL for the request by using the correct IP address of OHIG Adapter VM.
Run the test by clicking the green arrow near the top left corner of the StorePatientConsent1 window.
Run the test AdapterPEPWS -> AdapterPIPBindingSoap -> RetrievePtConsentByPtId -> RetrievePatientConsent to verify that the document was stored successfully.
Update the patient preference by modifying the StorePatientConsent2 (AdapterPEPWS -> AdapterPIPBindingSoap -> StorePtConsent -> StorePatientConsent2) SOAP request where you use "false" for the "optIn" element, and include the policyOID element, which can be found in the response of the RetrievePatientConsent request.
The modified request looks like:
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:gov:hhs:fha:nhinc:common:nhinccommonadapter"> <soapenv:Header/> <soapenv:Body> <urn:StorePtConsentRequest> <urn:patientPreferences> <urn:patientId>0000000000</urn:patientId> <urn:assigningAuthority>1.1</urn:assigningAuthority> <urn:optIn>false</urn:optIn> <urn:fineGrainedPolicyMetadata> <urn:policyOID>20.200.20.31</urn:policyOID> </urn:fineGrainedPolicyMetadata> </urn:patientPreferences> </urn:StorePtConsentRequest> </soapenv:Body> </soapenv:Envelope>
Execute the modified StorePatientConsent2 request. This will update the patient's preference.
Open the test AdapterPEPWS -> AdapterPEPBindingSoap -> CheckPolicy -> DocumentQueryIn. Use "false" for the "optIn" element.
Note:
While testing using the default CONNECT Adapter provided Master Patient Index (mpi.xml
), for the resource-id
attribute, use the string D123401
as the attribute value.In the DocumentQueryIn window, using the edit current option, edit the endpoint URL for the request by using the IP address of OHIG Gateway VM.
Run the test by clicking the green arrow near the top left corner of the DocumentQueryIn window. You will observe "Deny" in the response.
Run the SOAP request AdapterPEPWS -> AdapterPIPBindingSoap -> StorePtConsent -> StorePatientConsent2. This time use "true" for the "optIn" element. This will again update the patient's preference.
Rerun the test AdapterPEPWS -> AdapterPEPBindingSoap -> CheckPolicy -> DocumentQueryIn. This time you will observe "Permit" in the response.
To validate the CONNECT software on the OHIG Gateway and Adapter VMs after they are configured to use openSSO Policy Engine:
Ensure that the GlassFish Application Server is up and running on Policy Engine, Gateway, and Adapter VMs using the following commands:
> cd /home/hiauser/SUNWappserver/bin
> asadmin start-domain domain1
Validate the configuration using the sample universal client distributed with the Gateway:
Launch the application by navigating to the following URL:
http://
<GATEWAY_VM_IP>
:8080/UniversalClientGUI/
The authentication page is displayed asking for user account details.
Enter a valid username and password (user1
/password
)
Click the Login button.
- If the account details are correct, the Universal Client GUI Main page has the patient search tab enabled, while the rest of the tabs are disabled.
- If the provided account details are incorrect, you will be prompted to enter the correct account details again.
Search for a patient with the last name: “Younger”.
If the installation is correct, this returns a page with the PatientId for the patient.
Click the PatientId hyperlink for additional details on the patient.
The Document tab is now enabled and you can search for patient documents by date range. Search for date range 08/01/2000 to 08/01/2010
Click on the document URL to retrieve the document.
To avoid a java.security.cert.CertificateException
you need to ensure that your OHIM hostnames are not fully qualified.
To Make the Hostname Not Fully Qualified
Set the OHIM and OHIG hostnames to be not fully qualified.
Add aliases for all hosts.
Regenerate and re-import the certificates.
Restart all the servers.
Test that you do not have a Java security certificate exception.