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. 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. 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. 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: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.
Permissions Overview
Setting up the Permissions Database
Installing the Permissions Handler
There is currently no installation routine for installing the PermissionsHdlrs. The following is the current method for installation:
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.
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.
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:
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:
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.
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:
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:
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:
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:
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