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 sytem.
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 licences 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: There is currently no installation routine for installing the PermissionsHdlrs.
The following is the current method for installation: Figure 3: PermissionsHdlr showing Client.exe connected under the
Guest account. 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: LI>The MaintTool is now ready for use. Figure 4: MaintTool.exe showing the Guest and PermMaint accounts 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� Dataworks
Enterprise� The 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. 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 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: 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. 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. Similarly, instruments can be assigned ProductIDs from more than one authority.
In this mode, the accounts MUST have entitlements from both authorities. 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. 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, is equivalent to explicitly applying default field masking in the form: 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.
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. 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. 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. This tab is used for creating and deleting the accounts that clients can be
assigned membership of. This tab is used for managing the set of user entitlements that define which
clients join a particular account. This tab can be used define the set of sources that clients of a particular
account can see. 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. This tab manages the creation of groups of Product IDs on a per Authority basis. 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 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. 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 the 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. 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. 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 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. 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 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 fieldsHow to Do Permissions
Permissions Overview
Setting up the Permissions Database
Installing the Permissions Handler
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 authentification 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 checkfailed: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.
Installing the MainTool Application
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 authentification 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.
Permissions: A Tutorial
Creating Permissioned Sources: TestPerms
Unrestricted Permissions Mode
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
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
' 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
' 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
Field Level Permissions Mode
'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
'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
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
The Guest Account
Creating New Accounts
Accounts
Account Members
Account Sources
Account Entitlements
Product Groups
Product IDs
Defining Account Membership
Dim pcpal As New RTPrincipal
pcpal.UserId = "myname"
pcpal.Password = "mypwd"
'logon to permissions
pcpal.Logon RTClient1
'request data as normal
Assigning Sources to Accounts
Creating Product Groups
Adding Product IDs to Product Groups
Assigning Entitlements to Accounts
Setting up Entitlements that Perform Field Filtering
