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.

RTTP Message

Message Subject Message Fields
MsgType Side Amount Instrument
/PRIVATE/Bob/FX/ONECLICK Execute Buy 500000 /FX/GBPUSD

An example of a rule that matches this request is:

Matching rule

Subject Match Field Match Criteria Product Reference Field Action Namespace
/PRIVATE/%u/FX/ONECLICK   Instrument ONE-CLICK  

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).

Action Product Namespace Authorisation
VIEW /PRIVATE/%u/FX/USDGBP   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".

Example rule

Subject Match Field Match Criteria Product Reference Field Action Namespace
/FT/TRADE Trading-Type=SPOT,
SIDE=Buy
Instrument spot trade  

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.

RTTP Message

  MsgType SIDE Amount Instrument
/FX/ONECLICK Execute Buy 500000 /FX/USDGBP

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

Matching rule

Subject Match Field Match Criteria Product Reference Field Action Namespace
/FX/ONECLICK   ALL_PRODUCTS ONE-CLICK  

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 that would apply

Action Product Namespace Authorisation
ONE-CLICK /FX/EURGBP   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.

RTTP Message

Message Subject Message Fields
L1_ L2_    
/TRADE/FX /FX/GBPUSD /FX/USDJPY    

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

Matching rule

Subject Match Field Match Criteria Product Reference Field Action Namespace
/TRADE/FX   L\d_ TRADE 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 that would apply

Action Product Namespace Authorisation
TRADE /FX/GBPUSD TRADER Allow
TRADE /FX/GBPUSD 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.

RTTP Message

Message Subject Message Fields
Tenor Trading-Type Instrument
/TRADE/FX 1Month RFQ /FX/GBPUSD

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

Matching rule

Subject Match Field Match Criteria Product Reference Field Action Action Reference Field Namespace
/.*   Instrument   Tenor 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.

Permissions that would apply

Action Product Namespace Authorisation
1Month .* TenorPermissions 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: