As well as writing policies that control access to entities in LUSID (such as portfolios and transactions), you can also write policies that restrict access to the properties you have added to those entities.
All property access checks are based on the property key, which has three parts: a domain, scope and code. This means that you can write policies to allow users to, for example, "read any properties in the scope X with an effective date starting from 1st July 2020". A record of all access checks performed in LUSID, including those for properties, is available via the Insights system.
With the property value access control feature enabled, an access check will be performed whenever a property is retrieved, edited or deleted, to check whether the user is permitted to perform that action. This means that even if a user has access to an entity, they may not have access to all the properties attached to that entity, unless access has been granted.
Property type and property value activities
To create a property, a property type must be specified with the property key. Property types specify what the property key is, and any criteria the property should conform to, such as whether it is a label or a metric property, or if it should be restricted to certain values. Property values are the values of that property when attached to a specific entity.
Via policies, you can control access to what activities (e.g. read, update, delete etc.) a user can perform on both the property type and the property value. The activities are summarised below:
Property definitions
These policies have actions with three parts: a scope (“default”), entity (“PropertyDefinition”), and activity. The activities for Property Definitions are:
- Add
- Read
- List
- Update
- Delete
- Any (all of the above)
Property value activities
These policies have actions with three parts: a scope (“default”), an entity (“PropertyValue”), and an activity. The activities for property values are:
- Read
- Update
- Delete
- Any (all of the above)
Controlling access to property values
As most interactions with properties require the property definition, you should grant Read access to the property definition alongside granting access to the property value. We have provided an example:
- Suppose we are creating a new property in the Portfolio domain, with the scope "Blue" and the code "Manager".
- Firstly, a property definition must be specified. Doing this will require the user to have a policy allowing them to Add a property definition. Let's say that the key for our new property is Portfolio/Blue/Manager. We can specify other things in the property definition, such as the fact that it is a label property.
- Now we can start adding this property to our portfolios. For the property key of "Portfolio/Blue/Manager", Portfolio1 may have the value "John Smith", and Portfolio 2 may have the value "Jane Jones".
- To be able to view, edit or remove the value of "John Smith" on Portfolio1 or "Jane Jones" on Portfolio 2, the user will require policies allowing them to Read, Update or Delete the property value, based on its property key and the effective and as-at timeframes. They will also need "Read" access to the property definition for Portfolio/Blue/Manager.
We have summarised some common use cases a user may have, and what permissions would need to be granted to enable them.
Getting Properties
To get a property value attached to an entity, the user must have property value Read access to the property's key, in the relevant effective and as-at dates.
Updating or Adding Properties
To add a property to an entity, or to update the value of an existing property, the user must have property value Update and Read access to the property's key, in the relevant effective and as-at dates.
Deleting Properties
To remove a property from an entity, the user must have property value Delete and Read access to the property's key, in the relevant effective and as-at dates.
Updating Entities with Properties
When using an endpoint that allows for "upserting" a new version of an entity, the user must have property value Update and Read access to all the properties included in the latest version of the entity.
If the entity being updated is an entity with a unique identifier (this is every type of entity except Holdings and Transaction Type Definitions), the new entity will also be compared with the previous version of the entity. Depending on the entity type, any properties omitted in the updated version will either be copied over or deleted. If deleted, the user will require Property Value Delete access to the property keys.
Deleting an Entity with Properties
When deleting an entity, the user does not require permission to delete the individual properties on that entity.
Derived Properties
Derived properties cannot be created or deleted, since they are simply calculated when reading. To read the value of a derived property on an entity, a user will need Read access for the derived property, as well as for any properties that it is derived from.
Property Time Series
To be able to retrieve the time history of a property's value, the user must have property value Read access for the entire duration of the time requested, specified in a single policy.
What happens if a user does not have access to properties?
This depends on the action they are trying to perform.
For API calls where properties are not specified, such as listing all the properties on a transaction, the user will get a set of properties that is limited to those they can view.
If the user is specifying the property key in some way – for example, trying to get a list of portfolios with properties they do not have access to, or filtering on a certain property - they will receive a failure message that explains which property (or properties) they are not permitted to perform the action on.