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 are used in the Subject Match expression of a rule and in the Product expression of a permission.

The Permissioning Service extends Java regular expression syntax with three extensions: the substitution tokens %u, %U, and %t. Substitution tokens are used to prevent one user from accessing another user’s data.

The Permissioning Service precompiles substitution tokens to regular expression capture groups of the form (.*). The capture groups must capture the value denoted by the original token for the expression to match a given string.

The Permissioning service recognises three substitution tokens:

  • %u denotes a capture group that must capture the current user’s user name. For example, if the current user is 'bob', then the expression /PRIVATE/%u/FX (which pre-compiles to /PRIVATE/(.*)/FX) matches the subject '/PRIVATE/bob/FX' but not the subject '/PRIVATE/alice/FX'.

  • %U denotes a capture group that must capture the current session’s session name. For example, if the current session name is 'bob-0', then the expression /PRIVATE/%U/FX (which pre-compiles to /PRIVATE/(.*)/FX) matches the subject '/PRIVATE/bob-0/FX' but not the subject '/PRIVATE/alice-0/FX'.

  • %t denotes a capture group that must capture the current user’s user name or any user the current user can trade on behalf of (TOBO). For example, if the current user is 'bob', and he has permission to trade on behalf of 'carol' but not 'alice', then the expression /PRIVATE/%t/FX/USDGBP (which pre-compiles to /PRIVATE/(.*)/FX/USDGBP) matches '/PRIVATE/bob/FX/USDGBP' and '/PRIVATE/carol/FX/USDGBP', but not '/PRIVATE/alice/FX/USDGBP'.

    The %t token can only be used in the Product expression of a permission. 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).

If you need to include %u, %U, or %t as literal values rather than as substitution tokens, escape each string with a \ like this: \%u.

Do not directly precede a substitution token with .*, such as .*%U. Because substitution tokens precompile to capture groups in the form (.*), writing .*%U will precompile to .*(.*). In that form, the capture group cannot logically capture any content and the expression will always fail.

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.

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