Open DACS Application Best Practices

Introduction

Overview

DACS (Data Access Control System) is the permissioning sub-system of Thomson Reuters Enterprise Platform (TREP).  Open DACS enables development of applications that conform to DACS permissioning, allowing clients to manage access to fee liable data within their firms.

This article provides "best practice" recommendations for Open DACS application developers to ensure an application is implemented to correctly support all DACS features exposed through the API.  

Where appropriate it also describes the potential impact of not following the recommendations.

Audience

Open DACS application developers and Market Data Systems specialists concerned with managing TREP and Open DACS deployments.

Open DACS Developer Responsibilities

The development of an Open DACS application places a responsibility on the developer to ensure that, as a bare minimum, it conforms to all of the DACS entitlement controls. Any failure in this requirement may result in data compliance exposure with legal and commercial implications.

DACS Features and the Open DACS API

These DACS features are exposed to the Open DACS programming interface and therefore depend on the application to use the API correctly in order to support them:

  1. User Authorization : A user must be authorized before any protected data is made available by the application
  2. Simultaneous Position Access: The maximum number of positions a user can login simultaneously is specified by the DACS user entitlement: “Allowed Simultaneous Login”.
  3. Application Entitlement (optional)
  4. Service Entitlement : A user must be authorized to use the service before any data can be requested
  5. Subservice Entitlement : Within a service such as Elektron Real-time there will be many Exchanges and information providers supplying content, each venue will be entitled separately; applications must comply with these subservice entitlements in order to protect access to this content.
  6. DACS On Demand: A cost saving feature in which the user is dynamically entitled to data when access is requested
  7. Authorization Migration : Allows users to migrate and return their profile from one desktop to another desktop or device whilst honouring the limit on the maximum number of simultaneous logins. Described in [3] DACS Reference Manual (Chapter 2 “System Description, Active DACS Server”)
  8. Usage Data: A record of each data access requested.

Open DACS Login

The Login method exposed at the Open DACS SDK and Open DACS Permission Server is required to support the following DACS features: User Authorization (1), Simultaneous Position access (2) and Application Entitlement (3).

Before any other authorization request, an Open DACS application must first ensure that the user login request is successful. This requires valid parameters for the user name, the Application Identifier and the position.

The Login process is among the more expensive operations available, involving the transmission and in-memory caching of the users entitlement profile; The login request must therefore be used efficiently; Application behaviour patterns that login to take a ‘snapshot’ of a user’s entitlement and then logout should be avoided.

This behaviour pattern can reduce scalability and in many cases it will not conform to DACS entitlements.

User name and the Multi-connect feature

Applications with a user-base that spans across DACS sites will need to use the Open DACS multi-connect feature in order to connect to a DACS daemon at each site and a means to determine the site/connection at which the user is defined.

If an application employs a polling strategy to determine the site at which the user is located, i.e. trying each connection until the user login is successful, then the definition of user names must be unique across sites. Ensure that this is the case before adopting this strategy.

If active users are not unique between sites then a user login can be registered at the wrong site by the application.

To improve performance of the login process when a polling strategy is employed an application should record the connection used, i.e. the site at which the user is located, thus allowing any further login request for the same user to be directed to the same connection and avoid repeating the polling process.

Without a mechanism for remembering where a user is located Open DACS application clients may experience delays as each repeat login request must also repeat the polling process.

Application Identifier

For any new application development that will perform entitlement checks or consume data on the Enterprise Platform ensure that an entry is created in the list of applications by the DACS Administrator. The application will be assigned a name and a number. The number is the Application Identifier or “AppId”.

The login request must include the correct AppId and not rely on generic application such as the “Def_SSL_App” (AppId=256).

Note: When using the SDK, the value is set using the StandardPrincipalIdentity method setAppName(), the AppId must always be the number value as a string, not the application name (as the method signature suggests).

The AppId is used in usage reporting, item consolidation features and entitlement checking, if any application entitlement features are enabled (e.g. See Multiple Instance Profiling) and is also registered on TREP which provides necessary information to support the application.

An incorrect or generic AppId can result in missing usage reports, incorrect entitlements and when the application cannot be identified by the AppId it may impede support activities.

Where an application will be deployed to a large number of clients, e.g. a marketed third-party software product, then the application can be registered with DACS product management so that it can be predefined in the application list.  See [2] DACS Best Practices Guide  for more information.

Do not use the same AppId for an OpenDACS application and TREP consumer API activity.

DACS does not provide any other means by which to report that the access is being requested through an OpenDACS application versus a TREP consumer; it will prevent separate reporting of usage and entitlements now and in the future.

Position Parameter

The position parameter relates to the host or device used by the client for whom the login is requested. It is a string containing a combination of the IP Address and the  name of the display on which the data will be consumed.

The positon is used to track where a user is logged in and count the number of different positions used concurrently by the same user, it is crucial for enforcing Simultaneous Position Access. It must identify where the client is viewing data and be one of the following formats:

< IP Address> /net

The IP Address where the data will be consumed by the user, with no hostname specified.

<IP Address>/<hostname>

The IP Address where the data will be consumed by the user, with the specified hostname.

<IP Address1>/<IP Address2>

This format is used where the data is on-passed to a display device, e.g. a host on <IP Address1> consumes data and on-passes the information to display device <IP Address2>. Simultaneous login checks are performed against <IP Address2>.

The IP address is specified in the format nnn.nnn.nnn.nnn, where nnn is a decimal number between 0 and 255, following the normal convention for IP addresses.

Example:  “10.1.6.218.11/net”.

The IP Address must be consistent across all deployed DACS enabled applications, identifiable as a physical position or device and accurately reflect where the data is being consumed:

An application that does not provide position information consistent with other deployed DACS applications will incur a potential costs for the business because it will require an increase in the number of allowed simultaneous accesses.

Do not use the loopback address or any other generic address;

Position entitlement control will be circumvented and the application will fail any audit involving unit of access count.

Avoid using the address of the Open DACS server application for client login requests.

This is a form of generic address being used by the Open DACS application in which the applicaiton makes no distiction between different positions that the client may use with the same user name. For users of this Open DACS application the "Allowed Simultaneous Login" entitlement control will be circumvented and the application will fail any audit involving unit of access count.

In addition, using the address of the Open DACS server will not reflect the host or device at which the client is consuming the data and will incorrectly appear as an additional position when any other DACS enabled application is used by the same client from the same host or device. The “Allowed Simultaneous Login” will have to be increased and in effect this may lead to "double charging" for access to the data.

Generating Position Information

When an environment does not provide an Open DACS application access to client IP Addresses, wherever possible, avoid synthesizing IP Addresses to create ‘logical’ positions.

Such ‘logical’ positions will not be consistent with other DACS applications and will therefore be counted against the simultaneous login count when any DACS enabled applications is used by the same client. The “Allowed Simultaneous Login” will have to be increased and consequently a potential increase in data costs.

Any generated position information must map 1:1 to an active physical position.

An application that cannot discriminate between physical positions cannot enforce Simultaneous Position Access and will fail any audit involving unit of access count.

Open DACS Logout

When an application performs an Open DACS user Logout, access to any protected data must be withdrawn;

An application that continues to provide protected data after a logout has occurred will circumvent entitlement features supported by Open DACS Login, at the very least the application will fail any audit involving unit of access count.

Service Entitlement

To check user entitlement to service the checkSubscription method is available in the Open DACS SDK and the equivalent Open DACS Permission Server command: subscriptionTest.

It requires a valid service name and item name parameter. Where the service uses Subject-Based entitlements, this method will also perform the necessary subject entitlement checks on the item name parameter.

Always perform an intial Service entitlement check, even where it is known that a subsequent CBE entitlement check is required after the data is retrieved; Where there is a cost involved in fetching the content, it is more efficient when the request is denied at the initial service entitlement check.

Content Based Entitlements

For content based entitlement services when an application uses the checkSubscription method/ subscriptionTest to determine user entitlement it is mandatory to include the service, item and DACS Lock.

Do not omit the item name:

Usage data will not be loaded into the DACS Database if the item name is absent.

Do not omit the DACS Lock:

False positives will result if the DACS Lock is not present – without it Open DACS can only report the user entitlement to the service, not the subservice, consequently the resulting usage data will not resolve to a subservice entitlement usage. Any application that supplies data from a CBE service on the basis of a checkSubscription result when the DACS lock is absent cannot comply with the data access policy of venue from which it was sourced.

Regardless of the strategy employed by an application for last-value caching, always retrieve and cache the DACS Lock provided with the data response (unless the DoNotCache flag is set);

  1. The DACS Lock can change over time.
  2. The DACS Administrator may change the user entitlements.

Processing DACS Lock Changes

When protected data is consumed with an update stream, it is possible that a change to the DACS Lock will be received. A consuming application that uses an Elektron API or RFA will receive an unsolicited Refresh or Status message containing the new DACS Lock on any affected streaming request.

A change to the DACS Lock must trigger checkSubscription/subscriptionTest entitlement checks using the new lock for all downstream subscribers of the affected data;

If no action is taken when the DACS Lock changes then users may continue viewing data that they are no longer entitled to access.

When a subsequent DACS Lock is received, the application should compare it with the original to determine if it has changed. A comparison provides an optimisation where there are multiple clients viewing the associated data; If the comparison indicates that the DACS Lock is unchanged then no further action is required.

Without a comparison, every time a DACS Lock is received it must trigger checkSubscription entitlement checks using the received lock for all downstream subscribers of the affected data.

Where an application does not cache the original DACS Lock it must unconditionally perform entitlement checks for all subscribing clients whenever a DACS Lock is received, this introduces unnecessary additional processing on any message that contains the DACS Lock.

Processing Entitlement Changes

When the DACS Administrator changes a user’s entitlement they come into effect only when a distribute operation is performed, an Open DACS application will receive a DoRepermission event for any affected user in order to alert the application to the change.

When new entitlements become active the application must re-check the entitlements for all open requests associated with all affected users.

Where CBE services are in use an entitlement re-check will require the DACS Lock associated with the open requests, an application that does not cache the DACS Lock must re-request the item in order to retrieve it and this introduces unnecessary additional processing and request/response traffic on both the application and infrastructure. When scaling up an application this behaviour can affect the stability of a system and must be avoided by caching the DACS locks for all open items.

DACS Lock Recovery

DACS Lock information is normally retrieved from the message header when using the Elektron API and RFA consumer interfaces. For Elektron real-time sourced content, if the DACS Lock is not available (e.g. the application is using a legacy API), it can be reconstructed using the value of the PROD_PERM field in the data content.

Note: This technique is only suitable for content sourced directly from an Elektron real-time service; it is not suitable for services that use a compound DACS Lock. Compound Locks are used when republishing data and contain all the DACS Locks of the constituent records from which the republished record is composed.

Handling Authorization Migration

When a DACS a user is enabled for Authorization Migration a login request which would exceed the maximum allowed simultaneous will succeed but the oldest active login will receive a null profile, this will result in a DoRepermission event.

In order to manage this condition correctly an application must react to DoRepermission events by rechecking the user entitlement to all active items. The recheck will result in a denial to any data and the application must act accordingly, removing access to all data which is subject to entitlement control.

An application that does not react correctly to DoRepermission events will not conform to Position entitlements correctly, the new device will be able to access data whilst the Open DACS application continues to permit the original login to continue consuming data.

A login that is subject to Authorization Migration in this way will receive a secondary DoRepermission event when the entitlement is restored, typically when the user has logged out of another position: Where the use-case is applicable, an application may recheck entitlements for all requests that were denied in the previous DoRepermission event. This allows the application to restore subscriptions that were previously denied by the Authorization Migration event.

Where a recheck is not carried out, user intervention will be required to restart the subscriptions previously denied by Authorization Migration.

Usage Data

Every authorization request, such as a login, accepts a usage logging parameter to specify when the request should be logged, the actual parameter values used equate to one of the following:

  • Aways.

    Unconditionally log a usage record for this authorization request irrespective of the result
  • Denial.

    Log a usage record only when the authorization request results in a denial.
  • Success.

    Log a usage record only when the authorization request results in a success (access granted).
  • Never.

    Do not log a usage record for the authorization request irrespective of the result.

In general the setting should only create a usage log when there is a change:

New Requests: Always. The request will be logged when the request is first made.

Repermission of successful active requests: On a repermission event, which will typically occur as a result of a change in the user entitlements, requests that were successful and continue to consume data should be subject to repermission checks with a usage setting to log Denials. This means that only when the successful requests are later denied will there be a record logged, all intervening checks that remain successful do not generate a log.

Repermission of denied requests. For applications that maintain a subscription list that may have some items denied when first requested, they may perform a re-check of these denied requests on a repermission event. In such cases the usage logging parameter should be set to Success. Therefore a usage record is only logged when the result changes from denied to successful.

Subscription Checks versus PE Entitlement Lists

Some application use-cases involve directly accessing the list of entitled PEs contained in the users profile information instead of performing discrete subscription checks.

For the Open DACS SDK this list is provided with by the AuthorizationAgent Interface using the method getPEList(). See Open DACS reference for C++, Java and .NET.

This method can be used to check content-based entitlement instead of using the checkSubscription() method. Note: This is for particular application use-cases; it does not offer any significant optimisation because the PE information is cached in memory for use by the checkSubscription() method.

Without further measures such use-cases will not generate usage-data and as a result entitlements used to obtain data by the application will be identified as unused by the DACS reporting procedures.

Deferred Usage Generation

In order to avoid entitlements being routinely revoked, applications that employ the above use-case can retrospectively generate usage by making calls that would have been made to the OpenDACS checksubscription method at a later time or delegating the task to another process.

When this technique is used the application should ensure that the deferred usage is generated as close as possible to the moment that the data access occurred, it MUST be completed before any entitlement changes are made AND within the same map-collect cycle that the data was actually consumed in order to avoid inaccurate reporting of entitlement usage.

DACS On Demand

The DoD variant of getPEList() provides a list of all assigned PE entitlements and those available via DACS on Demand assignment: getODPEList();

When allowing a user access to a PE on the basis of the On Demand assignment a corresponding checkSubscription method call is mandatory. This is required to notify DACS that the user has accessed a DACS On Demand Exchange.

Web Services interface

This is an interface to the administrative functions available through the DACS Console. It should not be used for entitlement checking on market-driven production applications.

The Web Services interface operates on and depends on the DACS Station, it is not appropriate to use this interface for entitlement checks because it does not have the same performance or resilience characteristics as the Operational DACS components used by Open DACS.

By design the availability of the DACS Station affects the administrative role, it does not affect the operation of the production environment. An application must not use the Web Services interface in such a way as to introduce a dependency on the DACS Station into the production environment, this will result in a greater risk of production outages.

References

[1] OpenDACS Multi-connect option

[2] DACS Best Practices Guide

[3] DACS Reference Manual

[4] Open DACS C++ User Guide

[5] Open DACS Java Reference Manual

[6] Open DACS .NET User Guide

[7] RFA C++ Reference Manual

[8] RFA Java Reference Manual

[9] RFA .NET Reference Manual

[10] ODPS Developers Guide

[11] DACS Web Services Programmer's Guide