Writing a permissioning adapter

In this tutorial you will create a permissioning integration adapter that defines a number of users. Each of the users will have a different set of permissions – starting with the admin user who has permission to request anything, and leading on to other users who have specifically organised permissions for subscribing to certain sets of data and being able to trade on others.

You will also create groups of users so that multiple users can share the same permissions (which are associated with the group).

Caplin’s Permissioning Auth Module (PAM) is packaged as the Caplin Permissioning Service, available as a separate download to Liberator.

The default auth module for Liberator is openauth, packaged in the OpenPermissioning blade. The openauth module accepts all connections and is non-configurable. It is not used in production systems.

To complete this tutorial, you will deactivate the OpenPermissioning blade and deploy the PermissioningService blade.

The Permissioning Auth Module does not accept unauthenticated connections and the default level of authorisation is deny. After enabling the PermissioningService blade, all requests will be rejected by Liberator until you supply permissioning configuration to the PAM via a permissioning adapter.

Follow the steps below to deploy the Permissioning Service:

See Download Caplin’s training project in the Writing a pricing adapter (1) tutorial.

Create a new adapter project based on the Permissioning Adapter example.

Follow the steps below:

Follow the instructions for your IDE below.

After you have created the project, perform the following tasks. Refer to the Writing a pricing adapter (1) for help.

The new PermissioningAdapter project contains the entry point class PermissioningAdapter and a PermissioningAdapterPermissioningProvider class that does the work.

The constructor of the PermissioningAdapterPermissioningProvider class creates a PermissioningDataSource object. This object is the one which you use to manage all the users and their permissions. All permission updates are propagated to the Permissioning Auth Module (PAM) in Liberator by means of a "transaction". The PermissioningDataSource object can be used to start a new transaction, add permissions to the transaction, and then commit the transaction so that the permissions are sent to the PAM. It is only when you commit the transaction that the permissions are sent to Liberator.

There are two types of transactions for sending permissions to the PAM. An image transaction (startImageTransaction() method) will clean any permissions you have previously set and add the new ones which are described inside the transaction. If you don’t want to clear everything, you can use an update transaction (startUpdateTransaction() method). Never forget the commitTransaction() method. You can also use the rollbackTransaction() method if you catch an exception while executing the transaction.

After starting a transaction, you can use the PermissioningDataSource methods createUser() or createGroup() to create a new user or group respectively. Then use user/group.applyPermission() to define permissions for that user or group before committing the transaction.

The first user you will configure is the administrator who should have permission to see all data and trade on any data.

Follow the steps below:

Now that the admin user exists and is able to login to Liberator, we will give that user permission to subscribe to streaming data.

Follow the steps below:

View permissions are the simplest permissions you can create. They are simply defined by the action "VIEW" and a regular expression that must match the requested subject. The namespace is not important.

In this case we have provided the regular expression /.*, which will allow the user to subscribe to any subject that begins with a forward slash character. Later in the tutorial we will see what happens if we provide a more restrictive pattern, so that users can subscribe to some subjects but not others.

Now we are going to create some trading permissions for the admin user. This is a bit more complicated than simple view permissions. First we have to create a rule that tells Liberator how to identify which incoming trade messages represent an ESP trade. Then we assign the admin user a permission that allows them to perform ESP trades on certain currency pairs.

Action rules and permissions make extensive use of regular expressions. The Caplin Permissioning Service uses the standard Java regular expression engine, java.util.regex.Pattern. For more information on the syntax supported by this engine, see the Java 8 documentation for java.util.regex.Pattern.

Follow the steps below:

Our test page sends the Open trade message with several fields, among them are:

Every time Liberator receives a message from a client, the PAM checks all of the rules to determine what type of action this is. It does this based on the subject and the fields in the message. In this example, we have defined a rule that says if the message is on the trade channel subject and contains the field TradingProtocol with the value 'ESP', then the action is FX-ESP-TRADE. The final part of the rule definition is the field on the message containing the name of the product on which the action is performed. In this case it is the Instrument field.

Having found the rule(s) that match the message, the PAM then checks that the user who sent the message permission to perform this action. In this example, the admin user has a permission that allows him to perform the FX-ESP-TRADE action on any product with a name matching the regular expression /.*. Since the value in the Instrument field will always match the pattern /.*, Liberator will allow this trade message to go through to the adapter.

If you restart the adapter and try to trade again from the test page, your trade should now be successful.

Now that we’ve got the basics set up, let’s create some more fine-grained permissions. The aim in this section is to define a new user, user1, who will be allowed to view all the GBP currency pairs available on the Pricing Integration Adapter (e.g. /FX/GBPUSD) but not any other currency pairs (e.g. /FX/EURUSD). Additionally, we will demonstrate simple inheritance by applying these permissions to a group and adding user1 to the group so that it will inherit the group’s permissions.

Follow the steps below:

In some cases, you may not want all group members to inherit all of the group’s permissions. For example, you have created a group that allows trading in all currency pairs, but you want to prohibit a subset of the group’s members from trading in the more volatile currency pairs.

You can restrict the permissions that a member inherits from a group by applying DENY permissions at member-level that override the ALLOW permissions of the group.

You are going to add a new user, user2, to the GBPGroup group that you just created. This user, however, will not have permission to view one specific currency pair: GBPUSD.

Follow the steps below:

A user can be a part of more than one group. When this is the case, the user inherits the permissions associated with both groups. In this scenario there may be clashing permissions, i.e. ALLOW and DENY permissions on the same instruments. If this is the case, the DENY permission is always the one that is applied.

You are going to create two new groups, EURGroup1 and EURGroup2, and a new user, user3, who is a member of both groups. Some of the permissions associated with the groups will clash. No code example this time, but you should be able to complete the task based on the examples above.

Follow the steps below:

Finally, we are going to create a new user that will be used in the Caplin Trader tutorials to follow (where you will create a simple trading application, including a trade tile, that connects to the backend that you created in this first set of tutorials). These permissions will be used to demonstrate the frontend permission API.

The user, called 'demouser', can:

Answers to common questions:

Having completed this tutorial you should now have understood how to use the PermissioningDataSource to create users and groups and how to assign permissions to the group. Also remember that you can define your own actions like you did for the FX-ESP-TRADE action. In reality it may be necessary to connect to a server providing permission data, interpret this data, and translate it into permission transactions.