CONNECT OpenSSO Installation and Configuration Manual

Transcription

1 CONNECT OpenSSO Installation and Configuration Manual Version 4.0 CONNECT Release March 2010

2 REVISION HISTORY REVISION DATE DESCRIPTION July 2009 Initial Release September 2009 Updated to reflect CONNECT Release January 2010 Updated to reflect CONNECT Release March 2010 Updated to reflect CONNECT Release 2.4 CONNECT_OpenSSO_Manual i Release 2.4

3 TABLE OF CONTENTS 1.0 INTRODUCTION PURPOSE SCOPE DOCUMENT DESCRIPTION REFERENCED DOCUMENTS CONNECT INSTALLATION CHECKLIST INSTALLATION AND CONFIGURATION CHECKLIST TEST DEPLOYMENT FOOTPRINT HARDWARE REQUIREMENTS SOFTWARE REQUIREMENTS INSTALLATION AND CONFIGURATION OBTAIN MEDIA/ SOFTWARE INSTALL/DEPLOY OPENSSO INTO GLASSFISH CONFIGURE OPENSSO CREATE A TEST USER INSTALL OPENSSO COMMAND LINE TOOLS TEST THE OPENSSO INSTALLATION TEST THE OPENSSO INSTALLATION WITH THE OPENSSO API SAMPLES INSTALL GENERIC POLICY DECISION POINT REQUEST HANDLER IN TO OPENSSO TEST THE GENERIC POLICY DECISION POINT REQUEST HANDLER CONFIGURE THE CONNECT GATEWAY MACHINE ACRONYMS APPENDIX A... A-1 A.1 CREATE A CONSUMER PREFERENCES DOCUMENT... A-2 A.2 ALTERNATE CONSUMER PREFERENCES DOCUMENT CREATION A-6 LIST OF FIGURES FIGURE 3.0-1: INSTALLATION WORKFLOW... 2 FIGURE A.1-1: LOG INTO THE CPP GUI...A-2 FIGURE A.1-2: SELECT DEFINE PATIENT AUTHORIZATION ACTIVITY...A-3 FIGURE A.1-3: ENTER SEARCH CRITERIA...A-4 FIGURE A.1-4: UPDATE PATIENT AUTHORIZATION...A-5 FIGURE A.1-5: DEFINE PATIENT AUTHORIZATION...A-6 FIGURE A.2-1: CREATE CPP DOCUMENT...A-7 FIGURE A.2-2: VERIFY CPP DOCUMENT...A-8 CONNECT_OpenSSO_Manual ii Release 2.4

4 1.0 INTRODUCTION 1.1 Purpose This document is the installation and configuration manual for installing the OpenSSO single sign-on application which may be used by the National Health Information Network (NHIN) CONNECT software as one of the options to help orchestrate and enforce security and consent policies for an NHIN participant. The CONNECT software uses the OpenSSO application as a policy engine to make security enforcement decisions for all incoming and outgoing electronic request or response messages for patient data. 1.2 Scope The procedures in this document are applicable to all CONNECT users who wish to use the OpenSSO policy engine. 1.3 Document Description This document includes the following sections. Section 1.0 Introduction Section 2.0 Referenced Documents Section 3.0 CONNECT Installation Checklist Section 4.0 Test Deployment Footprint Section 5.0 Installation and Configuration Section 6.0 Acronyms 2.0 REFERENCED DOCUMENTS The following documents are referenced in this document: CONNECT System Installation and Configuration Full Binary Manuals ws%29 CONNECT System Installation and Configuration Source Code Manuals 8Windows%29 8Linux%29 CONNECT_OpenSSO_Manual 1 Release 2.4

5 3.0 CONNECT INSTALLATION CHECKLIST The following is an overall NHINC workflow/checklist that guides the reader through the steps required to install the CONNECT software and join the NHIN. Most of the steps in this flow are contained in the CONNECT installation and configuration documents available on the CONNECT website and are only repeated here for reference. This document will focus on the Perform Installation workflow item as it pertains to the installation of the OpenSSO application. OID Request Process Submit a request for an OID for each gateway being configured. Assess Hardware Requirements Ensure to secure hardware that meets the hardware and software requirements provided for the appropriate platform. Determine Installation Method Obtain Media/ Software Perform Installation Request and Install SSL Configure the Gateway Select an installation method: Manual, install from a zip or install a VM Gateway image. As applicable, download the Gateway VM software, Gateway Software zip or tar file Follow the installation instructions for zip or tar as appropriate. Instructions on how to request and install the SSL the CONNECT gateway. Configure the specific gateway properties depending on the Agency s needs and platform selected Step to be executed by Agency Step executed by Agency & CONNECT Team Step executed by Agency & CSC Figure 3.0-1: Installation Workflow CONNECT_OpenSSO_Manual 2 Release 2.4

6 3.1 Installation and Configuration Checklist The following checklist provides a quick reference of the steps involved with installing the OpenSSO application with the NHINC software. Item Procedural Step 1 Download the CONNECT-OpenSSO zip file from the CONNECT web site. See section Install/Deploy the OpenSSO application war file into the Glassfish application server. See section Configure OpenSSO. See section Setup/Create a test user for later testing. See section Install the OpenSSO Command Line Tools. See section Test the OpenSSO installation. See section Test the OpenSSO API examples. See section Install the generic Policy Decision Point Request Handler. See section Test the generic Policy Decision Point Request Hander. See section Configure the CONNECT Gateway machine. See section TEST DEPLOYMENT FOOTPRINT 4.1 Hardware Requirements This section describes the recommended minimum hardware component infrastructure including processor performance, disk space, and RAM for the NHINC application server platform. This is provisional information subject to change based on continued development. CONNECT_OpenSSO_Manual 3 Release 2.4

7 Item Processor RAM Hard Disk Size Hard Disk Speed Network Interface Version Minimum dual 2GHz CPU Minimum of 4 GB Application Dependent on the deployment configuration. For sizing purposes, assume 100K per CCD record, 1K per audit log record. Minimum of 7200 RPM and RPM preferred. 100MB Ethernet acceptable; 1GB Ethernet desirable 4.2 Software Requirements This section describes any dependent software products. Item Operating System Java-JRE/JDK Application Server Communication Stack Network Protocol Relational Database Recommended Dev Environment (Optional) Recommended Test Tools (Optional) Description Use of the same operating system as needed by the Glassfish v2.1and GlassfishESB v2.1 applications is required. For additional information, refer to the specific installation instructions for Windows or Solaris. Java SDK 1.6 Update 16 (32-bit version) Glassfish v2.1 Metro v1.5 TCP/IP Any ANSI SQL92 compliant relational database. For example, MySQL 5.1, Oracle, and DB2 NetBeans IDE build soapui v3.0.1, Junit CONNECT_OpenSSO_Manual 4 Release 2.4

8 5.0 INSTALLATION AND CONFIGURATION There are two phases to the OpenSSO installation and configuration. The first phase will install and test the initial OpenSSO application by deploying the opensso.war file into the Glassfish web application server. The second phase will install and test a generic Policy Decision Point component for use with the opensso application. As introduced at the beginning of this document, OpenSSO is used by the CONNECT software as a policy engine. The policy engine is used to make policy decisions for all incoming and outgoing messages to the CONNECT software. The Policy Enforcement Point (PEP) is responsible for orchestrating the policy engine calls to the Policy Information Point (PIP) to retrieve information such as the patient opt-in status to build into access (XACML) request messages. These messages are provided to the Policy Decision Point (PDP) whereupon a decision of Permit or Deny is made. The PEP capability is provided by the CONNECT software component, AdapterPEPEJB which depends upon the classes within another CONNECT software component called the AdapterPEPLib. A Proxy Component is also defined and provided by the AdapterPEPProxy and the AdapterPEPProxyImpl software components, allowing a switch to be in place for a Java only solution or a Web Service implementation. The PDP is handled by OpenSSO components and is dependent upon a customized RequestHandler being placed within the OpenSSO deployment (see section 5.7). 5.1 Obtain Media/ Software Download the CONNECT OpenSSO component packages from the CONNECT Site. Step Action Input Expected Result 1 Download the NHIN_Connect_OpenSSO_2.4.x.xxx.zip file from the NHIN CONNECT release site. 2 Unzip the above file to the hard drive of your machine. NOTE: These instructions will assume that the OpenSSO components will have been unzipped to the root directory of the windows c:\ drive. The file is now located on your computer. The OpenSSO components will be extracted onto your hard drive. CONNECT_OpenSSO_Manual 5 Release 2.4

9 3 Downlaod NHIN_Connect_OpenSSO_Adapter PEPWS_Test.zip. 4 Unzip the above file to the hard drive of your machine. NOTE: These instructions will assume that the OpenSSO Adapter PEPWS zip file will have been unzipped to the following directory: The file is now located on your computer. The OpenSSO components will be extracted onto your hard drive. C:\NHINC\ThirdPartyTools\OpenSS O 5.2 Install/Deploy OpenSSO into Glassfish The following steps outline the procedures to deploy the OpenSSO application war file into the same Glassfish application server as used by the CONNECT software. Step Action Input Expected Result 1 Start the Glassfish application server. The Glassfish application server should start without error. 2 Open your preferred web browser (e.g., Firefox) and navigate to the Glassfish administration web page. The Glassfish administration web page is displayed. 3 Login to the Glassfish administration application. Unless previously altered, the user name and password as used during the CONNECT software installation process will be: User Name: admin Password: adminadmin Login credentials will be accepted and the Glassfish administration web page will be displayed. CONNECT_OpenSSO_Manual 6 Release 2.4

10 4 Under the Deployment" section of the web page, select Deploy Web Application (.war). The Deploy Enterprise Applications/Modul es web page will be displayed. 5 In the Location field, select the "Packaged file to be uploaded to the server" radio button and fill in the file name as: c:\nhinc\thirdpartytools\opensso\opensso.war A File Upload dialog box will appear allowing you to navigate to the opensso.war file. CONNECT_OpenSSO_Manual 7 Release 2.4

11 6 Leave the rest of the fields in their default values and click on the OK button. The OpenSSO application will be deployed. 5.3 Configure OpenSSO The following steps outline the procedures to configure the OpenSSO application. Step Action Input Expected Result 1 With the Glassfish application server already running and the OpenSSO application deployed, navigate to the following location using your preferred web browser: The OpenSSO administration web page will be displayed. NOTE: Internet Explorer web browser users were known to experience difficulties when configuring CONNECT_OpenSSO_Manual 8 Release 2.4

12 OpenSSO. You may choose to use the Firefox web browser. 2 Login to OpenSSO using the following credentials: NOTE: Login is not required the first time OpenSSO is run. This user account is created as part of the configuration process. User Name: amadmin Password: adminadmin A successful OpenSSO login. 3 Select the "Create Default Configuration" link. An OpenSSO Configurator window will be displayed. CONNECT_OpenSSO_Manual 9 Release 2.4

13 4 Enter and confirm the password for the amagent and UrlAccessAgent users: amagent Password: adminadmin UrlAccessAgent Password: password The amagent and UrlAccessAgent passwords will be submitted, and the OpenSSO default configuration process will be started. Click on the Create Configuration button. 5 Click on the Proceed to Login link to continue. The configuration will be complete, and you will be CONNECT_OpenSSO_Manual 10 Release 2.4

14 taken to the OpenSSO login web page. 5.4 Create a Test User A test user will need to be created at this point in order to successfully execute the tests outlined later in this document. The following steps describe how this process is accomplished. Step Action Input Expected Result 1 Open a web browser and login to the OpenSSO administration console ( ). User Name: amadmin Password: adminadmin A successful login will result in the display of the OpenSSO administration web page. CONNECT_OpenSSO_Manual 11 Release 2.4

15 2 Select the Access Control tab. The Access Control web page will be displayed. 3 Click on the / (Top level Realm) link. The web page displaying the general properties of the / (Top Level Realm) will be displayed. CONNECT_OpenSSO_Manual 12 Release 2.4

16 4 Click on the Subjects tab. The Subjects property tab will be displayed. 5 Click on the New button. The New User web page will be displayed. CONNECT_OpenSSO_Manual 13 Release 2.4

17 6 Enter the following information on this page: ID: user1 First Name: One Last Name: User Full Name: User, One Password: password Password (confirm): password User Status: Active The user1 test user will be created and displayed in the list of users on the Subjects tab. CONNECT_OpenSSO_Manual 14 Release 2.4

18 Click on the OK button. 7 Click on the Back to Access Control button. The Access Control web page will be displayed. CONNECT_OpenSSO_Manual 15 Release 2.4

19 8 Click on the LOG OUT button. The OpenSSO logout page will be displayed. Click on the OK button if presented with another dialog box regarding the need to close other associated windows. 5.5 Install OpenSSO Command Line Tools The following steps outline the procedures to install the OpenSSO command line tools. Step Action Input Expected Result 1 With the Glassfish application server already running and the OpenSSO application deployed, open a command window and navigate to the A command line interface window should be CONNECT_OpenSSO_Manual 16 Release 2.4

20 following location on your hard drive: C:\NHINC\ThirdPartyTools\OpenSSO\ssoAdminT ools displayed in the directory listed on the left. 2 Execute the OpenSSO command line tools setup program by entering the command, setup and pressing the enter key. 3 Enter the path to the config files of the OpenSSO server by substituting <user-home> with the folder name associated with your user on your machine. For a username of bob, the following directories would be used on various operating systems: Windows XP: C:\Documents and Settings\bob Vista: C:\Users\bob The setup command utility will start The path to your machine s OpenSSO configuration files will be set. <user-home>\opensso 4 Enter the path to the OpenSSO debug directory on your machine by substituting <you-user> with the folder name associated with your user on your machine. The directory will be created for you if it does not already exist. The path to the OpenSSO debug directory on your machine will be set. <user-home>\opensso\opensso\debug 5 Enter the path to the OpenSSO log directory on your machine by substituting <you-user> with the folder name associated with your user on your machine. <user-home>\opensso\opensso\log The path to the OpenSSO log directory on your machine will be set. The setup command will complete and you will see a similar output on your command window CONNECT_OpenSSO_Manual 17 Release 2.4

21 as the following: The scripts are properly set up under directory: C:\NHINC\ThirdPa rtytools\ssoadmin Tools\opensso Debug directory is c:\documents and Settings\Admin\op ensso\opensso\de bug. Log directory is c:\documents and Settings\Admin\op ensso\opensso\log. The version of this tools.zip is: Express Build 7(2009-April-10 08:05) The version of your server instance is: Express Build 7(2009-April-10 08:05) 6 Add the following to your system path environment variable: C:\NHINC\ThirdPartyTools\OpenSSO\ssoAdminT ools\opensso\bin NOTE: Remember to include the separator character between path entries. The system path environment variable will be updated to include the directory listed to the left. CONNECT_OpenSSO_Manual 18 Release 2.4

22 5.6 Test the OpenSSO Installation The following steps outline the procedures to test your OpenSSO installation. Step Action Input Expected Result 1 Start the Glassfish application server if it is not already running. The Glassfish web service application should be running. 2 Login to the Glassfish administration application User Name: admin Password: adminadmin The Glassfish administration web page should be displayed. 3 Click on the Deploy Web Application (.war) button. The Deploy Enterprise Applications/Modul es web page will be displayed. CONNECT_OpenSSO_Manual 19 Release 2.4

23 4 Ensure the Packaged file to be uploaded to the server radio button is selected, then click on Browse to find the following file: C:\NHINC\ThirdPartyTools\OpenSSO\ IdSvcsClient.war The IdSvcsClient.war file will be deployed in the Glassfish web server. CONNECT_OpenSSO_Manual 20 Release 2.4

24 Then click the OK button. 5 Navigate to the following using your preferred web browser: 6 Fill in the username and password using the following values: Username: user1 Password: password A web page will be displayed allowing you to enter a username and password. The user1 name and password will have been entered into the IdSvcsClient web page. CONNECT_OpenSSO_Manual 21 Release 2.4

25 7 Test the OpenSSO web service authentication method by clicking on the WS button A web page displaying the following text similar to the following: "Successful Authentication using Web Services (SOAP/WSDL)" With a corresponding result token. 8 Click on the web browser s back button The web page prompting for a username and password should be displayed as shown in step 6. 9 Enter the user name and password again and click the "REST" button. You should see a similar "Successful Authentication using REST" message with an associated token. 5.7 Test the OpenSSO Installation with the OpenSSO API Samples The following steps outline the procedures to test the OpenSSO installation using the OpenSSO API samples. Step Action Input Expected Result 1 Start the Glassfish application server if it is not already running. The Glassfish web service application should be running. CONNECT_OpenSSO_Manual 22 Release 2.4

26 2 Open the following file with your preferred text editor: c:\nhinc\thirdpartytools\ OpenSSOXACMLExample\resources\AMConfig.p roperties. 3 Search for the line that contains the following text: "com.iplanet.services.debug.directory" And ensure that the debug directory is pointed to the correct name of your user directory on your machine (i.e., replace the <user-home> text in the following example): The AMConfig.properties file will be opened in your preferred text editor. The property setting listed on the left should have a value that corresponds to the value entered in step 4 in section 5.5. <user-home>/opensso/opensso/debug 4 Save the file. The AMConfig.properties file will be updated and saved on your hard drive. 5 Make sure the following directory exists and is empty: C:\NHINC\ThirdPartyTools\ OpenSSOXACMLExample\classes 6 Open a new command window and change directories to: The directory on the left exists and is empty. The new command window will be in the directory listed to the left. C:\NHINC\ThirdPartyTools\ OpenSSOXACMLExample 7 Enter the following command from that directory to compile the examples (the compiled classes will be placed into the classes sub-directory referred to in step 5): The OpenSSO API example classes will be compiled. scripts\compile-samples 8 Login Sample Test Open a new command window, change to the The login example program will begin CONNECT_OpenSSO_Manual 23 Release 2.4

27 C:\NHINC\ThirdPartyTools\ OpenSSOXACMLExample directory and enter the following command to test the login example: execution. scripts\login 9 Press the return key when prompted for a Realm (i.e., just leave the value blank forcing the program to use the default value). 10 When prompted, enter the following text at the Login module name (e.g. DataStore or LDAP): prompt The default realm value will be used. The DataStore value will be used as the module name. DataStore 11 Enter the following at the Login locale (e.g. en_us or fr_fr): prompt: The English US locale value will be used in this test. en_us 12 Enter user1 at the User Name: prompt. The user1 test user will be used for this test. 13 Enter password at the Password: prompt. The user1 s password value will be used for this test. 14 Verify that the text values, Verification of a successful login test. Login succeeded." and "Logged Out!!" are displayed in the command window. 15 CommandLineSSO Sample From a new command line window, change to the C:\NHINC\ThirdPartyTools\ OpenSSOXACMLExample directory and enter the command: The CommandLineSSO program will begin execution and the following text will be displayed in the command window: Scripts\CommandLineSSO CONNECT_OpenSSO_Manual 24 Release 2.4

28 Organization: / DataStore: Obtained login context User Name: 16 Enter user1 and password when prompted. The user1 test user will be used for this test. 17 Verify the following text is displayed in the command line window: A successful test completion. Successful authentication " with some other lines of information printed. 18 CommandLineIdRepo Sample From a new command line window, change to the C:\NHINC\ThirdPartyTools\ OpenSSOXACMLExample directory and enter the following command: The commandlineidrepo program will begin. scripts\commandlineidrepo 19 Enter the following values at the appropriate prompts: The appropriate values will be entered for this test. Userid [amadmin]: amadmin Userid amadmin's password [openssoxxx]: adminadmin Realm [/]: enter). (leave this field blank - just hit 20 Verify that the command line displays the following text: A successful test. "==>Authentication SUCCESSFUL for user amadmin" Enter option 7 to exit. CONNECT_OpenSSO_Manual 25 Release 2.4

29 21 CommandLineLogging Sample From a new command line window, change to the C:\NHINC\ThirdPartyTools\ OpenSSOXACMLExample directory and enter the following command: The CommandLineLogging program will begin. scripts\ CommandLineLogging 22 Enter the following values at the appropriate prompts: The appropriate values will be entered for this test. Subject Userid [user1]: (leave this field blank - just hit enter) Subject Userid user1's password [user1password]: password Log file [TestLog]: (leave this field blank - just hit enter) Log message [Test Log Record]: (leave this field blank - just hit enter) LoggedBy Userid [amadmin]: (leave this field blank - just hit enter) LoggedBy Userid's password [amadminpswd]: adminadmin Realm [/]: (leave this field blank - just hit enter) 23 Verify that the command line displays the following text: "==>Authentication SUCCESSFUL for user user1" followed by "==>Authentication SUCCESSFUL for user amdadmin", followed by "LogSample: Logging Successful!!! 24 Policy Evaluation Sample Create a policy by using the OpenSSO admin A successful test. You should also see a new log file in your log file directory called TestLog with log entries in it. (Log file directory would be: C:\Documents and Settings\<youruser>\opensso\opensso\lo g.) The OpenSSO login page will be displayed. CONNECT_OpenSSO_Manual 26 Release 2.4

30 console at: 25 Login to the OpenSSO admin console. User: amadmin Password: adminadmin The OpenSSO administration web page will be displayed. 26 Click on the "Access Control" tab. The Access Control web page will be displayed. 27 Click on the / (Top level Realm) link. The web page displaying the general properties of the / (Top Level Realm) will be displayed. CONNECT_OpenSSO_Manual 27 Release 2.4

31 28 Click on the "Policies" tab. The Policies properties web page will be displayed. 29 Click on the New Policy button The New Policy web page will be displayed. CONNECT_OpenSSO_Manual 28 Release 2.4

32 30 Enter the following information: Name: PolicyTest Description: Policy Test The new policy name and description fields will be populated. 31 Click on the New button under the Rules section. The new rules wizard will begin. CONNECT_OpenSSO_Manual 29 Release 2.4

33 32 Click on "URL Policy Agent (with resource name)" radio button and then click "Next". The new rules wizard Step 2 web page will be displayed. 33 Enter the following information and then click on the Finish button: The values specified on the left should be entered CONNECT_OpenSSO_Manual 30 Release 2.4

34 Name: Banner URL Rule Resource Name: Check "GET" and "ALLOW" Check "POST" and "ALLOW" action values. on the form, and the New Policy web page will be redisplayed. 34 Click on the New button under the Subjects section. Step 1 of the New Subject wizard web page will be displayed. CONNECT_OpenSSO_Manual 31 Release 2.4

35 35 Select "OpenSSO identify Subject" radio button and then click on the "Next" button. The New Subjects Step 2 web page will be displayed. CONNECT_OpenSSO_Manual 32 Release 2.4

36 36 Enter Policy Test Users in the Name field. The new subject rule will be named. 37 Click on the drop-down filter button to highlight the User value, and then click on the Search button. 38 Select the amadmin and user1 users, and then click on the Add button. A list of available users will be displayed under the Available: section. The amadmin and user1 users will be added as subjects. CONNECT_OpenSSO_Manual 33 Release 2.4

37 39 Click on the Finish button. The New Policy web page will be redisplayed. 40 Click the OK button to save this new policy The new policy will be saved and the Policies web page will be displayed with the new policy listed. 41 Open a new command line window, change directories to the C:\NHINC\ThirdPartyTools\OpenSSOXACMLExa mple and enter the following command: scripts\run-policy-evaluation-sample As there are no prompts to enter information, the following should be displayed in the command window: Using properties file:policyevaluationsampl e sample properties: user.password:adminadmi n service.name:iplanetamw CONNECT_OpenSSO_Manual 34 Release 2.4

38 ebagentservice user.name:amadmin resource.name: sample.com:80/banner.ht ml action.name:get : Entering getssotoken():username =amadmin,password=adm inadmin TokenID:AQIC5wM2LY4Sf cw+syhesbnciv0irgf8p1t SQACMDE=# returning getssotoken() from Entering getpolicydecision():resour cename= e.com:80/banner.html,serv icename=iplanetamweba gentservice,actionname= GET policydecision:<policydeci sion> <ResponseAttributes> </ResponseAttributes> <ActionDecision timetolive=" "> <AttributeValuePair> <Attribute name="get"/> <Value>allow</Value> </AttributeValuePair> CONNECT_OpenSSO_Manual 35 Release 2.4

39 <Advices> </Advices> </ActionDecision> </PolicyDecision> returning from getpolicydecision() 42 XACML Example NOTE: You must have already set up the policy rule in the previous example before you can run this example. The OpenSSO administration web page will be displayed. Login to the OpenSSO administrative console: URL: User Name: amadmin Password: adminadmin 43 Click on the Configuration tab. The configuration web page will be displayed. CONNECT_OpenSSO_Manual 36 Release 2.4

40 44 Click on the Global sub-tab. The OpenSSO Global Configuration web page will be displayed. 45 Click on the SAML v2 SOAP Binding link. The SAML v2 SAOP Binding global attributes web page will be displayed. CONNECT_OpenSSO_Manual 37 Release 2.4

41 46 Click on the New button. The New Request Handler web page will be displayed. 47 Enter the following information: The new SOAP binding information will be created. Key: /xacmlpdp Class: CONNECT_OpenSSO_Manual 38 Release 2.4

42 com.sun.identity.xacml.plugins.xacmlauthzdecis ionqueryhandler And click on the OK button. 48 Click on the Save button. The new SOAP Binding information will be saved. 49 Click on the "Back to Service Configuration" button. The Global configuration web page will be redisplayed. CONNECT_OpenSSO_Manual 39 Release 2.4

43 50 Open a new command line window and go to the following directory: C:\NHINC\ThirdPartyTools\ OpenSSOXACMLExample 51 Enter the command: ssoadm create-cot -t xacml-pdp-cot -u amadmin -f password.txt 52 Enter the command: ssoadm create-metadata-templ -y xacmlpdpentity -p /xacmlpdp -m xacmlpdp.xml -x xacmlpdp-x.xml -u amadmin -f password.txt 53 Enter the command: ssoadm import-entity -t xacml-pdp-cot -m xacmlpdp.xml -x xacmlpdp-x.xml -u amadmin -f A new command window will be opened in the location listed on the left. The command window will display the following: Circle of trust, xacml-pdpcot was created. The command window will display the following: Hosted entity configuration was written to xacmlpdpx.xml. Hosted entity descriptor was written to xacmlpdp.xml. The command window will display the following: Import file, xacmlpdp.xml. CONNECT_OpenSSO_Manual 40 Release 2.4

44 password.txt Import file, xacmlpdpx.xml. 54 Enter the command: ssoadm create-cot -t xacml-pep-cot -u amadmin -f password.txt 55 Enter the command: ssoadm create-metadata-templ -y xacmlpepentity -e /xacmlpep -m xacmlpep.xml -x xacmlpep-x.xml -u amadmin -f password.txt 56 Enter the command: ssoadm import-entity -t xacml-pep-cot -m xacmlpep.xml -x xacmlpep-x.xml -u amadmin -f password.txt 57 Login to the OpenSSO administrative console: URL: User Name: amadmin Password: adminadmin The command window will display the following: Circle of trust, xacml-pepcot was created. The command window will display the following: Hosted entity configuration was written to xacmlpepx.xml. Hosted entity descriptor was written to xacmlpep.xml. The command window will display the following: Import file, xacmlpep.xml. Import file, xacmlpepx.xml. The OpenSSO administration web page will be displayed. 58 Click on the Federation tab. The Federation web page will be displayed. CONNECT_OpenSSO_Manual 41 Release 2.4

45 59 Click on the "xacml-pdp-cot" link under Circle of Trust section. The Edit Circle of Trust web page will be displayed for the xacml-pdp-cot entry. CONNECT_OpenSSO_Manual 42 Release 2.4

46 60 Highlight xacmlpepentity SAMLv2" in the "Available" box and click on the "Add >" button. The xacmlpepentity SAMLv2 entry will move from the list of available items to the selected list. 61 Click on the Save button. The changes to the xacmlpdp-cot circle of trust entry will be saved. CONNECT_OpenSSO_Manual 43 Release 2.4

47 62 Click on the Back button. The Circle of Trust Configuration web page will be redisplayed. CONNECT_OpenSSO_Manual 44 Release 2.4

48 63 Click on the "xacml-pep-cot" link under Circle of Trust section. The Edit Circle of Trust web page for the xacmlpep-cot entry will be displayed. CONNECT_OpenSSO_Manual 45 Release 2.4

49 64 Highlight "xacmlpdpentity SAMLv2" in the "Available" box and click on the "Add >" button. The xacmlpepentity SAMLv2 entry will move from the list of available items to the selected list. CONNECT_OpenSSO_Manual 46 Release 2.4

50 65 Click on the Save button. The changes to the xacmlpep-cot circle of trust entry will be saved. CONNECT_OpenSSO_Manual 47 Release 2.4

51 66 Click on the Back button. The Circle of Trust Configuration web page will be redisplayed. CONNECT_OpenSSO_Manual 48 Release 2.4

52 67 Open a new command line window, change directories to the C:\NHINC\ThirdPartyTools\OpenSSOXACMLExa mple and enter the following command: scripts\run-xacml-client-sample As there are no prompts to enter information, the following should be displayed in the command window: Using properties file:xacmlclientsample sample properties: resource.servicename.dat atype: 001/XMLSchema#string resource.id: mple.com:80/banner.html action.id.datatype: ww.w3.org/2001/xmlsche ma#string CONNECT_OpenSSO_Manual 49 Release 2.4

53 resource.id.datatype: hema#string action.id:get subject.id:id=user1,ou=us er,dc=opensso,dc=java,dc =net : subject.id.datatype:urn:oa sis:names:tc:xacml:1.0:dat a-type:x500name pdp.entityid:xacmlpdpentit y resource.servicename:ipla netamwebagentservice subject.category:urn:oasis: names:tc:xacml:1.0:subjec t-category:access-subject pep.entityid:xacmlpepentit y testprocessrequest():xac mlrequest: <xacml-context:request xmlns:xacmlcontext="urn:oasis:names: tc:xacml:2.0:context :schema:os" xmlns:xsi=" org/2001/xmlschemainstance" xsi:schemalocation="urn: oasis:names:tc:xacml:2.0: context:schema:os /xacml/access_control- CONNECT_OpenSSO_Manual 50 Release 2.4

54 xacml-2.0-contextschema-os.xsd"> <Subject SubjectCategory="urn:oasi s:names:tc:xacml:1.0:subj ect-category:accesssubject"> <Attribute AttributeId="urn:oasis:nam es:tc:xacml:1.0:subject:su bject-id" DataType="urn:oasis:nam es:tc:xacml:1.0:datatype:x500name" > <AttributeValue>id=user 1,ou=user,dc=opensso, dc=java,dc=net</attribut evalue> </Attribute> </Subject> <xacmlcontext:resource> <Attribute AttributeId="ResourceId " DataType=" w3.org/2001/xmlsche ma#s tring" > <AttributeValue> ww.sample.com:80/ban ner.html</attributevalue > </Attribute> <Attribute AttributeId="urn:sun:na mes:xacml:2.0:resource: target-service" DataTyp e=" 01/XMLSchema#string" CONNECT_OpenSSO_Manual 51 Release 2.4

55 testprocessrequest():x acmlresponse: > <AttributeValue>iPlanet AMWebAgentService</ AttributeValue> </Attribute> </xacmlcontext:resource> <xacml-context:action> <Attribute AttributeId="urn:oasis:n ames:tc:xacml:1.0:actio n:action-id" DataType= " /XMLSchema#string" > <AttributeValue>GET</ AttributeValue> </Attribute> </xacml-context:action> <xacmlcontext:environment></ xacmlcontext:environment> </xacmlcontext:request> <xacmlcontext:response xmlns:xacmlcontext="urn:oasis:nam es:tc:xacml:2.0:contex t:schema:os" > <xacml-context:result ResourceId=" ample.com:80/banner.html "> CONNECT_OpenSSO_Manual 52 Release 2.4

56 <xacmlcontext:decision>permit</ xacml-context:decision> <xacml-context:status> <xacmlcontext:statuscode Value="urn:oasis:names:tc :xacml:1.0:status:ok"></xa cml -context:statuscode> <xacmlcontext:statusmessage>o k</xacmlcontext:statusmessage> <xacmlcontext:statusdetail xmlns:xacmlcontext="urn:oasis:names: tc:xacml:2.0:co ntext:schema:cd:04"><xac mlcontext:statusdetail/></xa cml-context:statusdetail> </xacml-context:status> </xacml-context:result> </xacmlcontext:response> 5.8 Install Generic Policy Decision Point Request Handler in to OpenSSO The following steps outline the procedures to install a generic Policy Decision Point (PDP) request handler into OpenSSO. A PDP request handler is required in order for the CONNECT software to correctly enforce consent policies and protect patient data. Step Action Input Expected Result 1 Copy the following file from: C:\NHINC\ThirdpartyTools\OpenSSO\XSPAXACM A copy of the XSPAXACMLAuth zdecisionqueryha CONNECT_OpenSSO_Manual 53 Release 2.4

57 LAuthzDecisionQueryHandler.class To: ndler.class file is in the Glassfish directory listed to the left. C:\Sun\AppServer\domains\domain1\applications\j 2ee-modules\opensso\WEB- INF\classes\com\sun\identity\xacml\plugins NOTE: You may need to create this directory 2 Start the Glassfish application server if it is not already running. 3 Open a web browser and login to the OpenSSO administration console. URL: User Name: amadmin Password: adminadmin The Glassfish web service application should be running. The OpenSSO administration web page will be displayed. CONNECT_OpenSSO_Manual 54 Release 2.4

58 4 Click on the Configuration tab. The Configuration web page will be displayed. 5 Click on the Global sub-tab. The Global configuration web page will be displayed. CONNECT_OpenSSO_Manual 55 Release 2.4

59 6 Click on the SAML v2 SOAP Binding link. The SAML v2 SOAP Binding Global properties web page will be displayed. CONNECT_OpenSSO_Manual 56 Release 2.4

60 7 Click on the New button. The New Request Handler web page will be displayed. 8 Enter the following information: Key: /openssopdp Class: com.sun.identity.xacml.plugins.xspaxacmlauth zdecisionqueryhandler The new request handler values will be entered. Then Click on the OK button. 9 Click on the Save button. The new request handler information will be saved. CONNECT_OpenSSO_Manual 57 Release 2.4

61 10 Click on the Back to Service Configuration button. The Global configuration web page will be redisplayed. 11 Open a new command line window and change the directory to: C:\nhinc\ThirdPartyTools\OpenSSO\AdapterPDP OpenSSO\conf 12 Execute the following command: ssoadm create-cot -t opensso-pdp-cot -u amadmin -f password.txt A new command line window will be opened in the directory specified on the left. The ssoadm program will execute and the command window will display: Circle of trust, opensso-pdp-cot was created. CONNECT_OpenSSO_Manual 58 Release 2.4

62 13 Execute the following command: ssoadm create-metadata-templ -y ConnectOpenSSOPdpEntity -p /openssopdp -m openssopdp.xml -x openssopdp-x.xml -u amadmin -f password.txt The ssoadm program will execute and the command window will display: Hosted entity configuration was written to openssopdpx.xml. Hosted entity descriptor was written to openssopdp.xml. 14 Execute the following command: ssoadm import-entity -t opensso-pdp-cot -m openssopdp.xml -x openssopdp-x.xml -u amadmin -f password.txt The ssoadm program will execute and the command window will display: Import file, openssopdp.xml. Import file, openssopdpx.xml. 15 Execute the following command: ssoadm create-cot -t opensso-pep-cot -u amadmin -f password.txt The ssoadm program will execute and the command window will display: Circle of trust, opensso-pep-cot was created. 16 Execute the following command: The ssoadm CONNECT_OpenSSO_Manual 59 Release 2.4

63 ssoadm create-metadata-templ -y ConnectOpenSSOPepEntity -e /openssopep -m openssopep.xml -x openssopep-x.xml -u amadmin -f password.txt program will execute and the command window will display: Hosted entity configuration was written to openssopepx.xml. Hosted entity descriptor was written to openssopep.xml. 17 Execute the following command: ssoadm import-entity -t opensso-pep-cot -m openssopep.xml -x openssopep-x.xml -u amadmin -f password.txt The ssoadm program will execute and the command window will display: Import file, openssopep.xml. Import file, openssopepx.xml. 18 From the OpenSSO administration web page, click on the Federation tab. The Federation configuration web page will be displayed. CONNECT_OpenSSO_Manual 60 Release 2.4

64 19 Click on the open-sso-pdp-cot link under Circle of Trust section. The Edit Circle of Trust web page will be displayed for the open-ssopdp-cot entry. CONNECT_OpenSSO_Manual 61 Release 2.4

65 20 Highlight the ConnectOpenSSOPepEntity SAMLv2 Available item. The item will be selected. CONNECT_OpenSSO_Manual 62 Release 2.4

66 21 Click on the Add button. The selected item will move from the list of Available items to the list of Selected items, and the profile will be saved. CONNECT_OpenSSO_Manual 63 Release 2.4

67 Then click on the Save button. 22 Click on the Back button. The Federation configuration web page will be redisplayed. CONNECT_OpenSSO_Manual 64 Release 2.4

68 23 Click on the open-sso-pep-cot link under Circle of Trust section. The Edit Circle of Trust web page will be displayed for the open-ssopep-cot entry. CONNECT_OpenSSO_Manual 65 Release 2.4

69 24 Highlight the ConnectOpenSSOPdpEntity SAMLv2 item under the Available section and click on the Add button. The selected item will be moved from the list of available items to the list of selected items and the profile will be updated and saved. CONNECT_OpenSSO_Manual 66 Release 2.4

70 Then click on the Save button. 25 Click on the Back button. The Federation configuration web page will be redisplayed. CONNECT_OpenSSO_Manual 67 Release 2.4

71 26 Logout of the OpenSSO Administrative web console and restart Glassfish. The Glassfish application server will be restarted. CONNECT_OpenSSO_Manual 68 Release 2.4

72 5.9 Test the Generic Policy Decision Point Request Handler There are several SoapUI tests provided to test the functionality of the PEP to PDP communication. These tests are provided in the NHIN_CONNECT_OPENSSO_AdapterPEPWS_2_4.zip file found on the OpenSSO web page on the CONNECT web site (see section 5.1).. In addition, you will need a consent document for a test patient stored in the document repository (see appendix section A.1 for instructions). In order to run the tests contained in this soapui project, all of the CONNECT components mentioned in the CONNECT installation manual will have to be already deployed into the Glassfish web application server. As the soapui project mentioned above contains many tests, the following steps are provided as an example to assist you with your testing should you choose to execute more than the one listed below. Step Action Input Expected Result 1 Open the soapui application. The soapui application will start. 2 From the File menu item, click on the Import Project sub-menu item. The Select soapui Project File CONNECT_OpenSSO_Manual 69 Release 2.4

73 dialog window will be displayed. 3 Enter C:\NHINC\ThirdPartyTools\OpenSSO\ AdapterPEPWS-soapui-project.xml as the filename The AdapterPEPWSsoapui-project.xml file will be imported into your soapui application. Click on the Open button. 4 From the AdapterPEPWS project node, expand the AdapterPEPBindingSoap11 and CheckPolicy nodes. The soapui application will expand the nodes similar to the screen shot shown to the left. CONNECT_OpenSSO_Manual 70 Release 2.4

74 5 Double click on the DocumentQueryIn node. The DocumentQueryIn request and response window will open inside soapui. 6 Click on the green arrow near the top, left corner of the DocumentQueryIn window as shown below (the green arrow has a red circle around it). SoapUI will execute the request and return a response. CONNECT_OpenSSO_Manual 71 Release 2.4

75 7 Verify that the response contained the text, Permit similar to the screen shot below. A successful response as indicated to the left Configure the CONNECT Gateway machine The CONNECT gateway software will come pre-configured to send the PIP and PEP to a non-enterprise message security implementation always returning a "Permit" value for patient record requests. In order to change this behavior, you will need to modify the AdapterPEPConfig.xml, AdapterPIPConfig.xml, AdapterPolicyEngineProxyConfig.xml, AdapterPolicyEngineOrchestratorProxyConfig.xml and the gateway.properties files on the CONNECT gateway machine. As referenced in other CONNECT installation CONNECT_OpenSSO_Manual 72 Release 2.4

76 manuals, the location of this file is referenced by the NHINC_PROPERTIES_DIR environment variable. Since Release 2.2, both a Java and WebService implementation have been provided for most of the services, including the Policy Engine. The following steps can be used to configure the use of the Java implementation. The Java implementation is recommended for configuration where the Policy Engine projects are co-located. The steps to modify the AdapterPEPConfig.xml file are as follows: Step Action Input Expected Result 1 Open the AdapterPEPConfig.xml file in your preferred text editor on the CONNECT gateway machine. The above file is located in the directory referenced by the NHINC_PROPERTIES_DIR environment variable as mentioned above. 2 Search for the following line: <bean id="adapterpep" class="gov.hhs.fha.nhinc.policyengine.adapte rpep.proxy.adapterpepproxynoopimpl"/> 3 Comment out this line by adding the following text at the beginning of the line <! And --> At the end of this same line. 4 UnComment the following line: <!-- <bean id="adapterpep" class="gov.hhs.fha.nhinc.policyengine.adapte rpep.proxy.adapterpepjavaproxy"/> --> by removing the <! from the beginning of the line and removing the --> from the end of the line. The AdapterPEPConfig.xml file will be opened in your preferred text editor. Your preferred text editor will find the search text listed to the left. The AdapterPEPProxyNoOpImpl entry will be disabled. The AdapterPEPJavaproxy entry will be enabled. The steps to modify the AdapterPIPConfig.xml file are as follows: This file may already be set correctly. Step Action Input Expected Result 1 Open the AdapterPIPConfig.xml file in your preferred text editor on the CONNECT gateway machine. The above file is located in the directory referenced by the NHINC_PROPERTIES_DIR environment variable as mentioned above. The AdapterPIPConfig.xml file will be opened in your preferred text editor. CONNECT_OpenSSO_Manual 73 Release 2.4

77 2 Search for the following line: Your preferred text editor will find the search text listed to the left. <bean id= adapterpip class= gov.hhs.fha.nhinc.policyengine.adapte rpip.proxy.adatperpipproxynoopimpl /> 3 Comment out this line by adding the following text at the beginning of the line <! And --> At the end of this same line. 4 UnComment the following line: <!-- <bean id= adapterpip class= gov.hhs.fha.nhinc.policyengine.adapte rpip.proxy.adapterpipjavaproxy /> --> The AdapterPIPProxyNoOpImpl entry will be disabled. The AdapterPIPJavaProxy entry will be enabled. The steps to modify the AdapterPolicyEngineOrchestratorProxyConfig.xml file are as follows: Step Action Input Expected Result 1 Open the AdapterPolicyEngineOrchestratorProxyConfi g.xml file in your preferred text editor on the CONNECT gateway machine. The above file is located in the directory referenced by the NHINC_PROPERTIES_DIR environment variable as mentioned above. 2 Search for the following line: <bean id="adapterpolicyengineorchestrator" class="gov.hhs.fha.nhinc.policyengine.adapte rpolicyengineorchestrator.proxy.adapterpolicy EngineOrchestratorPermitNoOpImpl"/> 3 Comment out this line by adding the following text at the beginning of the line: <! And --> At the end of this same line. 4 UnComment the following line: <!-- <bean id="adapterpolicyengineorchestrator" class="gov.hhs.fha.nhinc.policyengine.adapte The AdapterPolicyEngineOrchestrat orproxyconfig.xml file will be opened in your preferred text editor. Your preferred text editor will find the search text listed to the left. The AdapterPolicyEngineOrchestrat orpermitnoopimpl entry will be disabled. The AdapterPolicyEngineOrchestrat orjavaproxy entry will be enabled. CONNECT_OpenSSO_Manual 74 Release 2.4

78 rpolicyengineorchestrator.proxy.adapterpolicy EngineOrchestratorJavaProxy"/> --> by removing the <! from the beginning of the line. The steps to modify the AdapterPolicyEngineProxyConfig.xml file are as follows: Step Action Input Expected Result 1 Open the AdapterPolicyEngineProxyConfig.xml file in your preferred text editor on the CONNECT gateway machine. The above file is located in the directory referenced by the NHINC_PROPERTIES_DIR environment variable as mentioned above. 2 Search for the following line: <bean id="adapterpolicyengine" class="gov.hhs.fha.nhinc.policyengine.adapte rpolicyengine.proxy.adapterpolicyengineper mitnoopimpl"/> 3 Comment out this line by adding the following text at the beginning of the line: <! And --> At the end of this same line. 4 UnComment the following line: <!-- <bean id="adapterpolicyengine" class="gov.hhs.fha.nhinc.policyengine.adapte rpolicyengine.proxy.adapterpolicyenginejava Proxy"/> --> by removing the <! from the beginning of the line. The steps to modify the gateway.properties file are as follows: The AdapterPolicyEngineProxyConf ig.xml file will be opened in your preferred text editor. Your preferred text editor will find the search text listed to the left. The AdapterPolicyEnginePermitNoO pimpl entry will be disabled. The AdapterPolicyEngineJavaProxy entry will be enabled. Step Action Input 1 Open the gateway.properties file in your preferred text editor on the CONNECT gateway machine. The above file is located in the directory referenced by the NHINC_PROPERTIES_DIR environment Expected Result The gateway.properties file will be opened in your preferred text editor. CONNECT_OpenSSO_Manual 75 Release 2.4

79 Step Action Input variable as mentioned above. Expected Result 2 Search for the text, PdpEntityName Your editor will locate the text on the left. 3 Set the PdpEntityName property value to PdpEntityName=ConnectOpenSSO The ConnectOpenSSO PDP mechanism will be enabled. Comment out any other entries for this property in the file by placing a # at the beginning of the line. 4 Save the file. The gateway.properties file will be saved. Restart GlassFish after the configuration files have been modified. Rerun the DocumentQueryIn SoapUI test to verify that the policy engine is functioning and Permit is returned in the response. 6.0 ACRONYMS CA CAC CD CDC CMS DAT DOD DURSA DVD EHR EMR ESB FHA GB HDD HITSP IDE IHS Certificate Authority Common Access Card Compact Disk Centers for Disease Control & Prevention Centers for Medicare & Medicaid Services Digital Audio Tape Department of Defense Data Use and Reciprocal Support Agreement Digital Video Disc Electronic Health Record Electronic Medical Record Enterprise Service Bus Federal Health Architecture Gigabyte Hard Disk Drive Healthcare Information Technology Standards Panel Integrated Drive Electronics Indian Health Services CONNECT_OpenSSO_Manual 76 Release 2.4

80 IPv6 Internet Protocol Version 6 MB MPI NCI NDMS NHIE NHIN NIST OID ONC OS QA RAID RAM SCSI SDK SSA SSL TBD USB VA Megabyte Master Patient Index National Cancer Institute National Disaster Medical System NHIN Health Information Exchange Nationwide Health Information Network National Institute of Standards and Technology Object Identifier or Home Community ID Office of the National Coordinator Operating System Quality Assurance Redundant Array of Inexpensive Disks Random Access Memory Small Computer System Interface Software Development Kit Social Security Administration Secure Sockets Layer To Be Determined Universal Serial Bus Department of Veterans Affairs CONNECT_OpenSSO_Manual 77 Release 2.4