Permissioning for TOBO

TOBO stands for “trading on behalf of”. TOBO allows a user who is logged in to a client application to execute trades on instruction from a customer (for example, the customer may give instructions by telephone). The logged in user is called a sales-user, and the customer is called a customer-user (because they are known to the Caplin Platform as an end-user, and are a customer of the organization that employs the sales-user). The sales-user trades on behalf of the customer-user.

An important aspect of this arrangement is that each customer-user can be configured to receive tailored prices for any given traded instrument (price tiering). The prices offered to the customer-user should be the same, regardless of whether that customer-user trades directly through their own login, or a sales-user trades on their behalf.

The Caplin Platform's permissioning system supports TOBO functionality by:

  • Granting or denying a sales-user permission to trade on behalf of a particular customer-user.
  • Ensuring the sales-user has the right permissions to view and trade instruments on behalf of a customer-user.
  • Ensuring the sales-user sees the same tiered prices the customer-user would see.

If your client application is based on Caplin Trader, please contact Caplin Support to find out whether the TOBO facility described here is available in the Caplin Trader release that you are using, and for information on which aspects of TOBO are pre-configured in the Caplin Platform release that was delivered with Caplin Trader.

Contents:

Typical TOBO processing

Here is what happens when a sales-user logs in and receives prices, when he is not trading on behalf of another customer:

Sales User logs in and Receives Prices

  1. A sales-user logs in to the trading application (a client application) as himself; his username is "Bob". The trading application asks the Liberator, via the Client Permissioning API, for the permissions that apply to user Bob. The Liberator obtains these permissions from its Permissioning Auth Module. (The Permissioning Adapter had previously sent these permissions to the Permissioning Auth Module, as shown in the diagram.)
  2. The sales-user wishes to look at the prices for the FX currency pair GBPUSD. The Permissioning Auth Module verifies that he is allowed to do this. For this sales-user, the /FX subject namespace is mapped to tier1 prices, so the Liberator subscribes to /FX/GBPUSD-tier1, and requests this object from the Pricing Adapter that supplies /FX/GBPUSD-tier1.
  3. The Liberator streams the price updates to the trading application. The sales-user therefore sees the prices for GBPUSD that reflect the price tier defined for him as a user.

Now consider the situation where the sales-trader trades on behalf of a customer:

Sales-trader trades on Behalf of a Customer

The sales-user Bob receives a telephone call from a customer-user, Alice, asking him to quote prices for /FX/GBPUSD and possibly trade this currency on her behalf.

  1. When Alice trades for herself, she logs in to the trading application with username "Alice". However in this case, Bob, who is already logged in as himself, merely selects Alice's username from a drop down list in the trading application's UI and clicks on a "trade on behalf of" button.
  2. This action sends a TOBO switch message to the Liberator's Permissioning Auth Module, requesting that Bob be allowed to trade on behalf of the customer-user whose login username is "Alice".
  3. The Permissioning Auth Module checks that the sales-user Bob is permitted to trade on behalf of the customer-user Alice. (The Permissioning Adapter had previously sent these permissions to Permissioning Auth Module.) The Permissioning Auth Module also checks that Alice actually exists in the permissioning system. If one of these conditions is not met, Bob is not allowed to trade on behalf of Alice; the trading application receives notification of this and the prices remain tiered for Bob, just as they were before the attempted TOBO switch.
  4. If the Permissioning Auth Module's checks both succeed, the /FX subject namespace is mapped to tier2, which is the price tier that was allocated to Alice when her trading account was set up. The Liberator therefore subscribes to /FX/GBPUSD-tier2. 
  5. The Liberator streams the price updates for /FX/GBPUSD-tier2 to the trading application. 
  6. Bob therefore sees the prices for GBPUSD that reflect the price tier defined for Alice, on whose behalf he is trading.
  7. (Not shown in the diagram.) Bob could subsequently switch to trading on behalf of the customer-user "Peter", whose prices for /FX/GBPUSD are in yet another tier, tier3.
  8. (Not shown in the diagram.) When Bob has finished executing trades for customer-users, he stops the TOBO session. This restores his streamed prices to those he would normally see when trading for himself (the prices for tier1).

Note that customer-users do not have to be set up to log in and trade directly; they could be set up as Liberator users but not as users of the trading application, so they must always trade through a sales-user.

TOBO permission modes

There are two modes of TOBO permissioning behaviour. The Permissioning Auth Module may be configured, through the TOBOPermissionMode property in its javaauth.properties file, to exclusively use one mode or the other. In each mode, the sales-user can trade as a customer-user; the difference between the modes lies in how the permissions are determined when trading on behalf of the customer-user. Before you deploy your trading system for live operation, you must decide which mode to use and set up permissions accordingly, as explained in more detail in subsequent topics.

The TOBO modes are SalesUser and SalesIntersectCustomerUser.

SalesUser mode

In this TOBO mode, the sales-user's permissions are applied. That is, the permissions normally granted to the sales-user's Liberator session, which apply when he is not using TOBO, also apply when he is using TOBO. This typically means that in order to trade on behalf of different customer-users, the sales-user must be given the aggregate of all the customer-users' permissions.

Set this mode if it is acceptable to your business that few constraints should be applied to sales-users when they trade on behalf of customer-users. Note that in this mode, because a sales-user has all the permissions of the set of customer-users, the sales-user could trade an instrument on behalf of a customer-user that the customer-user would not be permitted to trade. For example:

Customer-user-A can trade FX/GBP.* only.
Customer-user_B can trade FX/AUD.* only.

When the TOBO mode is SalesUser, a sales-user must be allowed to trade both FX/GBP.* and /FX/AUD.* so that he can trade on behalf of Customer-user-A and on behalf of Customer-user-B. But this also allows the sales-user to trade /FX/AUD.* on behalf of Customer-user-A, which this customer-user cannot do on their own.

SalesIntersectCustomerUser mode

In this TOBO mode, permissions granted to both the sales-user and the customer-user apply. If either or both of the permission checks result in a Deny, the operation is denied. For the action to be allowed, both the sales-user and customer-user must be permitted. This is summarised in the following table:

SalesIntersectCustomerUser mode permission checks

Customer-user permission Sales-user permission Resulting TOBO permission is intersection (logical AND)
Deny Deny Deny
Permit Deny Deny
Deny Permit Deny
Permit Permit Permit

This mode of TOBO permissioning is most suited to situations where you wish to constrain what instruments a sales-user can trade on behalf of customer-users, in addition to independently constraining the instruments each customer-user can trade. For example, when there is a large number of customer-users, a particular sales-user cannot easily be aware of what trading restrictions apply to which customer-users. In this case, you can configure the permissions system in SalesIntersectCustomerUser mode, so the sales-user is only allowed to trade the instruments that the customer-user can trade. 

You can also use this mode to constrain what a particular sales-user can do on behalf of all customers. For example, you could prevent a less experienced sales-user from trading in volatile instruments by setting a deny permission for the sales-user. When this sales-user trades on behalf of a customer-user who is permitted to trade volatile instruments, the intersection of permissions prevents the sales-user from trading such an instrument.

Setting the TOBO permission mode

To set the TOBO permission mode you define a property called TOBOPermissionMode in the javaauth.properties file of the Permissioning Auth Module.

Example of TOBO rules and permissions

Here is an example of how rules and permissions work when a sales-user Bob trades on behalf of a customer-user Alice. It shows how Bob is allowed to switch over to trade on Alice's behalf. The example applies to both TOBO modes. In his trading application, Bob selects Alice's name from a list of customer-users and selects a button that requests permission to trade on her behalf. The application responds by sending a TOBO switch message to the Liberator:

TOBO switch message (RTTP Message)

Message Subject Field: Username
/TOBOCHANGEUSER Alice

By convention, the message subject is /TOBOCHANGEUSER, although you can specify a different name through configuration of the Permissioning Auth Module. The message contains a UserName field that identifies the customer-user on whose behalf the sales-user wants to trade; in this case, "Alice".

Object-map configuration in Liberator maps the username of the currently logged in user (the sales-user's  Liberator login name) to the subject of the TOBO switch message. The required configuration is:

object-map  /TOBOCHANGEUSER  /TOBOCHANGEUSER/%u

For sales-user Bob, this changes the message subject to:

/TOBOCHANGEUSER/Bob

The Permissioning Auth Module then looks for a rule that matches the subject of the TOBO switch message (/TOBOCHANGEUSER/Bob). If there is no such rule, Bob will not be allowed to perform a TOBO switch.
A matching rule looks like this:

Rule matching the TOBO switch message

Subject Match Field Match Criteria Product Reference Field Action Namespace
/TOBOCHANGEUSER/%u   UserName

ChangeTrade 

OnBehalfOf 

User

TradeOnBehalfOf

The Subject Match is /TOBOCHANGEUSER/Bob (the Permissioning Auth Module automatically substitutes the Liberator username "Bob" in the %u token). This matches the subject of the TOBO switch message, so the rule applies to the sales-user "Bob". The Product Reference Field of the rule is the field in the TOBO switch message (UserName) containing the name of the customer-user on whose behalf the sales-user wishes to trade. So in this case, the Product Reference field refers to the customer-user "Alice". The Permissioning Auth Module looks for a permission that:

  • is in the namespace defined by the rule (TradeOnBehalfOf),
  • has the action defined by the rule (ChangeTradeOnBehalfOfUser),
  • and is for the product called "Alice" (as defined by the Username field of the TOBO switch message).

The corresponding permission that allows the TOBO switch is:

Permission identified by the rule

Action Product Namespace Authorisation

ChangeTrade

OnBehalfOf

User

Alice TradeOnBehalfOf Allow

This permission has the authorisation "Allow", so Bob is allowed to trade on behalf of Alice. If the permission had the Authorization "Deny", or there was no permission matching the rule, Bob would not be allowed to trade on behalf of Alice. Note that the sales-user must have only one permission for the action ChangeTradeOnBehalfOfUser for each customer-user they can trade on behalf of. In addition to having permission to TOBO switch, Bob must also have sufficient permissions to actually view and trade the same instruments as Alice can. When Bob subsequently trades on behalf of Alice the subject mappings that would apply to Alice if she traded for herself are applied to Bob, so Bob sees the same prices that Alice would. For more information on this, see Subject Mapping.

Switching out of TOBO mode

When a sales-user has finished trading on behalf of a customer-user and does not intend to trade on behalf of yet another customer-user, the permissioning system must be returned to a state where the sales-user can trade on their own behalf, according to their own permissions and subject mappings. This changeover is done by sending a TOBO switch message that specifies a username of "null":

TOBO switch message (mapped)

Message Subject Field: Username
/TOBOCHANGEUSER/Bob null

The same rule is triggered as in Example of TOBO rules and permissions:

Rule matching the TOBO switch message

Subject Match Field Match Criteria Product Reference Field Action Namespace
/TOBOCHANGEUSER/%u   Username

ChangeTrade

OnBehalfOf

​User

 

 

TradeOnBehalfOf

This time the rule selects a permission for the Product called null:

Permission identified by the rule

Action Product Namespace Authorisation

ChangeTrade

OnBehalfOf

​User

null TradeOnBehalfOf Allow

This permission has the authorisation "Allow", which causes the Permissioning Auth Module to apply sales-user Bob's permissions and subject mappings.

ALL_ACTIONS permission

A permission with the special Action name ALL_ACTIONS allows a user to be permitted/denied all actions relating to the specified namespace and product/product set. This type of permission can be used to reduce the number of permissions that a sales-user must have in order to trade on behalf of a customer-user, as the following example shows.

Example

Assume customer-users have one or more trading accounts. There may be many different accounts spread across a large number of customers, and each customer-user must be permissioned to trade on just their own accounts. When customer-user "Alice" trades the instrument /FX/GBPUSD on the account "Account_1", the following RTTP message is sent to Liberator:

Message Subject Message Fields
MsgType Instrument Account {other fields}
/FX/TRADE Execute /FX/GBPUSD Account_1 ...

The rule that matches this trade message is:

Matching rule

Subject Match Field Match Criteria Product Reference Field Action Reference Field Namespace
/FT/TRADE   Instrument Account Accounts

The permission applying to "Alice" that matches this rule is:

Alice's permission 

Action Product Namespace Authorisation
Account_1 /FX/GBP.* Accounts Allow

When Alice trades the same instrument on a different account, "Account_2", the RTTP message is:

RTTP Message

Message Subject Message Fields
MsgType Instrument Account {other fields}
/FX/TRADE Execute /FX/GBPUSD Account_2 ...

The same rule matches this trade message as did previously:

Matching rule

Subject Match Field Match Criteria Product Reference Field Action Reference Field Namespace
/FT/TRADE   Instrument Account Accounts

The permission applying to Alice that this rule matches is:

Alice's permission

Action Product Namespace Authorisation
Account_2 /FX/GBP.* Accounts Allow

Note that Alice has a separate permission for each account. This gives the system administrators the flexibility to control which accounts Alice can trade on, by changing individual permissions. Now if sales-user "Bob" is to be allowed to trade /FX/GBPUSD on Alice's behalf for these accounts, he needs the same permissions as Alice – one per account that Alice is allowed to trade on. But in a deployed system, the number of permissions needed for the sales-traders is (number-of-sales-users) x (number-of-accounts) x (number-of-products). Also, every time we add or remove a permission for a customer-user, we have to add or remove the equivalent permission for all sales-users. Instead of defining another complete set of permissions just for Bob, we can give him a single ALL_ACTIONS permission:

Bob's ALL_ACTIONS permission

Action Product Namespace Authorisation
ALL_ACTIONS /FX/GBP.* Accounts Allow

This permission allows Bob to perform all actions on products that match /FX/GBP.* in the Accounts namespace. When the TOBO permission mode is SalesIntersectCustomerUser, and Bob trades on behalf of Alice, the intersection of Bob's ALL_ACTIONS permission with Alice's permissions (actions Account_1, Account_2), allows him to trade on both of Alice's accounts. Using ALL_ACTIONS permissions in this way makes it easier to maintain permissioning data. The number of ALL_ACTIONS permissions required for the sales-users is just (number-of-sales-users) x (number-of-products), and whenever a permission is added or removed for a customer-user, there is no need to modify the sales-users' permissions.

Only use the Action name ALL_ACTIONS in permissions.
Do not specify ALL_ACTIONS in the Action field of rules.
Explicitly defined permissions override the ALL_ACTIONS permission for the same combination of user, product, and namespace. So, for example, you could still deny Bob the ability to trade /FX/GBPUSD on Alice's behalf, by giving him Deny permission on the Product /FX/GBPUSD for the action Account, in the namespace Accounts.

ALL_ACTIONS when sales-users trade for themselves

Unless your sales-users are highly trusted, you should not give them ALL_ACTIONS permission when they trade for themselves. Set up separate rules and permissions to those used for trading on behalf of customer-users, (not using any ALL_ACTIONS permissions). Assign a different namespace to these rules and permissions, and make sure that different rules are matched by different fields in the RTTP message to those used in the customer-user messages. The following example illustrates this in the case where sales-user Bob trades /FX/GBPxxx instruments on his own behalf:

RTTP Message when Bob trades for himself

Message Subject Message Fields
MsgType Instrument SU_account {other fields}
/FX/TRADE Execute /FX/GBPUSD Account_1 ...

Note that in this message, the field containing the account name is called SU_Account, not Account as in customer-user Alice's RTTP message. The rule that matches this trade message is:

Matching rule

Subject Match Field Match Criteria Product Reference Field Action Reference Field Namespace
/FT/TRADE   Instrument SU_Account SU_Accounts

The Namespace for this rule is SU_Accounts (“Sales Users' Accounts”), not Accounts as in the rules applying to trades on behalf of customer-users.
The permission applying to "Bob" that matches this rule is:

Bob's permission

Action Product Namespace Authorisation
Account_1 /FX/GBP.* SU_Accounts Allow

Because Bob's RTTP message does not contain a Account field, the ALL_ACTIONS permission that Bob has to trade on behalf of other users does not apply when Bob trades for himself. The permission for Action Account_1 in namespace SU_Accounts allows Bob to trade /FX/GBPUSD, but he can only trade other products, such as /FX/AUD.* if he has the relevant other permissions.

ALL_ACTIONS in permission mode SalesUser

A sales-trader should not be given an ALL_ACTIONS permission when the TOBO permission mode is SalesUser, because in this mode, the permission would allow the sales-trader to do anything on behalf of any user.

Enabling/disabling TOBO for a sales-user

It may be desirable to turn TOBO permissions on or off quickly for a given sales-user, without removing the permissions that name the customer-users the sales-user can trade on behalf of (so these permissions don’t have to be remembered and added again when TOBO is turned back on). This can be done by creating an extra rule that is triggered when the Liberator receives a TOBO switch message. Here is an example of how to do this. Assume the sales-user is called Bob. Bob wishes to trade on behalf of customer-user Alice. 

As in Example of TOBO rules and permissions, the TOBO switch message received by the Permissioning Auth Module has the (mapped) subject /TOBOCHANGEUSER/Bob.

TOBO switch message with mapped subject

Message Subject Field: Username
/TOBOCHANGEUSER/Bob Alice

In addition to the rule shown in Example of TOBO rules and permissions, there is another rule that matches this message subject:

Rule matching the TOBO switch message

Subject Match Field Match Criteria Product Reference Field Action Namespace
/TOBOCHANGEUSER/%u   ALL_PRODUCTS ToboOn ToboEnabled

This rule is in a different namespace (see the Tip below) and refers to ALL_PRODUCTS, so the Permission Auth Module searches all permissions for the Action ToboOn in the ToboEnabled namespace. The (single) matching permission is:

Permission identified by the rule

Action ProductNamespace Namespace Authorisation
ToboOn ALL_PRODUCTS ToboEnabled Allow

This permission has the authorisation "Allow", so Bob is allowed to trade on behalf of sales-users, including Alice. If the permission had the Authorization "Deny", or there was no permission matching the rule, Bob would not be allowed to trade on behalf of anyone. Note that the TOBO switch message triggers two rules; the rule shown here that permits or denies trading on behalf of anyone, and the rule shown in Example of TOBO rules and permissions that permits or denies trading on behalf of a specific customer-user. The sales-user is only allowed to trade on behalf of the customer-user if both rules refer to permissions that have Allow authorisation.

The permission namespace (ToboEnabled) should be different to that used for permissioning the customer-users a sales-user can trade on behalf of (ToboSwitchPermissions). This is because permissions used for different purposes should be isolated from each other by namespace to prevent unintended interactions between them.

Enabling/disabling TOBO for all sales-users

The scenario previously described assumes there is a separate ToboOn permission for each sales-user in the system. A more sophisticated way to manage enabling and disabling TOBO would be to put all sales-users in a permissioning group, and define a permission at the group level that enables TOBO for all these sales-users. To then disable TOBO for an individual sales-user, you can define for that user a ToboOn permission that has Deny authorisation – this overrides the group level permission. Furthermore, you can disable TOBO for all sales-users by changing the group level ToboOn permission to Deny.

Using the %t substitution token

The %t substitution token can be used in the Product expression of a permission. It matches the username of the logged in user, or the username of any user that the logged in user can trade on behalf of, and is therefore intended for use in TOBO related permissions. The following example shows how %t is used in a permission, when a sales-user attempts to view a product on behalf of a customer-user. (Compare this to the simple example using %u shown in Using a substitution token in a permission.) Because the user is attempting to view a product, the default rule is applied. The following permission matches the default rule; it is for the action called VIEW in the default namespace:

Permission that applies

Action Product Namespace Authorisation
VIEW /PRIVATE/%t/FX/USDGBP   Allow

If sales-user Bob is authorised to trade on behalf of customer-users Steve and Alice, this permission applies to the following RTTP message subjects:

/PRIVATE/Bob/FX/USDGBP
/PRIVATE/Steve/FX/USDGBP
/PRIVATE/Alice/FX/USDGBP

Bob can therefore view USDGBP prices for himself, and on behalf of Steve and Alice. If Bob is not authorized to trade on behalf of Paul (that is, he cannot TOBO switch to Paul), Bob cannot view data with the subject:

/PRIVATE/Paul/FX/USDGBP

This is because the subject does not match the VIEW permission (the %t in the permission's Product string will never be replaced by the string "Paul"). Note that while the use of the %t token in permissions permits Bob to act on behalf of Steve and Alice, it does not permit Steve or Alice to act on behalf of Bob, nor does it permit Steve to act on behalf of Alice or vice-versa. For a user who is not permitted to trade on behalf of any other users, %t behaves like %u; it just matches the user’s Liberator login username.

A typical use-case

The %t token could be used in permissions to grant a sales-user access to a customer-user's trade history. This allows the sales-user to see the trade history data securely. Using %t also avoids having to explicitly grant the sales-user a separate VIEW permission for each customer-user.

Note: For the %t token to work, you must set the configuration properties ToboSwitchAction and ToboSwitchNamespace in the Permissioning Auth Module's javaauth.properties file.
Never use %t in the Subject Match definition of a permissioning Rule, or to map an object using object-map in the Liberator configuration. This is because Liberator does not recognise the %t token, and can only map objects for the logged in user and not the user they are trading on behalf of.
It is only the Permissioning Auth Module that recognises the %t token when it is placed in a product permission, where it matches the token to the logged in user, or to the user they are trading on behalf of.

See also: