Complex Permissioning Rules

Simple permissioning rules are covered in permissioning concepts. This page looks at how to construct more complex permissioning rules:

Matching the RTTP message subject

Java regular expressions and Caplin substitution tokens can be used when you define a rule or permission. Java regular expressions can be used in the Subject Match expression of a rule, and in the Product expression of a permission. For example "/F." matches "/FT" and "/FI", since the "." metacharacter matches any single character.

You will find further information about Java regular expressions in the API documentation for the java.util.regex package, as supplied by Oracle® Corporation.

Substitution tokens can also be used in the Subject Match expression of a rule, and in the Product expression of a permission. They are used to prevent one user from accessing another user's data. The substitution tokens that are understood by the permissioning system are, %u, %U, and %t:

  • %u matches the username of the logged in user. For example, "/PRIVATE/%u/FX" matches "/PRIVATE/Bob/FX" if the user logged in as "Bob".
  • %U matches the session name allocated by Liberator for a user session. For example, "/PRIVATE/%U/FX" matches "/PRIVATE/Bob-0/FX" if the user's allocated session name is "Bob-0". A user can log in more than once, and is allocated a different session name each time they log in.
  • %t matches the username of the logged in user, or any user that the logged in user can trade on behalf of.  Its main use is to support permissioning for TOBO; see Using the %t substitution token in Permissioning for TOBO. 

If substitution tokens are used in the definition of rules or permissions, corresponding object mappings must also be set up in the Liberator configuration (see a description of object-map in the Liberator documentation here). Note: Only use %t in permission definitions (see Using the %t substitution token).

To place one of the literal values %u, %U, or %t in a regular expression, escape the string with a "\" like this: \%u, so that it is not interpreted as a substitution token.IFNOT PRINT,PDF

Using a substitution token in a rule

The following example shows an RTTP message that has a username ("Bob") in the subject of the message.

Message to /PRIVATE/Bob/FX/ONECLICK
Field Value
MsgType Execute
Side Buy
Amount 500000
Instrument /FX/GBPUSD

An example of a rule that matches this message is:

Rule
Field Value
Subject match /PRIVATE/%u/FX/ONECLICK
Field match criteria  
Product Reference field Instrument
Action ONE-CLICK
Namespace  

Because the matching rule contains the %u substitution token, the Permissioning Auth Module compares the username of the logged in user with the username in the requested subject.

If the logged in user is "Bob", the rule is applied and the permission defined for the action "ONE-CLICK" in the default namespace is checked to see if the request from Bob is to be allowed or denied. If the logged in user is "John" and not "Bob", the Permissioning Auth Module immediately denies the request.

Using a substitution token in a permission

The substitution tokens %u, %U, and %t can also be used when you define a permission. When a user attempts to view a product a default rule is implemented, and the permission that has been defined for "VIEW" action in the default namespace is checked to see if the interaction is to be allowed or denied. The following example shows a typical RTTP message for this type of request, in which the user attempts to view a product, and the username of the logged in user ("Bob") is in the subject of the message.

Message Subject
/PRIVATE/Bob/FX/USDGBP

Because the user is attempting to view a product, the default rule is implemented. An example of a permission that would apply to this type of request is shown below (it is for the VIEW action and is in the default namespace, so it matches the default rule).

Permission
Field Value
Action VIEW
Product /PRIVATE/%u/FX/USDGBP
Namespace  
Authorisation Allow

In this example, the Permissioning Auth module replaces the %u token in Product with the username of the logged in user, and compares this modified Product with the requested subject.

If the logged in user is "Bob", the modified Product in the permission is /PRIVATE/Bob/FX/USDGBP, which matches the requested subject, so the request from Bob is allowed, provided no other VIEW permissions with Deny authorization match the subject. If the logged in user is "John" and not "Bob", the modified Product in the permission does not match the requested subject, so it has no effect on the permission for the requested subject, as the request from "John" is neither allowed nor denied by this permission.

Substitution tokens are most effective when applied to permissions in Groups that multiple users inherit from. Without the token you would have to define a specific permission for each user, containing the user's name.

For information about using the %t substitution token in permissions, see Using the %t substitution token.

Field match criteria

A rule can have zero or more field-match criteria that map RTTP message fields and values. All field mappings described by field-match Criteria must be present in the RTTP message, otherwise the rule will not match the message.

In the example below, the rule will only match an RTTP message if the message field "Trading-Type" has the value "SPOT", and the message field "SIDE" has the value "Buy".

Rule
Field Value
Subject match /FT/TRADE
Field match criteria Trading-Type=SPOT,SIDE=Buy
Product reference field Instrument
Action spot trade
Namespace  

If the rule does not define any field-match criteria, then the RTTP message fields will be ignored when the rule is being matched to the message. You will notice from the above example that it is not necessary to include the "Instrument" value of Product Reference Field in the field-match criteria when you define the rule. Product matching is described in The product reference field below.

Refering session-metadata in field-match criteria

From version 7 of the Permissioning Auth Module, you can reference the StreamLink application ID and KeyMaster token values when specifying field-match criteria for a permissioning rule. These values are exposed as virtual fields. These virtual fields are not part of the RTTP message and can only be referenced in field-match criteria.

Virtual Field Description
*APPLICATION_ID

The StreamLink application identifier for the origin of the message. Match a rule against this field to restrict the scope of the rule to messages from a specific application.

For example, to grant users different permissions under FX Mobile than under FX Professional:

  1. Look up the identifiers of your applications in your Liberator licence file. In this example, the application IDs are 'fxmobile' and 'fxprofessional'.
  2. Write one or more rules that use the field-matching criterion: *APPLICATION_ID=fxmobile
  3. Write one or more rules that use the field-matching criterion: *APPLICATION_ID=fxprofessional
*KEYMASTER_TOKEN:key

The value of a mapping-data key included in the KeyMaster authentication token of a Liberator session. Match a rule against this field to restrict the scope of the rule to messages in sessions that have a specific value set at web-application login.

For example, to grant higher privileges to users who have authenticated using two-factor authentication, follow the steps below.

  1. Add new code to the KeyMaster servlet to store users' authentication levels in their credential tokens (see com.caplin.keymaster.IAuthenticator.setMappingData). This example uses a key named 'AUTHENTICATION_LEVEL' and the values '1FA' and '2FA' for users who authenticate using one-factor authentication and two-factor authentication respectively.
  2. Write one or more rules that include the following field-matching criterion: *KEYMASTER_TOKEN:AUTHENTICATION_LEVEL=2FA

The product reference field

The Product Reference field of a rule identifies the field in the RTTP message that contains the name of the product. If the rule matches the message, the permission for the identified product is checked to see if the action is allowed or denied (see Permissions).

Matching all products

The Product Reference Field can be given the special value "ALL_PRODUCTS" (equivalent to the Java regular expression ".*"), in which case all product permissions for the action are checked to see if the action is allowed or denied.  We will now look at an example RTTP message and a matching rule that uses this special value.

Message to /FX/ONECLICK
Field Value
MsgType Execute
Side Buy
Amount 500000
Instrument /FX/USDGBP

An example of a rule that matches this type of trade is shown below:

Rule
Field Value
Subject match /FX/ONECLICK
Field match criteria  
Product reference field ALL_PRODUCTS
Action ONE-CLICK
Namespace  

In this case all product permissions for "ONE-CLICK" action in the default namespace are checked to see if the user is to be allowed or denied access. If any of these permissions deny "ONE-CLICK" action, access to "/FX/EURGBP" is denied. An example of a permission that applies to this type of trade is shown below.

Permission
Field Value
Action ONE-CLICK
Product /FX/EURGBP
Namespace  
Authorisation ALLOW

Although this permission is for "/FX/EURGBP", it also applies to "/FX/USDGBP", since the rule specifies that all product permissions for "ONE-CLICK" action in the default (undefined) namespace must be checked to see if the action is allowed or denied.

Using Java regular expressions

The Product Reference Field can be a Java regular expression, in which case every field of the RTTP message that matches the regular expression will be considered to contain the name of a product. Java regular expressions can be used to define rules for multi-leg trading, as shown in the following example.

Message to /TRADE/FX
Field Value
L1_ /FX/GBPUSD
L2_ /FX/USDJPY

An example of a rule that would match this type of trade is shown below.

Rule
Field Value
Subject match /TRADE/FX
Field match criteria  
Product Reference Field L\d_
Action TRADE
Namespace TRADER

The "\d" in the regular expression of the Product Reference Field will match any digit. In this case the permission that has been defined for the "TRADE" action in the "TRADER" namespace will be checked to see if the user is to be allowed or denied access to the products identified by fields "L1_" and "L2_". An example of the permissions that would apply to this type of multi-leg trade is shown below.

Permissions
Action Product Namespace Authorisation
TRADE /FX/GBPUSD TRADER Allow
TRADE /FX/USDJPY TRADER Allow

In this case "TRADE" action on the products "/FX/GBPUSD" and "/FX/USDJPY" will be allowed, since the rule states that the permission applies to each of these products. If the user did not have "Allow" permission for each of these products, then the multi-leg trade would be denied.

The action reference field

We have already looked at how you can define the action for a rule in the Action field of the rule. Rules can also be defined that derive the action from a field in the RTTP message. In the following example, we look at a rule that uses the Action Reference Field to identify the field of the RTTP message that defines the action.

Message to /TRADE/FX
Field Value
Tenor 1month
Trading-Type RFQ
Instrument /FX/GBPUSD

An example of a rule that would match this type of trade is shown below.

Rule
Field Value
Subject match /.*
Field match criteria  
Product reference field Instrument
Action  
Action reference field Tenor
Namespace TenorPermissions

The rule matches since the subject of the RTTP message is "/TRADE/FX", which matches the regular expression "/.*" in the Subject Match field of the rule. An example of the permission that would apply to this type of trade is shown below.

Permission
Field Value
Action 1Month
Product .*
Namespace TenorPermissions
Authorisation Allow

In this case "RFQ" trading with a tenor of one month will be allowed. The permission matches because:

  • The Action Reference Field of the rule identifies "Tenor" as the RTTP field that defines the action.
  • The "Tenor" field of the RTTP message has the value "1Month".
  • The permission allows "1Month" action for all products in the "TenorPermissions" namespace.

See also: