Permissioning for TOBO

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

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.

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.

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.

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:

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:

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

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:

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:

The corresponding permission that allows the TOBO switch is:

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.

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":

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

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

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

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.

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:

The rule that matches this trade message is:

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

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

The same rule matches this trade message as did previously:

The permission applying to Alice that this rule matches is:

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:

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.

Follow the guidelines below when using the ALL_ACTIONS action name:

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.

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

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:

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 %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:

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:

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:

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.