Adding users and permissions

Note: The following guide is optional. If you wish to begin setting up a connection to live RET data, see Connecting to Live RET Data.

This page will show you how to add and permission users to use the RET functionality facilitated by the Adapters. You will understand how the permissions config works, and use an example to permission users for trading.

Overview

Each adapter in the RET Adapter Suite will run separate from the rest of the Adapter Suite, and so has its own connection to user and permissions data. By default the adapters load users and permissions from XML files.  Included with the CaplinRETAdapterSuite.zip is a PermissioningAdapter that uses XML files to configure users and permissions. The user and permission configuration is used by the adapters to perform user-to-RET client mappings; the adapters themselves are not individually responsible for authorising users. User authentication is handled by Liberator in conjunction with the Permissioning Adapter. The role of the Permissioning Adapter is to supply the Caplin Platform with permissions. A logins.xml file specifies users that are permitted to log in and view or use the system, and a permissions.xml file specifies group-based permission rules.

There are three key extension points which handle XML based user and permission loading. The user information in logins.xml is dealt with by UserManager and AuthenticationManager. The UserManager is used by all of the adapters for client mapping. The AuthenticationManager is used exclusively by the Permissioning Adapter. The last of these extension points is PermissionLoader which is also used by the Permissioning Adapter and deals with the information in permissions.xml. The Permissioning Adapter will load permissions on startup and send them to Liberator.
 

Note: Integration with a custom permissions system, instead of XML, is possible by implementing the aforementioned extension points.

Adding Users

The logins.xml file defines users and assigns them to groups which determine their permissions to view and use the system. Because each adapter needs user data, ensure that when new users are added, each adapter with a logins.xml is updated. 

For each of the FxTradingAdapter, PricingAdapter, LBNAdapter, LimitOrderAdapter and PermissioningAdapter edit the contents of global_config\overrides\<adapter name>\etc\logins.xml using the following XML example config:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE logins SYSTEM "logins.dtd">
<logins>
  <admins>
    <user ssoName="admin" password="admin" groups="LiberatorStatus" />
  </admins>
  <sales>
    <default tradesOnBehalfOfClients="client1 client2" client="clientst" groups='Global AllTenors OrdersFX TwoWayPricing' />
    <user ssoName="salestrader1@caplin.com" />
    <user ssoName="salestrader2@caplin.com" tradesOnBehalfOfClients="client1" />
  </sales>
  <traders>
    <default groups="Global AllTenors OrdersFX TwoWayPricing" />
    <user ssoName="user1@caplin.com" client="client1" />
  </traders>
  <clients>
    <client name="clientst" retFxClient="caplinst_fxclient" retPmClient="caplinst_pmclient" />
    <client name="client1" retFxClient="caplin1_fxclient" />
    <client name="client2" retPmClient="caplin2_pmclient" />
  </clients>
</logins>

Understanding the example

  • admins
    • user
      • ssoName - name used to login (required)
      • password - plaintext password (required)
      • groups - set of permitted groups (required)
  • sales Typically trade on behalf of other clients
    • default - these settings are applied to all sales users by default
      • tradesOnBehalfOfClients - set of clients permitted to trade for, each must be in clients
      • groups - set of permitted groups
      • client - client used to retrieve rates for the sales user, has to be one of clients
    • user
      • ssoName - name used to login (required)
      • tradesOnBehalfOfClients - set of clients permitted to trade for, overrides the default, each must be in clients
      • groups - set of permitted groups, overrides the default
      • client - client used to retrieve rates for the sales user, overrides the default, has to be one of clients
  • traders Typically trade on their own behalf
    • default - these settings are applied to all traders by default
      • groups - these are the set of permitted groups
    • user
      • ssoName - name used to login (required)
      • client - client used to trade, has to be one of clients (required)
      • groups - set of permitted groups, overrides the default
  • clients Clients that are registered on the RET system
    • client
      • name - name registered with RET (required)
      • retFxClient - client used to retrieve FX rates
      • retPmClient - client used to retrieve PM rates

​In the logins.xml you can assign group permissions to the ssoName via userGroups.

Warning: After editing the configuration, the adapter blade will require a restart. To (re)start the blade, use the command ./dfw start.​ 

Adding Permissions

The permissions.xml file contains rules and groups which define permissions.  ​

Example Permissions Configuration

In the following example we create two rules which match Spot and Forward ESP trades, and a third rule which selects the tenor field. We also create two groups, Global and AllTenors - we use Global to permit streaming rates and trading restricted to the ESP type we defined, and AllTenors to specify valid tenor values.

Copy the default file over from active_blades\PermissioningAdapter\DataSource\etc\permissions.xml to global_config\overrides\PermissioningAdapter\etc\ to implement the following XML example config:

<?xml version="1.0" encoding="UTF-8"?>
<permissioning xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="Permissions.xsd">
  <rules>
    <rule productRef="ALL_PRODUCTS" subjectNameMatch="^/PRIVATE/TRADE/FX/%u" ruleType="WRITE" action="ESP-SPOT" permissionNamespace="FX_ESP">
      <fieldMatchCriteria>
        <match criteria="TradingProtocol" value="ESP" />
        <match criteria="TradingType" value="SPOT" />
      </fieldMatchCriteria>
    </rule>
    <rule productRef="ALL_PRODUCTS" subjectNameMatch="^/PRIVATE/TRADE/FX/%u" ruleType="WRITE" action="ESP-FWD" permissionNamespace="FX_ESP">
      <fieldMatchCriteria>
        <match criteria="TradingProtocol" value="ESP" />
        <match criteria="TradingType" value="FWD" />
      </fieldMatchCriteria>
    </rule>
    <rule productRef="ALL_PRODUCTS" subjectNameMatch="^/PRIVATE/TRADE/FX/%u" ruleType="WRITE" actionRef="L\d+_Tenor" permissionNamespace="FX_TENOR_LIST" />
  </rules>
  <groups>
    <group name="Global">
      <permissionSet>
        <productPermissionSet productSet="^/PRIVATE/TRADE/FX/%u">
          <permission auth="ALLOW" action="VIEW" />
          <permission auth="ALLOW" action="WRITE" />
        </productPermissionSet>
        <productPermissionSet productSet=".*">
          <permission namespace="FX_ESP" auth="ALLOW" action="ESP-ONECLICK" />
        </productPermissionSet>
      </permissionSet>
    </group>
    <group name="AllTenors">
      <permissionSet>
        <productPermissionSet productSet=".*">
          <permission namespace="FX_TENOR_LIST" auth="ALLOW" action="TODAY" />
          <permission namespace="FX_TENOR_LIST" auth="ALLOW" action="TOM" />
          <permission namespace="FX_TENOR_LIST" auth="ALLOW" action="SPOT" />
          <permission namespace="FX_TENOR_LIST" auth="ALLOW" action="1D" />
          <permission namespace="FX_TENOR_LIST" auth="ALLOW" action="1W" />
          <permission namespace="FX_TENOR_LIST" auth="ALLOW" action="2W" />
          <permission namespace="FX_TENOR_LIST" auth="ALLOW" action="3W" />
          <permission namespace="FX_TENOR_LIST" auth="ALLOW" action="1M" />
          <permission namespace="FX_TENOR_LIST" auth="ALLOW" action="3M" />
          <permission namespace="FX_TENOR_LIST" auth="ALLOW" action="6M" />
          <permission namespace="FX_TENOR_LIST" auth="ALLOW" action="1Y" />
        </productPermissionSet>
      </permissionSet>
    </group>
  </groups>
</permissioning>

Understanding the example

  • rules Configure which subjects allow contributions, which enables trading
    • rule - each rule can identify a different RTTP message based on its attributes like subject, trade type and protocol.
  • groups Groups define permissions, single inheritance of groups is possible
    • group - each group can contain sets of product permissions.
      • productPermissionSet - a product permission typically applies to a subject or valid values for a given field.

Note: The file Permissions.xsd contains further documentation of the permissions.xml format and can be found in your RETAdapterToolkit-<version>.zip under Permissioning Adapter, in the directory Blade/DataSource/etc/

Product permission sets in more depth

Declare references that can be used in permission sets:

  • rule
    • productNamespace - declaration of namespace used by a permission
    • action - declaration of action (exclusive, actionRef cannot be used)
    • actionRef - should refer to an RTTP field (exclusive, action cannot be used)

productNamespace and action can be used together to identify a specific type and subtype of a message, making it possible to differentiate between an ESP Spot and an ESP Forward trade for example, and to apply different permissions. These two attributes are declared in the example above, and we could have used them to break the Global group into separate Spot and Forward permissions groups if we wanted.

  • productPermissionSet - a product permission typically applies to a subject or valid values for a given field.
    • productSet  - the products that the permission set is defined for
    • permission - list of permission
    • namespace - a product namespace declared in a rule
    • auth - can be either ALLOW or DENY
    • action - a possible RTTP field value (required)

When a productNamespace is combined with an actionRef in a rule, RTTP field values can be individually permissioned if actions are added to a productPermissionSet. Each action in the set represents a field value and auth determines whether it is permitted. We could use this to apply permissions based on tenor value, and restrict certain tenors to particular trade types.

Note: Any time you update permissions it is advisable to restart the adapter blade, see instructions below.

After you have made any edits to the XML files you will need to restart the DFW. Open Cygwin (if using Windows) or your command line tool and navigate to the Deployment Framework’s directory. Then enter following command:


./dfw start