How to Do Permissions

This document describes the permissioning system used within Dataworks Enterprise. After a brief overview of how permissioning is implemented, the document details the steps required to set up and test the permissioning system.

It is assumed that the reader is familiar with Dataworks Enterprise architecture, in particular the concept of Handlers which utilise RTServers and RTSources to publish data into Dataworks Enterprise, and Client applications that utilise RTClient and RTRecord objects to request data from the system.

Readers unfamiliar with Dataworks Enterprise are referred to the Client Control and Server Control sections of The Platform.doc available on the release CD for an overview of the above components.

Permissions Overview

Prior to release version 2.10 (build 147) of Dataworks Enterprise, no direct form of permissioning was implemented within the product. Any client application could request data from any source. The only form of 'permissioning' that existed was the capability to deny access to sources by configuring the Remote Server or Remote Client modules not to export or import specified sources.

Figure 1: Conventional view of sources and clients within Dataworks Enterprise cache.

However, most data vendors apply some form of restriction around the accessing of their content. This can take the form of licenses restricting the number of users that can access the data, fee based real-time versus charge-free delayed content, or layered levels of content. Without permissioning, it is impossible to restrict what data client applications can access.

Permissioning within Dataworks Enterprise is implemented by using a logical source in a similar manner to that used for data content. This Permissions source can be exported around the network using the conventional RemoteServer and RemoteClient module, providing all the benefits of Dataworks Enterprise scalability, resilience and reliability. This source is used solely by Dataworks Enterprise' cache, and is kept hidden from client applications.

When client applications first load, the cache makes a logon request containing its user credentials to the Permissions source. These user credentials are used by the permissioning system to assign the client application to an Account, and to return to the client the set of sources and instrument entitlements, known as the permission set, the account is permitted to access. By default the client uses the Windows domain and computer names (or System account if running as a service) as part of the user credentials, but these can be overridden by the application developer using the RTPrincipal object introduced in release 2.1.0.

The returned permission set is maintained for the duration of the lifetime of the client application, and can be modified by making adjustments to the entitlements assigned to the underlying account within the permissioning system. Since the entitlements are returned as part of the initial request from the client to the Permissions source, adjustments are sent to the client's cache using the instrument update mechanism inherent in Dataworks Enterprise.

The permission set defines the list of sources the client applications are permitted to access. Sources not specified within this list are never exposed to the client application. The set also includes a list of instrument entitlements. These are basically sets of integers (ProductIDs) grouped by an identifier termed an Authority. An authority is usually a unique identifier (i.e. namespace) assigned to one or more sources that interact with a specific supplier of data. These sets of ProductIDs (Product Groups) define the range of instruments the client is entitled to access. When the client application makes requests to a source for data, each instrument returns the set of ProductIDs (again grouped by authority) that define the permissions for that instrument. The client application compares the returned permission set with the entitlements returned during account login. If there is a match, then the data is passed through for processing by the client. If there is no match with the account entitlements, the data is not passed through for processing. Instead, the client is notified that the data was blocked due to permisisoning restrictions.

From the source developer point of view, there is no requirement to understand anything about client credentials or their entitlements. The developer simply has to create a suitable authority for the underlying source, and to assign a suitable ProductID to each item requiring permissioning. Thereafter, Dataworks Enterprise will automatically take care of the matching of account entitlements with the instrument's permission settings and apply or deny updates.

Figure 2: The Permissioning components of Dataworks Enterprise

Figure 2 shows the components that make up the permissioning system. Key to the system is the Permissions Database. This is a Microsoft SQL Server database used to store the accounts, the user credentials that define account membership, and the list of entitlements that belong to each account. All the other tools interact with this database.

The Permissions Handlers mount the Permissions source onto Dataworks Enterprise platform. Client applications request logon information from Dataworks Enterprise source, supplying their user credentials in the process. The Permissions Handler queries the database using these credentials to determine the account the client should be assigned to, defaulting to the Guest account if no match is found. The database is finally queried using the account details to extract the source and authority entitlements. These are then returned to the client application. The Permissions Handler also periodically queries the database for any accounts that have had their entitlements modified by the system administrator. Any account changes are sent as updates to all the downstream clients that are members of the account.

The system also provides administration tools that permit the administrator to create and manage the accounts, including specifying member credentials and assigning entitlements. The MaintTool utility currently provides these capabilities. A COM API is also under development to enable system administrators to develop their own management tools.

The final components in the permissioning system are the import tools. These utilities, utilising the COM API, allow the suppliers of the data, the Authorities, to remotely manage the Product Groups that customers are permitted to assign as entitlements to accounts. An example of these utilities would be where an application queried a data supplier's site using a user ID and password. The remote site would then send the client's set of permissions as an XML stream for ingest into the database.

Setting up the Permissions Database

Permissioning requires that the permissions handler, PermissionsHdlr.exe, and the maintenance tool, MaintTool.exe, have access to a database where all the account information is stored. Since the Permissions source exposed by PermissionsHdlr.exe must be exposed to all downstream client applications, it is recommended that the PermissionsHdlrs are located at the top of Dataworks Enterprise platform hierarchy. When deciding where the database should reside, bear in mind that all the boxes supporting PermissionsHdlr and MaintTool.exe will need to be able to access the database.

The SQL Server specific Database Definition file, PDPP.DDL, is available from the Platform Development team. This script file defines all the tables, fields and triggers required for permissioning within Dataworks Enterprise. Using the SQL Server Query Analyzer under an administrator account, open the PDPP.DDL file, select the master database and execute the script.

The script file precreates 2 system user IDs for the PDPP database: "PermMaint" to allow access for the maintenance tool, and "pdpp_user" used by the PermissionsHdlr to obtain account settings. For system security purposes, these user details  should be amended as soon as possible so that only the permitted permissioning and system administrators can access the database.  However, the current version of the PermissionsHdlr attempts to connect using the username and password "pdpp_user".  For now the pdpp_user settings should be left untouched; the access rights do not permit modification of any table. The maintenance tool prompts for database login details during start up (or can optionally use a command line argument of the form "Data Source=DSN;uid=USER;pwd=PWD"). The PermMaint user details can therefore be modified immediately.

The script file also creates a default permissioning account called Guest used for any client applications that fail to be assigned to any other account.

Installing the Permissions Handler

The PermissionsHdlr executable mounts the Permissions source on Dataworks Enterprise platform. All downstream RTClient objects login to the Permissions source, via the RTPrincipal object, and are assigned to an Account. This Account contains the source and product entitlements the RTClient object is permitted to see. When the RTClient object receives updates from Dataworks Enterprise, it applies these entitlements to determine if the client application can receive the data.

The PermissionsHdlr has the following requirements:

  • A DSN connection to the Permissions SQL Server database with access rights equivalent to the database system user "pdpp_user", created during the database initialisation.

  • To be positioned at a high enough level within Dataworks Enterprise platform hierarchy that all downstream Dataworks Enterprise (client) platforms can access the Permissions source.

  • To be run in conjunction with a properly configured Dataworks Enterprise RemoteServer or FreewayServer so that the Permissions source can be exported to downstream clients.

    There is currently no installation routine for installing the PermissionsHdlrs. The following is the current method for installation:

  • Obtain the latest versions of PermissionsHdlr.exe, .dat and .scp from the Platform Development team.

  • The desired machine must have the current release of Dataworks Enterprise (minimum version 2.10 (Build 147)) pre-installed. As a minimum, this installation must have a RemoteServer or FreewayServer installed. The RemoteServer or FreewayServer must be configured such that the Permissions source will be exported to downstream client machines.

  • If Dataworks Enterprise installation includes RemoteClnt or FreewayClient applications, their configurations must be set such that they do not import a Permissions source from any other machine.

  • Copy the PermissionsHdlr.exe into the \Primark\Platform\Bin folder on the drive where Dataworks Enterprise software was originally installed.

  • Copy the PermissionsHdlr.dat and PermissionsHdlr.scp files into the \Primark\Platform\Config folder on the drive where Dataworks Enterprise software was originally installed.

  • Within the system registry, add "PermissionsHdlr.scp" as a key (of type string) to HKLM\SOFTWARE\Primark\Platform\Launch. This setting will tell the RTLaunch utility to load the PermissionsHdlr application on start up.

  • From the "Data Sources (ODBC)" option in the Windows Control Panel (in Windows 2000 you also have to select the Administrative Tools folder), add a Data Source (DSN) "PDPP" that will connect to the Permissions database installed previously (see Setting up the Permissions database). If the PermissionsHdlr is going to be run as a service (as part of Dataworks Enterprise installation), the DSN will have to be added under the System DSN tab rather than the User DSN tab.

    The current implementation of the handler attempts to connect as "pdpp_user" to the DSN named "PDPP". The DSN name must currently therefore be "PDPP" and the original pdpp_user settings set up when the database was installed must be maintained. The pdpp_user access rights do not permit modification of any tables within the database.

    When setting the SQL Server authentication details, select the option to use a login ID and password entered by the user. The client configuration details should be set as recommended by the database administrator. In order to get the default settings for the additional configuration options, you will have to enter login details. When first set up the database has login details with user ID "PermMaint" and password "PermMaint". If your database administrator has changed these details, he/she should supply you with the relevant login details.

    All the other DSN set up details can be left as default.

  • Run up the PermissionsHdlr.exe in the absence of any other Dataworks Enterprise products. On launching, the PermissionsHdlr checks the connectivity to the database. A successful connection will produce a log of the form:

    27/06/01 13:07:53 [I] Checking database connection...
    27/06/01 13:07:55 [I] Database connection established

    If problems are encountered, the log will be of the form:

    27/06/01 13:06:09 [I] Checking database connection...
    27/06/01 13:06:10 [E] Database connection check failed: DSN=zz;UID=xx;pwd=** Data source name not found and no default driver specified.

    The error message is the message returned from the ODBC command that failed. This should give some indication of why the failure occurred. The above error message occurs if the DSN setting is wrong or not properly setup. If the user details are wrong, a "Login failed for user 'xx'" message would be returned.

  • From the View menu, select the Sessions to display the view of client connections. This will currently be an empty list.

  • Run up a client.exe (Start Menu\Programs\The Press\The Press Client). On checking the PermissionsHdlr's sessions view, you should find that the client.exe has been connected under the Guest account as indicated in Figure 3. The Host and Windows User details should match the computer name and current login details for the local machine.

  • The PermissionHdlr is now ready for use.

    Figure 3: PermissionsHdlr showing Client.exe connected under the Guest account.

    Installing the MainTool Application

    The MainTool executable allows Dataworks Enterprise permissions to be setup and maintained within an installation where permissioned sources are being used. It is used to create Accounts and define what client credentials are required in order to join an Account. Once an Account has been created, it can be configured in terms of specifying what sources are exposed and what entitlements are permitted. Currently the MaintTool is the only utility available for setting up and maintaining Dataworks Enterprise permissions. A COM interface is also under development that will allow custom tools to be developed to set up and maintain these permissions. Tools developed under this COM interface will permit a more automated method of initialising the permissions database, and may also provide remote ingest, maintenance and auditing of third party entitlements.

    The MaintTool has the following requirements:

  • A DSN connection to the Permissions SQL Server database with access rights equivalent to the database system user "PermMaint", created during the database initialisation.

  • A current release of Dataworks Enterprise (minimum version 2.10 (Build 147)). Dataworks Enterprise does not need to be running; the MaintTool simply uses some of the Permissioning objects provided by the product suite.

    The MaintTool makes additions and modifications directly to the SQL Server database. As entries are modified, triggers within the database record the changes within a table that is periodically checked by the PermissionsHdlr (30 second default). When changes are detected by the PermissionsHdlr, they are retrieved and forwarded to all the connected clients that are members of the account affected by the modification.

    To install MaintTool:

  • Obtain the latest versions of MaintTool.exe from the Platform Development team.

  • Copy the MaintTool.exe into the \Primark\Platform\Bin folder on the drive where Dataworks Enterprise software was originally installed.

  • From the "Data Sources (ODBC)" option in the Windows Control Panel (in Windows 2000 you also have to select the Administrative Tools folder), add a Data Source (DSN) that will connect to the Permissions database installed previously (see Setting up the Permissions database).

    The MaintTool prompts for the DSN login details when launched. There is therefore no restriction on the name or user details required for the DSN. However, since the MaintTool can modify the database contents, it must have the same access rights as those set up for the PermMaint user when the database was first installed.

    When setting the SQL Server authentication details, select the option to use a login ID and password entered by the user. The client configuration details should be set as recommended by the database administrator. In order to get the default settings for the additional configuration options, you will have to enter login details. When first set up the database has login details with user ID "PermMaint" and password "PermMaint". If your database administrator has changed these details, he/she should supply you with the relevant login details.

    All the other DSN set up details can be left as default.

  • Although the MaintTool prompts for the database login details when first started, this can be overridden by adding "Data Source=xx;uid=yy;pwd=zz" as a command line argument to the application on start up, where xx, yy and zz are the DSN, user ID and password respectively. However, bear in mind that this technique potentially exposes the database login password.

  • Run up the MainTool utility and fill in the DSN details when prompted by the login dialog box. If the login fails, you will get a dialog box that provides an error message. The error message is the message returned from the ODBC command that failed. This should give some indication of why the failure occurred. If the DSN setting is wrong or not properly setup, the message will be of the form "Data source name not found and no default driver specified". If the user details are wrong, a "Login failed for user 'xx'" message will be returned.

  • Selecting Cancel on the Login dialog will bring up the MaintTool main window, but will disable the user interface.

  • If the MaintTool successfully connects to the database, it will display the existing accounts. Running up MainTool after initially installing the Permissions database will result in the Accounts tab displaying the default Guest and PermMaint accounts, as shown in Figure 4.

    LI>The MaintTool is now ready for use.

    Figure 4: MaintTool.exe showing the Guest and PermMaint accounts

    Permissions: A Tutorial

    The following tutorial is designed to introduce the various stages required to create a permissioned source, and to then configure the Permissions database such that downstream clients can access the source's content. In all steps used in this tutorial the TestPerms application is used to provide the permissioned source, and the client application (select Start Menu… Programs… The Dataworks Enterprise… Dataworks Enterprise Client) is used to test the data retrieval. In order to view and amend the permission settings, you will need to run both the MaintTool and the PermissionsHdlr applications. These tools require a DSN connection to the permissions database as described in previous sections.

    Creating Permissioned Sources: TestPerms

    The TestPerms sample VB code, available from Platform Development, demonstrates the coding required in order to create a permissioned source. TestPerms has 3 modes of operation: unrestricted, item level (basic) permissioning, and field level permissioning (see Figure 5). It returns dummy content for any request.

    Figure 5: The TestPerms application

    Unrestricted Permissions Mode

    In this mode (the "No Permissioning" option), TestPerms simply responds to requests for data by returning an image without any attached permissioning information. In this mode the source is termed unrestricted. Any downstream client that can see the source can request all the available instruments supported by the source. Requests are simply handled as follows:

    	Private Sub RTServer1_Request(ByVal Source As RTCtl.IRTSource, ...
    		' We have a request for an instrument
    		'construct the field list
    
    		Dim flds As New RTFields
    		flds.Add "Symbol", Item.Instrument
    		flds.Add "Name", "Blah Blah"
    
    		' and so on

    ' image the field list

    Item.ImageFields flds End Sub

    Item Level Permissions Mode

    In this mode ("Basic Permissioning"), the source assigns one or more ProductIDs to each instrument requested. These ProductIDs are integer values grouped by a string identifier termed an Authority. An authority is usually a unique identifier assigned to one or more sources that interact with a specific source of data. For example, all Dataworks Enterprise sources that interact with Thomson's GlobalTopic feed, implement item permissioning using the "PGE" authority. Similarly, all sources that interact with the Datastream server, implement permissioning under the "Datastream" authority. Since ProductIDs are simply integers, assigning them to an authority provides a method of tracing ProductIDs back to the originating source of the permissions.

    Within the permissioning system, once a client application has been assigned to a particular account, it receives a list of entitlements that have been previously assigned to that account. These Entitlement units known as Product Groups, are defined sets of ProductIDs grouped by Authority. These entitlements are stored by Dataworks Enterprise for the duration of the account session. When the client application makes requests to a source for data, each instrument returns the set of ProductIDs (again grouped by authority) that define the permissions for that instrument. The client application compares the returned permission set with the entitlements returned during Account login. If there is a match then the data is passed through for processing by the client. If there is no match with the account entitlements, the data is not passed through for processing. Instead, the client is notified that the data was blocked due to permisisoning restrictions.

    The benefit of this approach is that the developer of the permissioned source does not have to know anything about client connections or their entitlements. The developer simply has to assign suitable ProductIDs within an Authority group to each item requiring permissioning. The administrator of the permissioning system will take care of creating accounts, assigning user credentials for what accounts client applications join, and what entitlements are assigned to specific accounts. Thereafter, Dataworks Enterprise will automatically take care of the matching of account entitlements with the instrument's permission settings and apply or deny updates.

    In "Basic Permissions" mode, requests to TestPerms are handled in much the same way as for the unrestricted case, except that the authority and ProductIDs need to be assigned to the instrument.

    	Private Sub RTServer1_Request(ByVal Source As RTCtl.IRTSource, ...
    		' We have a request for an instrument
    
    		' We need to set an authority and product ID for the item
    		Dim perm As RTPermission
    		Set perm = Item.Permissions.Add("MY_AUTH")
    		perm.Add 400 ' 400 may define London equities for example
    
    		'construct the field list as per normal
    		Dim flds As New RTFields
    		flds.Add "Symbol", Item.Instrument
    		flds.Add "Name", "Blah Blah"
    	
    		' and so on
    		' image the field list
    
    		Item.ImageFields flds
    	End Sub
    

    In the above example code we create a RTPermission object with authority named "MY_AUTH" and assign the ProductID 400 to the instrument. Thereafter the code simply continues to construct the image in the same way as for the unrestricted example. All downstream client applications will need to be members of accounts that have the ProductID 400 on the MY_AUTH authority within one of its assigned entitlements in order to access the data.

    In the actual example code for the "Basic Permissions" option within the TestPerms application, the ProductID value is toggled between 400 and 500 on alternate requests. We will see further on in the tutorial how this affects the downstream clients, and how we can create Product Groups that contain both Product IDs to fully entitle clients to see all the instruments.

    In practice, there will probably be many ProductIDs, with each instrument assigned at least one from the list. The definition of these ProductIDs will depend on the permissioning model of the underlying data feed. For example, for sources that interface to the GlobalTopic feed, the ProductIDs are simply integer representations of the Closed User Groups (CUGs) provided by the GlobalTopic feed for instrument level permissioning on GlobalTopic Workstations. Similarly, for Datastream derived sources, the ProductIDs are just integer representations of the Logical DataBases (LDBs) used to retrieve the Datastream data.

    Developers can assign more than one ProductID within an authority to each item and can specify whether accounts need to be entitled for either one or both ProductIDs in order to access the data. For example, the following code specifies that an account needs to be entitled to both the London and European Equities ProductIDs in order to retrieve the data.

    		' We need to set an authority and product ID for the item
    
    		Dim perm As RTPermission
    		Set perm = Item.Permissions.Add("MY_AUTH", True)

    ' True parameter implies client must be entitled to ALL the ProductIDs ' False, implies client must be entitled to any one of the ProductIDs perm.Add 400 ' 400 could represent London Equities perm.Add 800 ' 800 could represent European Equities

    Similarly, instruments can be assigned ProductIDs from more than one authority. In this mode, the accounts MUST have entitlements from both authorities.

    		' We need to set an authority and product ID for the item
    		Dim perm As RTPermission
    		Set perm = Item.Permissions.Add("AUTHXXX")
    		perm.Add 500 ' definition of 500 is specific to AUTHXXX
    		Set perm = Item.Permissions.Add("AUTHZZZ")
    		perm.Add 345 ' definition of 345 is specific to AUTHZZZ
    

    Finally, keep in mind that not all instruments necessarily need to be permissioned. If there are some instruments that you require all clients to see, e.g. index, help, copyright instruments, etc., these should not be assigned any ProductIDs in the same way as for unrestricted sources. When Dataworks Enterprise applies permissions, it only does filtering on instruments that have RTPermission data attached. Hence, when we talk about restricted and unrestricted sources, we are really talking about restricted and unrestricted instruments.

    Field Level Permissions Mode

    Before reading this section, it may be worthwhile jumping forward and reading the sections on configuring accounts and adding entitlements using just the "Basic Permissions" setting on TestPerms. The following section assumes you are familiar with adding accounts and entitlements and dealing with permissioning at the instrument level.

    Field Level permissioning, known as field filtering, builds on item level permissioning in that field filtering is only applied on items that the client is permissioned for. i.e., the client application must have the instrument's ProductID and authority assigned as an entitlement within the account it belongs to.

    Field filtering is the process of enabling or disabling access to specific fields depending on the mask called the SubProduct that is assigned to the ProductID. Downstream client entitlements can be set such that they can only see a subset of the fields contained within an image or update. Field filtering allows the source developer to create instruments that combine (for example) both delayed and real time data and to let Dataworks Enterprise determine which of the field sets a client application receives. The developer does not need to know anything about the client application's permissioning level. Downstream clients request the same instrument regardless of whatever permissioning level their account is entitled to see. Dataworks Enterprise filters out only those fields the client is permitted to access under the assigned entitlement.

    A typical scenario is where back-office personnel (e.g. settlements) are permitted to see only delayed (exchange free) data, whereas front-office personnel (e.g. traders) are permitted to see real-time data where exchanges typically charge fees. By merging the real-time and delayed updates into one instrument, users can run the same applications independent of whether they are front or back-office users. When performing field filtering, Dataworks Enterprise renames filtered fields by stripping off the last three characters. If the delayed and real-time fields are appropriately named by the source developer, field filtering can remap the delayed and real-time fields to a common field set, permitting the downstream applications to process the same fields of the instrument regardless of the account entitlements.

    Another scenario is where instruments that return fundamental research data may have to support several types of client, ranging from guest level through to premium accounts. The instrument in this case could return fields with multiple SubProduct IDs, with each client level being entitled to see a range varying from just a few introductory fields (guest level), all the way up to the premium level that is permissioned for the entire field set. Again, the source developer merely has to output all the fields with the appropriate masking and let Dataworks Enterprise deal with the particulars of each client. Dataworks Enterprise currently supports up to 16 levels of field masking (SubProducts) on a single instrument.

    Field masks are applied by setting the AuthInfo property of each field to a mask value of between 0 (the default) and 15. When operating in the "Basic Permissions" mode where no field masking is applied, the TestPerms code implicitly applies the default mask value of 0 to all the added values. A field mask of 0 is the lowest level of permissioned field, and is always displayed if the client is permissioned for the instrument. For example,

    	'construct the field list
    
    	Dim flds As New RTFields
    	flds.Add "Symbol", Item.Instrument
    	flds.Add "Name", "Blah Blah"
    	' and so on

    ' image the field list Item.ImageFields flds

    is equivalent to explicitly applying default field masking in the form:

    	'construct the field list
    	Dim flds As New RTFields
    	Dim fld As RTField
    
    	Set fld = flds.Add( "Symbol", Item.Instrument)
    
    	fld.AuthInfo = 0 ' default mask
    	Set fld = flds.Add( "Name", "Blah Blah")
    
    	fld.AuthInfo = 0 ' default mask
    
    	' and so on

    ' image the field list Item.ImageFields flds

    In "Field Filtering" mode, the TestPerms application produces instruments with combined delayed and real time fields. Fundamental fields such as the Symbol ID and the instrument name are output with the default field mask 0. The real-time fields are assigned a mask value of 1 and delayed fields use a mask value of 2. Since Dataworks Enterprise renames filtered fields by stripping off the last 3 characters, the real-time fields append "_RT" and the delayed fields append "_DL" to all their field names. Downstream clients will see either BID_RT or BID_DL as BID depending on the entitlement assigned to their account. Fundamental fields, assigned the default field mask valueof 0, do not have their field names modified by Dataworks Enterprise.

    	Private Sub RTServer1_Request(ByVal Source As RTCtl.IRTSource, ...
    
    		' We have a request for an instrument

    ' We need to set an authority and product ID for the item Dim perm As RTPermission Set perm = Item.Permissions.Add("MY_AUTH") perm.Add 400 ' 400 may define London equities

    ' Fundamental fields are fields that should be displayed regardless of the downstream ' masking applied by Dataworks Enterprise caches. As long as the client is entitled to see this item, 'they should be able to see all the fundamental fields. So we leave the AuthInfo ' property as default Dim flds As New RTFields flds.Add "Symbol", Item.Instrument flds.Add "Name", "Blah Blah" ' real-time fields use a mask value of 1 and use names ending with "_RT" Dim fld As RTField Set fld = flds.Add("BID_RT", 545.23) fld.AuthInfo = 1 Set fld = flds.Add("ASK_RT", 563.71) fld.AuthInfo = 1 ' we can do both instructions in one go flds.Add("DELAY_RT", "").AuthInfo = 1 ' delayed fields use a mask value of 2 and use names ending with "_DL" Dim fld As RTField Set fld = flds.Add("BID_DL", 321.67) fld.AuthInfo = 2 Set fld = flds.Add("ASK_DL", 355.01) fld.AuthInfo = 2 ' we can do both instructions in one go flds.Add("DELAY_DL", "20 minutes").AuthInfo = 2 ' and so on ' image the field list Item.ImageFields flds End Sub

    Managing the Permissions Database

    This section of the tutorial walks through the steps required to create permissioning accounts and to set up user credentials for joining them. Using the TestPerms application, you will see how Dataworks Enterprise applies the permissioning rules to allow or deny access to an instrument's data.

    The Guest Account

    When first installed, the permissions database creates a guest account that clients are assigned to if their user credentials do not entitle them to join any other accounts. As first installed, the Guest account entitles all member clients to see every source in the system, but requires them to apply permissioning rules where supplied by the source. Since the Guest account does not have any entitlements when first created, this means that client applications will be able to request data from unrestricted sources but will be barred from accessing data from restricted sources. In practice, the Guest account should ultimately be set up such that members are restricted to the minimum set of sources and entitlements required to support base level clients.

    Running up Dataworks Enterprise Client application from Dataworks Enterprise menu, you should see from the PermissionsHdlr' Sessions view that the application is assigned to the Guest account (Figure 3). The Host column will contain the computer name where the client is connecting from. The Windows User column details the domain name and the logged on user name for the given computer (for Windows95/98 the Windows User column displays the computer name and the logged on user name). If the client application runs as a Windows service, the Windows User column will contain the computer name and "System". (Prior to Dataworks Enterprise version 2.1.0 SP2, the column contained "NT AUTHORITY\SYSTEM" for applications running as a service). If the client application uses the RTPrincipal object to logon with a particular set of user credentials, the Effective User column will display the user name passed to the RTPrincipal object. Readers are referred to "The Platform" document, available on the release CD, for an overview of how the RTPrincipal object can be used to log client applications onto specific accounts.

    Using the TestPerms in "No Permissions" mode, Dataworks Enterprise Client application should be able to request and receive data from the source TestSrc. Switching the TestPerms to "Basic Permissions" mode will result in Dataworks Enterprise Client being refused access to data. Dataworks Enterprise Client will display a "not authorised to access record" message on the title bar as in Figure 6. This is the status message returned in the ChangeStatus event on the RTClient object.

    Figure 6: Dataworks Enterprise Client displaying a "not authorised" message

    The TestPerms application appends permissioning information to each instrument on the source under the "MY_AUTH" authority. In order for Dataworks Enterprise Client to access these instruments, it will have to be assigned to an account that has entitlements to the MY_AUTH authority. In the following sections we will create this account, specify user credentials that allow Dataworks Enterprise Client application to join the account, create entitlements for the MY_AUTH authority that include the Product IDs used by TestPerms, and then assign these entitlements to the newly created account. Thereafter, Dataworks Enterprise Client should be able to access the restricted data.

    Creating New Accounts

    Figure 4 shows the MaintTool application's user interface. The user interface consists of a number of tabs each used for configuring a specific section of the permissions.

    Accounts  

    This tab is used for creating and deleting the accounts that clients can be assigned membership of.

    Account Members

    This tab is used for managing the set of user entitlements that define which clients join a particular account.

    Account Sources

    This tab can be used define the set of sources that clients of a particular account can see.

    Account Entitlements

    This tab is used to manage the entitlements that are assigned to an account. The Product Groups available here are defined using the Product Groups and Product tabs.

    Product Groups

    This tab manages the creation of groups of Product IDs on a per Authority basis.

    Product IDs

    This tab allows the inspection and modification of the Product IDs available within a Product Group. At the moment this is the only means of creating Product IDs within the permissioning system (other than directly ingesting into the database with a dedicated SQL tool). When the COM interface that allows custom tools to be developed to set up and maintain these permissions becomes available, it is more than likely that this tab will be modified to only allow inspection of the Product IDs within a Product Group.

    Since the TestPerms application puts out 'delayed' and 'real-time' fields in "Field Filtering" mode, we will ultimately need to create 2 accounts. We will call these accounts BACKOFFICE and FRONTOFFICE, and will ultimately assign them with the delayed and real-time entitlements, respectively. Selecting the Accounts tab on MaintTool, we add the details for the BACKOFFICE as shown in Figure 7.

    Figure 7: Creating the BACKOFFICE Account

    The Description field can be any text that reasonably defines the function of the account. The Max Logons field defines the maximum number of concurrent clients the account is allowed to have. Setting this value to -1 specifies that the Account can have an unlimited number of concurrent users. Some accounts may be assigned entitlements to data from authorities that demand a limit on the number of concurrent users accessing their data. For example, licensing agreements or fees on a particular source of data may restrict the number of users allowed to see the data. In this case, the account can restrict the number of clients by setting the limit in the Max Logons field. The Unique Session checkbox can be used to ensure that each client logon is treated as a separate session even if clients logon with the same user credentials.

    The Default Access and Commands Allowed controls are used to set the default attributes for all the sources that are not specifically set up for this account in the Account Sources tab. The Default Access control can be set to restricted, denied or unrestricted. The restricted setting is the default setting, allowing the cache to apply permissioning if the instruments supply entitlement data. The denied setting prevents account members from seeing any sources that are not specifically assigned to the account in the Account Sources tab. This setting would typically be applied to the Guest account. The unrestricted setting should only be used for debugging purposes. In this mode Dataworks Enterprise is instructed to ignore the permissioning information supplied with any instruments from these sources. This allows downstream clients to see all the raw fields provided by a source without field filtering being applied by Dataworks Enterprise (where the last 3 characters of the masked fields are stripped of before delivery to the client). This mode should only be set on accounts that are used by source developers when analysing problems with either the source or the permissions system. The Commands Allowed option simply defines whether Dataworks Enterprise Commands are passed to the source. For more details of Commands, refer to "The Platform" document, available on the release CD.

    Pressing the Add button on the Accounts tab will add the BACKOFFICE account to the permissions system. Repeating the same process for the FRONTOFFICE account should produce a display similar to Figure 8.

    Figure 8: The FRONTOFFICE and BACKOFFICE Accounts

    Defining Account Membership

    Now that we have our accounts set up, we need to specify how client applications become members of these accounts. To do this we use the Account Members tab.

    In this tab, the user credentials are displayed for all the accounts in the system. Selecting a specific account from the Account ID and enabling the Selected Account Only control, will just display the user credentials for the selected account. User credentials are specified by providing a login name and an optional password. There is also the option of limiting user credentials to specific computers using the Host Name field.

    Downstream applications that do not supply user credentials via the RTPrincipal object, such as Dataworks Enterprise Client application, run under the desktop and use the current NT login details as the user credentials. In this mode, the login name provided is a combination of the domain and account names of the computer logging in. The supplied password is an empty string, and the host name is the name of the computer running the downstream application. The examples that follow were created under the account SharkeyJ, on a computer named JSHARKEY, running under a local domain also called JSHARKEY. Dataworks Enterprise Client applications running under this account will logon to the Permissions system using the following credentials:

  • Host:   JSHARKEY

  • Name: JSHARKEY\SharkeyJ

  • Password:

    For applications running under a service, and which do not use an RTPrincipal object to supply user details, the Name field will include the service account details. If the service is running under the system account, the Name field will be a combination of the computer name and "System". For example, an application running as a service on computer JSHARKEY will logon to the Permissions system using the following credentials:

  • Host:   JSHARKEY

  • Name: JSHARKEY\System

  • Password:

    Note, for versions of Dataworks Enterprise software prior to version 2.1.0 SP2, applications running as a service under the system account supplied "NT AUTHORITY\SYSTEM" in the Name field when logging in.

    Using an RTPrincipal object within an application, allows the client to login with credentials other than the default NT account or system service details. This permits multiple applications running on the same desktop to login to separate permissioned accounts. The user details can be loaded from a registry setting or entered directly by the user.

    		Dim pcpal As New RTPrincipal
    
    		pcpal.UserId = "myname"
    		pcpal.Password = "mypwd"
    		'logon to permissions
    		pcpal.Logon RTClient1
    
    		'request data as normal
    

    The above code would log onto the permissions system using the following credentials:

  • Host:   JSHARKEY

  • Name: myname

  • Password: mypwd

    The Account Members tab of MaintTool.exe has three fields, User ID, Host Name and Password that allow you to specify the user credentials required to join a particular account. As a minimum, the User ID must be specified. For applications running under the desktop or as a service, the password field should be left blank. Leaving the Host Name field blank will mean that applications can login using the User ID and password from any computer within the system. Otherwise the login will be restricted to the specified computer name.

    Selecting the BACKOFFICE account we created earlier, we can add the credentials that will allow Dataworks Enterprise Client application to join this account. Since Dataworks Enterprise Client application is running on the local desktop and does not use an RTPrincipal object, it will attempt to login using the current NT login details:

  • Host:   JSHARKEY

  • Name: JSHARKEY\SharkeyJ

  • Password:

    Entering these details into the Account Members tab and selecting Add, should add an entry as demonstrated in Figure 9.

    Figure 9: Adding user credentials for the BACKOFFICE Account

    Figure 10: PermissionsHdlr showing Client.exe connected to the BACKOFFICE account.

    Running up Dataworks Enterprise Client application from Dataworks Enterprise menu, you should see from the PermissionsHdlr' Sessions view that the application has been assigned to the BACKOFFICE account (Figure 10). Requesting data from Dataworks Enterprise Client application (with TestPerms running under "Basic Permissions" mode) will still result in no data being visible (Figure 6). We still need to create the entitlements under the authority MY_AUTH used by TestPerms, and to assign these to the BACKOFFICE account.

    Assigning Sources to Accounts

    Depending on how an account was set up when first created, members of an account can be configured to have or be denied access to all the sources in the system. The Default Access field in the Accounts tab applies this attribute to all sources that are not specifically set up in the Account Sources tab.

    The Account Sources tab allows the permissions administrator to permit or deny access to specific sources within an account. In addition, each of the sources can be renamed if required. For example, there may be a case for 2 discrete data sources that access the same fundamental data; one for back-office personnel and one for front-office personnel. Although Dataworks Enterprise provides field filtering such that these two classes of user could request data from the same source, restrictions within the underlying data feed may not permit this or make it feasible. In this case the permissions administrator can use the Account Sources tab to permit each of the accounts to see only one of the two sources, and can rename both sources such that all downstream users see a standard source name.

    As an example of how to use the Account Sources tab, we can add an entry for the TestSrc source created by the TestPerms application under the BACKOFFICE account, rename it to MySource, and mark the access type as unrestricted (Figure 11). Marking the source as unrestricted instructs Dataworks Enterprise to ignore the permissioning information supplied with any instruments from this source. With this setting, when Dataworks Enterprise Client joins the BACKOFFICE account, it will see the source MySource, and will be able to request data from any instrument on this source (Figure 12). The fact that the BACKOFFICE account has no entitlements to the MY_AUTH authority provided by the TestPerms application is completely ignored by Dataworks Enterprise. This mode should only be set temporarily on accounts when you need to analyse problems with either a source or the permissions system. Overriding the entitlements provided by a permissions authority may violate any user agreements with the data vendor.

    Figure 11: Adding an alias for the TestSrc source under the BACKOFFICE account

    Figure 12: The Account Sources tab can be used to temporarily override permissioning

    In order to proceed with the tutorial, where we will add entitlements for the MY_AUTH authority to the BACKOFFICE account, the above entry for the TestSrc source in the Account Sources tab will have to be deleted.

    Creating Product Groups

    Assigning entitlements to an account involves assigning one or more precreated Product Groups. Product Groups are defined sets of ProductIDs grouped by Authority. In practice, Product Groups should be created and maintained by offline tools that ingest the Product IDs directly into the permissions database using the forthcoming COM API. The Product Groups and Products tabs within the MaintTool utility should only be used to inspect these groups and to assign them to specific accounts. However, the current version of MaintTool allows the administrator to create Product Groups and Product IDs on the fly. We will use this capability to entitle members of the BACKOFFICE and FRONTOFFICE accounts to access the content of the source supported by the TestPerms application.

    The Product Groups tab within the MaintTool utility allows the permissions administrator to view the list of Product Groups currently available. Creating a Product Group consists of simply adding a group name and a suitable description of what purpose the Product Group serves.

    For the purposes of this tutorial we will create a Product Group named Auth400 to which we will assign the single Product ID 400. Figure 13 shows the Auth400 Product Group after it has been added to the list of current Product Groups. We then need to use the Products tab to add Product IDs to this group.

    Figure 13: The Product Groups tab

     

    Adding Product IDs to Product Groups

    Under the "Basic Permissions" mode of the TestPerms application, data requests are assigned Product IDs alternating between the values 400 and 500. Within the Product Group Auth400 created in the previous section, we will assign only the Product ID 400. When we later assign this Product Group as an entitlement to the BACKOFFICE account, we will see that account members will only be able to access every second instrument on the TestSrc source. This will demonstrate how Dataworks Enterprise permissioning denies access to data if the entitlements do not match the Product IDs returned by the instrument.

    In the Products tab of the MaintTool utility, selecting a Product Group lists all the Product IDs that have been assigned to that group. The MaintTool currently provides the ability to add and delete Product IDs from Product Groups. In future releases this functionality will be denied once the COM API becomes the sole route to managing Product Groups and IDs.

    Selecting the Auth400 Product Group should display an empty list of Product IDs. Figure 14 shows the entries required to add the Product ID 400 to this group. The Product field should contain the Product ID to be assigned; in this case 400. The Authority field should contain the name of the authority to which the Product ID belongs, namely MY_AUTH.

    The Sub Product field specifies the mask to be applied for field filtering. Since we are currently dealing only with the TestPerm application operating in Basic Permissions mode, we wish to display all the fields in the instrument. In this case we simply set the Sub Product to -1 to enable all fields. We will look more closely at how to set the Sub Product in order to perform field filtering in the last section of this tutorial.

    Figure 14: Adding Product ID 400 to the Auth400 Product Group

    The Description field is a user readable entry specifying the fields that will be enabled with the given Sub Product. The description is authority specific, but since we are displaying all fields, and since we know TestPerms outputs fundamental, delayed and realtime fields, the entry specifies these field types. When we later look at field filtering, we will see how this field description helps to define what the Sub Product mask allows.

    Assigning Entitlements to Accounts

    With the Product Group defined and the Product IDs assigned to the group, assigning entitlement is simply the process of adding the Product Group to the account. The Entitlements tab simply displays a list of available Product Groups and a list of Product Groups assigned to the selected account. Assigning or removing entitlements simply involves moving Product Groups between the lists of Assigned and Available Product Groups. Each account can have one or more entitlements.

    Assigning Product Group Auth400 to the BACKOFFICE account (Figure 15) and running up Dataworks Enterprise Client application should enable the client to display data from the TestPerms application in Basic Permissions mode (as per Figure 12). However, because each alternate request returns a Product ID of 400 or 500, and since the entitlement only permits instruments with a Product ID of 400, every second request will be denied. This demonstrates how Dataworks Enterprise applies permissioning at the instrument level.

    One other thing to note is that Dataworks Enterprise updates permissions on the fly. Whenever an account entitlement is modified, a transaction is placed in an audit table within the database. Periodically (by default every 30 seconds), the Permissions handler queries this audit table and applies any changes to the account. Therefore, removing the Auth400 from the BACKOFFICE's entitlements should result in all requests being denied after 30 seconds.

    Figure 15: Adding Product Group Auth400 as an entitlement to BACKOFFICE

    The Auth400 Product Group only provides entitlement to Product ID 400. In order to fully enable Dataworks Enterprise Client application for all instruments on TestSrc, we also need to provide entitlement for Product ID 500. We could do this by creating a separate Product Group with a single Product ID 500 and assign this as an additional entitlement to the BACKOFFICE account. However, we can assign both IDs to a single Product Group. Figure 16 shows a Product Group "Auth" that has both the Product IDs 400 and 500 assigned to it. Removing the Auth400 group from BACKOFFICES's entitlements and assigning Auth (Figure 17) will now enable Dataworks Enterprise Client to access all the instruments supported by the TestSrc source.

    Figure 16: Adding Product IDs 400 and 500 to the Auth Product Group

    Figure 17: Adding Product Group Auth as an entitlement to BACKOFFICE

    Setting up Entitlements that Perform Field Filtering

    In "Field Filtering" mode (the Field Level Permissions section of this document discusses this mode in detail), the TestSrc source applies a field mask to each returned field using the AuthInfo property of the field. The source does not need to know anything about the downstream client application's permissioning level. Instead, each field is given a specific field mask that can be enabled or disabled within a specific Product Group created on the Permissions system. When this Product Group is assigned as an entitlement to an account, Dataworks Enterprise uses the Sub Product fields to filter out only those fields the client is permitted to access under the assigned entitlement.

    From the section discussing Field Level permissions, The Sub Product field specifies the mask to be applied to all the returned fields, provided the client is permissioned for the instrument. The developer of the source can assign a field mask value between 0 and 15 to each field. Fields with a mask value of 0, fundamental fields, are always displayed if the client is permissioned for the record. All other field mask values must be set within the Sub Product field in order for the specified fields to be delivered to the client application.

    The Sub Product field is a bitfield where each bit represents one of the possible field mask values. Setting a particular bitfield to 1 will enable that particular field mask. Since field mask 0 is always enabled, bit 0 represents field mask 1, bit 1 represents field mask 2, and so on. In effect, to enable fields with a mask value of n, the Sub Product field will need to have bit (n – 1) set. For example, if the Product Group is to display only fields that have a mask value of 0, 1, 4 or 9, the Sub Product value would have to be set to:

    0 + 2(1-1) + 2(4-1) + 2(9-1) = 265

    In the previous section of the tutorial, we added the Product Group named Auth as an entitlement to the BACKOFFICE account. This Product Group contained the Product IDs 400 and 500, each with a Sub Product field with value -1. This field value enabled all fields of the TesSrc source to be presented to client applications. Switching the TestPerms application from Basic Permissions to Field Filtering mode outputs a field set that combines both delayed and real-time data. Requesting instruments from the TestSrc source using the previously assigned entitlements will result in all the _RT and _DL fields being displayed as in Figure 18.

    Figure 18: TestSrc in Field Filtering mode with all fields enabled

    In practice, the entitlements should be setup such that client applications should only be entitled to either the real-time or delayed fields. To do this we need to modify the Sub Product fields of the assigned Product IDs such that clients of the BACKOFFICE account will see the delayed data, and FRONTOFFICE clients will see the real-time data.

    Figure 19: The Product Groups tab with AuthFrontOffice and AuthBackOffice groups

    First of all we create 2 Product Groups, AuthFrontOffice and AuthBackOffice, as shown in Figure 19 (we can also delete the Auth and Auth400 groups since we no longer have a need for them). In Field Filtering mode, the TestPerms application assigns a mask value of 1 to the real-time fields and a mask value of 2 to the delayed fields. In the Products tab of Maintool we need to add entries for Product IDs 400 and 500 to both the AuthFrontOffice and AuthBackOffice groups. We then need to assign the value 1 (2n-1 where n is 1 => 1) to the SubProduct field for both Product IDs within the AuthFrontOffice group, and the value 2 (2n-1 where n = 2 => 2) to the SubProduct fields for the AuthBackOffice group as shown in Figure 20 and Figure 21. Note the entries for the Description fields have been modified to indicate that the field masks are setup to display either "Fundamental, RealTime" or "Fundamental, Delayed". These descriptions are useful for the administrator when assigning Product Groups as entitlements.

    Figure 20: The AuthFrontOffice Product Group with real-time mask settings

    Figure 21: The AuthBackOffice Product Group with delayed mask settings

    Finally, the Product Groups need to be assigned as entitlements to the relevant accounts as shown in Figure 22 and Figure 23.

    Figure 22: The AuthFrontOffice Product Group assigned to the FRONTOFFICE account

    Figure 23: The AuthBackOffice Product Group assigned to the BACKOFFICE account

    The previous settings for the BACKOFFICE account entitled client applications to see all the fields returned by the TestSrc source (Figure 18). After the new account entitlements have been applied by the Permissions handler (up to 30 seconds delay), Dataworks Enterprise Client application will only display the fundamental and delayed fields as shown in Figure 24. Note that the delayed field names have been renamed to remove the _DL appendage.

    Figure 24: BACKOFFICE account members see only fundamental and delayed fields

    In order to check that the FRONTOFFICE account can see only the fundamental and real-time fields, we need to get Dataworks Enterprise Client application to log onto this account. To do this we need to switch the user credentials from the BACKOFFICE (Figure 9) to the FRONTOFFICE account (Figure 25). To do this you select the user credentials in the list, select the FRONTOFFICE account from the Account Id dropdown list, and then select the Update button. Dataworks Enterprise Client application will now be assigned to the FRONTOFFICE account (Figure 26 -- note: in early versions of the Permissions handler, the reassignment will only occur when the client application is restarted). Dataworks Enterprise Client application will now only be able to access the fundamental and real-time fields (Figure 27). As for the BACKOFFICE settings, the real-time fields are renamed to remove the _RT appendage. The effect of the field renaming is that all client applications see the same field names regardless of whether the fields are real-time or delayed. Thus the downstream applications can be the same regardless of the accounts they access. Note that we could also have cheated and switched the BACKOFFICE account to have the AuthFrontOffice group as an entitlement to ensure that this entitlement only permitted fundamental and real-time data.

    Figure 25: Changing the user credentials to the FRONTOFFICE Account

    Figure 26: PermissionsHdlr showing Client.exe connected to FRONTOFFICE account.

    Figure 27: FRONTOFFICE account members see only fundamental and real-time fields