From Omar Wiki

Contents 1 Overview 1.1 Participants in Collaboration 2 Installation and Setup 2.1 CVS Instructions 3 Project Tasks 4 Project Design 4.1 Design Issues Encountered and their Workarounds 4.2 Bugs Identified 4.3 UML Diagrams 4.4 Role Definitions 5 Running the Software 5.1 Instruction To Run Demo 5.2 Typical Problems and their Solution 5.3 Access Control Policy Setup 5.4 ACP Testing

Overview

Ontario Gateway (OG) is a messaging hub that will connect the Corporate Messaging System of Government Ontario (GO-CMS) with similar systems in the other Canadian jurisdictions. The examples of these systems are SMRS (Secure Message Routing System), which is used for the Government of Canada (federal) organizations, NRS (National Routing System), Provincial and Municipal messaging systems, Community of Interest (COI) messaging systems etc.

This page describes a prototype developed for Ontario Gateway using freebXML Registry.

Participants in Collaboration

Participants in Collaboration

Participant	Telephone	Email	Instant Messager Handles	TZ	Roles
Allana Brown	289-259-9201	allana.brown@sun.com		GMT-5 (Toronto, CA)	Sun Program Manager
Farrukh Najmi	781-442-9017 x29017	farrukh.najmi@sun.com	irc.east.sun.com: farrukh_najmi irc.sfbay.sun.com: farrukh_najmi irc.freenode: farrukh_najmi AIM: farrukhnajmi Yahoo: farrukh_najmi MSN: Farrukh.Najmi@sun.com	GMT-5 (US East, Boston, MA)	Sun Architect for Service Registry
Iain McCorquodale	Phone x52821/+1 905 415 29 21 Mobile 905 520 3743	Iain.McCorquodale@Sun.COM		GMT-5	Sun Solution Architect, Sun Client Solutions
Norman Lee
Adnan K.	416-314-1221	Adnan.Kulenovic2@mgs.gov.on.ca

Installation and Setup

CVS Instructions

• Download and install NetBeans 5.5 beta
• Configure NetBeans for CVS
  At this stage, NetBeans requires some extra steps to support an ext protocol Repository directly through its built-in client. As a simpler alternative we can do the checkout and updates through the command line.

1. Install a CVS client on your workstation, if one does not already exist. If using a Windows workstation, you will need to install SSH on your machine as well.
   • The best approach is to download and install Cygwin. This will provide all the Unix facilities required for accessing the CVS repository, including ssh and cvs.
   • If you are behind a corporate firewall, you will have to tunnel to your socks server. There are three steps to this:
     • Download a file named connect.exe and save it to a directory in your PATH
     • Create a file named <cygwin-install-dir>/home/<your-user-name>/.ssh/config and add the following text:
       Host *.sourceforge.net *.apache.org *.kohsuke.org
       User <your sourceforge ID>
       ProxyCommand /<your path>/connect -S <Socks5 proxy>:1080 %h %p
       cipher 3des
       Protocol 1,2
     • Set the following environment variables:
       CVSROOT=:ext:bigmaciain@cvs.sourceforge.net:/cvsroot/ebxmlrr
       USERNAME=bigmaciain
       CVS_RSH=ssh
2. Download the JWSDP 1.6 from Sun and install it to $HOME
3. Create a CVS workspace directory called $HOME\osws. Please use this name to be consistent with the rest of the team.

• There are two options for using CVS with NetBeans. You can use the command line option to checkout and update files to the project directory under $HOME\osws or you can use the built-in tools in NetBeans to access cvs commands from the NetBeans menu. The NetBeans approach is slightly problematical with cvs.sourceforeg.net for the following reason.
  • cvs.sourceforeg.net uses ssh encryption to manage access to the repository. When using the command line you will be prompted for a password. NetBeans, cannot see this prompt, so the cvs command invoked from NetBeans will just spin indefinitely. If you want to use NetBeans's cvs facilities, it is necessary to use ssh to create a public key which is then registered with sourceforge, to get round the password requirement. The instructions on how to do that can be found here.
• Checkout CVS repository for omar project

1. To check out the source code for the omar project, open a command prompt and navigate to $HOME\osws
2. Enter the following command: cvs checkout -RAP omar
   You will be promted for your sourceforge password and then cvs will bring down all the sorce code for omar

• Checkout CVS repository for the goo project, this is the project for the POC code

1. Enter the following command: cvs checkout -RAP ebxmlrr
   You will be promted for your sourceforge password and then cvs will bring down all the sorce code for ebxmlrr

• Create omar and goo projects in NetBeans

1. Omar
   • Start NetBeans, if not already started, and select Open Project
   • Select $HOME\osws\omar
   • The Omar project is now open and the files in $HOME\osws\omar are linked to the IDE. All changes are made to this folder. Any subsequent updates through CVS will be reflected in the IDE.
2. goo
   • Start NetBeans, if not already started, and select Open Project
   • Select $HOME\osws\ebxmlrr\samples\goo
   • The goo project is now open and the files in $HOME\osws\ebxmlrr\samples\goo are linked to the IDE. All changes are made to this folder. Any subsequent updates through CVS will be reflected in the IDE.

• Build and deploy omar to tomcat container

1. This information still to be added.

Function ebxmlrr

If you are using the bash shell in Unix, you can set the environment variables by adding the following function to your .bashrc file. Remember to explicitly call the function in the file.

function ebxmlrr {

   export CVSROOT=:ext:yoursfidgoeshere@cvs.sourceforge.net:/cvsroot/ebxmlrr

   export USERNAME=yoursfidgoeshere

   export CVS_RSH=ssh

}
ebxmlrr

Project Tasks

Task Breakdown

Task	Owner	Effort Estimate	Status	Due Date	Details
Checkout latets CVS bits for omar	developers	4 hours	Done		Need to see if MGS folks have done this or not yet.
Create source tree for GOO POC under ebxmlrr module	Farrukh	4 hours	Done	10/28/2005	See CVS Instructions
Create initial UML design	Farrukh, Iain	1 day	Done		See UML Diagrams
Provide API Doc & Product Roadmap to Gov	Allana				Allana contacted Reg Gillmor Nov 10 for documentation
Bootstrap MGS team on development env / CVS etc.	Iain	1 day
Provide NDA for performance,scalability test specs/results	Norman			11/09/05	Closed Reg Gilmor agrees to use NDS signed earlier 2005
MGS Feedback re progress in open development	Norman/Adnan			Ongoing
Configure org, service configuratiuon metadata	Farrukh	2 day	Done
MessageReceiver handleMessage impl. Publishes message to registry with status Published.	Iain	2 day	Done
MessageLoader test driver program impl	Iain	1 day	Done		Now reads messages and metadata from files and stores both into registry.
Configure Validation Service for GOCMS Messages	Farrukh	2 day
Configure registry for Notification of receipt of GOCMS message.	Farrukh	2 day	Done
Implement PluginNotifier in omar.	Farrukh	1 day	Done		Now a Java PluginNotifier class such as MessageSender can be invoked by EventManager instead of SOAPNotifier which then invokes the plugin class (MessageSender).
Get Notifications delivered to MessageSender.	Farrukh	1 day	Done		A Message sent thru MessageLoader is now delivered all the way to MessageSender.
Implement MessageSender to use subscriber configuration to deliver message to all subscribers. Delivery simulated thru println. Also updates documentStatus to Delivered.	Farrukh	1 day	Done
Implement validation of BirthCertificates.	Farrukh	1 day	Done		Implemented in MessageReceiver after consulation with Adnan because registry plugin requires reliance on private registry APIs
Configure Role Based Access Control	Farrukh	4 day			See Role Definitions for info provided by Adnan
Development complete in open source env.	Farrukh			11/18/05
Registry into JES for Q&A	Farrukh			12/7/05

Project Design

Design Issues Encountered and their Workarounds

• Validation plugin requires dependency on private server classes and API. This will be fixed in omar in future. Note that it is possible to program a SOAP endpoint rather than a plugin today.
  • Workaround is to define validation rules in registry client layer (MessageReceiver)

Bugs Identified

The following bugs in registry have been identified. These will be fixed after the POC:

• Need to configure and apply access control policies at ObjectType / class level rather than instance level.
• Unregistered User should not be able to self register. This is a security hole.
• Notifications are lost if NotificationListener is not online when delivery is attempted. Need reliable delivery of Notification.
• Need to fix omar to support Calaging and Validation Service plugins that do not rely on registry server APIs and rely only on JAXR API.

UML Diagrams

Be sure to do SHIFT RELOAD in browser to get latest version of following links:

• Class Diagram
• Sequence Diagram: receive Message from CMS
• Sequence Diagram: Send Message to SMRS

Role Definitions

The following roles and associated policies need to be defined:

• ServicePublisher: Responsible for creating new service descriptions.
  • Can create and update Services and all composed and pseudo-composed types (e.g. Classification...)
  • Can create and update Associations where sourceObject=Organization targetObject=Service and User associated with Organization
  • Cannot deprecate, approve or remove Services.
  • Has no rights to do any other actions on any other types of objects.
  • Can grant and revoke his rights to other roles (The ebRR specs require that Role assignment be done by RegistryAdministrator role only so this is not directly feasible).

• ServiceResearcher: Responsible for finding services.
  • Can read services.
  • Cannot change or create registry objects.

• ServiceAdministrator: Responsible for the service approval and maintenance. ** Reads, approves, deprecates or removes any service.
  • Cannot create or update services.
  • Has no right to create or remove repository objects.
  • Can create new subtypes of class Service or its subclasses.
  • Can grant or revoke rights to other roles. The right can be qualified on a subset of registry objects (for example, services offered by the organizations located in Toronto).

• MessagePublisher: Responsible for submitting new documents to the Registry.
  • Can only create documents in the Registry. This role has no other rights.

The following existing roles need to be redefined as specified:

• RegistryGuest: Represents an unauthenticated user
  • Can perform read on any type of objects (Adnan is this correcty for POC?)
  • Cannot perform any write operations of any kind (Create, Update, Delete)
• RegistryAdministrator: Represents a superuser that administers the registry
  • Can perform all operations on all objects
  • Loads the configuration in <ebxmlrr>/samples/goo/misc/config/SubmitObjectsRequest_config.xml

Following matrix maps above policies. It makes the following simplifications (Adnan please comment if you disagree):

• If a role can create a type then it can Update it as well as classify it.
• All Registered users can read all types

Role Based Access Control Matrix

Role	Read	Create	Update	Delete	setStatus
ServicePublisher	All types	Service, Associations with sourceObject=Organization and targetObject=Service	Service, Associations with sourceObject=Organization and targetObject=Service
ServiceResearcher	All types
ServiceAdministrator	All types			Service	Service
RegistryGuest	All types
RegistryAdministrator	All types	All types	All types	All types	All types

Running the Software

Instruction To Run Demo

NOTE: Where indicated, certain steps relate to particular Use Cases in the POC

• Checkout latest code from CVS for ebxmlrr and omar modules. See CVS Instructions
• Open omar project in NetBeans
  • File => Open Project => choose the omar directory.
• Build, deploy and smoke test omar in Jakarta tomcat. See omar setup instructions
  NOTE:This POC expects Tomcat to be started and stopped as ant scripts. Start Tomcat with the command build jpda.tomcat and stop it with build stop.tomcat. Also note, that under Windows, this will open a command window and all Tomcat output will go to this window and not the Tomcat log file. Finally, omar's build.xml file defined the ports that Tomcat will use for debugging: server.debugSocket, client.debugSocket, test.debugSocket. Check tha these port numbers are not already in use and set them to a range within your free range if necessary.
• Open goo project in NetBeans
  • File => Open Project => choose the ebxmlrr/samples/goo directory.
• Do a clean build
  • In project tab select goo folder and right-click and select "Set Main Project".
  • Build => Clean and Build Main Project
• Configure server so it can use goo plugin code for MessageSender
  • cd <ebxmlrr>/samples/goo
  • cp build/dist/goo.jar <jakarata-tomcat>/webapps/omar/WEB-INF/lib #Copy goo.jar, which contains goo POC code to omar servlet so MessageSender plugin can be invoked by server.
• Load configuration data into registry server. THIS STEP EXERCISES USE CASE 5.
  • cd <omar>
  • ./build.sh run.browser & #Start omar Java UI
  • Perform user registration. Use Registry issued cert if first time. Subsequent time you can use cert in existing .p12 file.
    The POC uses a hardcoded userid/password for log-in to the Registry. When registering the test user, the userid is testuser and the password is testuserpasswd.
  • In Java UI perform Login using cert alias and keypassword
  • Import the file <goo>/misc/config/SubmitObjectsRequest_config.xml using File => Import in Java UI
• Now run the MessageLoader CLI to start the POC
  • Select Run==>Attach Debugger... to attach the debugger to Tomcat. The port number is the same port defined by server.debugSocket in omar's build.xml
  • Select Project tab in NetBeans
  • Expand to show content of the following node: goo => src => ca.on.gov.mgs.gateway
  • Double click on file MessageLoader.java to open it in editor.
  • Click somewhere in MessageLoader.java editor window to give it focus.
  • Run MessageLoader class in debugger: Run => Run File => Debug "MessageLoader.java"
    • See output produced by MessageSender in <jakarata-tomcat>/temp.MessageSender<id>.txt. This file wil be deleted when Tomcat ends, so copy the files if they are needed for comparison folllowing tests.
    • THESE LAST STEPS INITIATE A WORKFLOW THAT EXERCISES USE CASES 1 - 4 & 6

Typical Problems and their Solution

• TBD

Access Control Policy Setup

The instructions below describe how to set up the required Access Control Policy and prepare the Registry for testing Use Case 7.

Create three new users in the Registry: SuperUser will have theRegistryAdministrator role ServicePublisher has the ServicePublisher role ServiceAdministrator has the ServiceAdministrator role

The steps to do this are as follows

1. Use the Java UI to define a new user called SuperUser. Use the name SuperUser for first name, alias, key password, last name.
2. Having done this, it is necessary to change the properties file to define SuperUser as a Registry Administrator, since a User cannot give itself those priveleges. To do this, serach for the new user and browse the details. There is a unique ID generated for the user and this wil be used to define the user as a RegistryAdministrator in the properties file. Locate the following lines in <omar-home>/conf/omar.properties. Copy the unique ID and paste it into the sample uid in the un-commented line to set the value of omar.security.authorization.registryAdministrators:

     #
     # Specifies the ids of Users that have role of RegistryAdministrators
     # Add additional users by separating with '|' symbol with no intervening spaces as shown below
     #
     #omar.security.authorization.registryAdministrators=urn:freebxml:registry:predefinedusers:registryoperator|urn:freebxml:registry:predefinedusers:nikola|urn:uuid:bab82b84-7d63-44dd-b914-e72e0476c043
     omar.security.authorization.registryAdministrators=urn:freebxml:registry:predefinedusers:registryoperator|urn:uuid:2d308fbf-80a6-44f0-a1fd-ba919a6f1ff5
     #

1. Stop Tomcat and re-deploy omar with the command ant deploy, then re-start Tomcat.
2. Re-start the Java UI and log-in as SuperUser. Create a new user named ServicePublisher following the same pattern as

SuperUser. This step wil prompt you to login as the new user, so you must now log out and log back in as SuperUser.

1. Assign the role of ServicePublisher to the user ServicePublisher. If this role is not available, the Registry has not been configured. Import the file <goo_home>/misc/config/SubmitObjectsRequest_config.xml if that is the case.
2. Repeat the preceding steps above for User/Role ServiceAdministrator.
3. Set the default ACP definition for the Registry by editing <omar-home>/conf/omar.properties as follows:

     #
     # The id of default access control policy file
     #
     #omar.security.authorization.defaultACP=urn:oasis:names:tc:ebxml-regrep:acp:defaultACP
     omar.security.authorization.defaultACP=urn:ca:on:gov:mgs:acp:defaultACPForGOO

Then use the Java UI to import <goo_home>/misc/config/defaultACPForGOO.xml, stop tomcat, redeploy omar with ant deploy and restart tomcat. The registry is now configured with the necessary users and ACP rules to test Use Case 7.

Use Case 7 Tests. Detailed instructions on how to test the ACP using the REgistry Browser Java UI are provided in the folowing section ACP Testing.

ACP Testing

Use Case 7 execercises the rules defined for the Access Control Policy. This section provides detailed instructions on how to perform tests for Use Case 7 using the Java UI. Detailed documentation on teh use of the Java UI is available here. Once logged-in, the UI displays two tabs: Discover and Submission. The Discover tab is used for executing Business and Ad-hoc queries against existing Registry objects. The Submission tab is used for publishing new objects.

• Test: Publish a service

Log in as ServicePublisher and select the Submision tab. Select Service from the droplist and click the Insert button (shaped like a diamond) immediately to the right of the droplist. An icon representing the Service will appear on the canvas. Right-click this icon and select Edit. Give the Service a Name in the name field and add text to the description field. Click OK. Right-click on the icon again and select Save. Click OK in the Save dialog, leaving the two checkboxes un-checked. The test is successful if no Error message is displayed. For a negative test, log in as Service Administrator and publish a Service. An error message will be displayed on trying to save the new Service.

• Test: Edit a Service

Log in as Service Publisher Right-click on the new Service and Select Edit. Change the description and click OK. Right-click on the icon again and select Save. Click OK in the Save dialog, leaving the two checkboxes un-checked. The test is successful if no Error message is displayed. For a negative test, log in as Service Administrator and repeat these steps. An error message will be displayed on trying to save the changes to the Service.

• Test: Publish a Classification on a Service

Log in as Service Publisher Right-click on the new Service and Select Edit. Right-click on the Classifications list box and select Insert. A Classification dialog box will appear. Click the ClassificationScheme button near the bottom of the dialog. This will display a Classification Schemes selector. Initially, this will show only Scheme nodes. Select an appropriate Scheme node and an expansion symbol will appear beside the node, forming a Tree View. Expand the npnode by clicking on this symbol to see a list of Classifications for that scheme. Select the desired Classification and click OK. The Logical and Unique Identifiers will be populated in the classification dialog. Click OK and the classification will be added to the Classifications list in the SEService dialog. Click OK to complete editing of the Service. Right-click on the icon again and select Save. Click OK in the Save dialog, leaving the two checkboxes un-checked. A classification has now been published on the Service and the test is successful if no Error message is displayed. For a negative test, log in as Service Administrator and repeat these steps. An error message will be displayed on trying to save the changes to the Service.

• Test: Service Publisher can only publish a Service or an Association.

A ServicePublisher is unable to publish other types of Registry Objects. While logged in as ServicePublisher, select something other than Service from the droplist (e.g. External Link) and click the Insert button (shaped like a diamond) immediately to the right of the droplist. An icon representing the Object will appear on the canvas. Right-click this icon and select Edit. Give the object a Name in the name field and add text to the description field. Click OK. Right-click on the icon again and select Save. Click OK in the Save dialog, leaving the two checkboxes un-checked. The test is successful if an Error message is displayed.

• Test: Service Publisher can only create or edit a Service or an Association.

Select the Discovery tab and perform a BusinessQuery on Object Type of Service. In the resuts list, highlight the service and then right click. Choose one of the following from the pop-up menu: Remove From Registry, Approve Deprecate or Undeprecate. An error message will display indicating that the user does not have permissions to perform these actions.

• Test: Publishing an Association.

A ServicePublisher can publish Association only if all of following conditions are true; the sourceObject is an existing Organization; the targetObject is an existing Service; the Subject has an Association with Organization where associationType is "AffiliatedWith".

To test this, set up the association between ServicePublisher and an Organization. To run this test, it is necessary to have the uid of Service Publisher, the service being published and the Organization being associated with the Service. Login as SuperUser and perform the Business queries to find these UIDs and record them. Next, switch to the Submission tab. Add an Association, set the sourceObject ID to be the unique ID of ServicePublisher and the targetObject ID as the MGS id (urn:ca:on:gov:mgs) and select "AffiliatedWith" from the Association Type drop list. Click OK and then right click-the Association Icon and select Save. ServicePublisher is now associated with MGS.

Log out and login as ServicePublisher. For a positive test publish an association between the Service and MGS. As before, select Association from the drop list and select the Insert icon. Right-click to Edit. Enter the Organization UID as the Source, Object ID, and the Service UID as the Target Object ID. Select "OffersService" from the AsAssociationType drop list and click OK. Right-click on the AsAssociation icon and select Save. The association is successfully published of no Error message is displayed. For a negative test, using the same steps above, try to publish an association between the Service and another Organization. Perform another business query to get the UID for a different Organization.