Creating policies to control access to providers for different Luminesce end users

In this tutorial we'll see how to set up access control for different Luminesce end users so they can write Luminesce SQL queries for particular providers.

The goal is to create policies that grant permission to use just those providers that enable them to perform their professional responsibilities, and no more. Note that without a suitable policy granting access, no provider is available to query.

Note: To complete this tutorial, you must yourself have suitable permissions. This can most easily be achieved by assigning your LUSID user the built-in lusid-administrator role. This should already be the case if you are the domain owner.

The Luminesce end users in our scenario are:

• A Portfolio Manager who needs to write queries for providers to upsert transactions into LUSID and calculate holdings.
• An Administrator who needs to write queries for providers to analyse LUSID logs and administer the Luminesce system.
• A Data Loader who needs to write queries for providers to read data from, and write data to, files stored in Drive.

For a general introduction to providers and all the other components in the Luminesce platform, see this guide to the architecture.

• Step 1: Understanding access control in Luminesce (and LUSID)
• Step 2: Defining the roles and policies we want to create
• Step 3: Assembling a list of providers for each user
• Step 4: Creating a policy for the Portfolio Manager using the LUSID web app
• Step 5: Assigning the policy to a role and user in the LUSID web app
• Step 6: Confirming the user has the correct provider access

Step 1: Understanding access control in Luminesce (and LUSID)

Every Luminesce end user must have a LUSID user account. See how to onboard users into LUSID.

Every LUSID user must have at least one role, and every role must have at least one policy granting appropriate permissions. Without a role and a policy, a user has no access rights at all. In summary:

Note: In this tutorial, we are creating policies that enable end users to write queries for providers supplied by FINBOURNE to access investment data in LUSID and files in Drive. Note that, to actually observe results returned by these providers, end users also require separate data policies granting permission to see LUSID and Drive data (otherwise, queries execute but no data is returned). To learn how to create data policies, and for information on identity and access management (IAM) in LUSID in general, see our IAM documentation.

Step 2: Defining the roles and policies we want to create

For our Luminesce end users, we'll create the following roles and policies:

End user	Role	Policy
Portfolio Manager	luminesce-lusid-portfolio-manager	luminesce-lusid-provider-policy
Administrator	luminesce-admin	luminesce-sys-tools-lusidlogs-provider-policy
Data Loader	luminesce-drive-operator	luminesce-drive-provider-policy

Step 3: Assembling a list of providers for each end user

A provider performs a particular operation (read, write or analyse) on a particular data source. We supply providers for:

• All the different entities representing investment data stored in LUSID (instruments, portfolios, transactions and so on). See a list of LUSID providers.
• Files stored in Drive. See a list of Drive providers.
• System information about LUSID, such as logs, scopes and property types. See a list.
• Core information about the Luminesce platform itself.

Note: You can also create your own providers for your own data sources. You would then create access control policies for these custom providers in exactly the same way.

You must grant an end user explicit access to each provider they need to write queries for. In addition, you should grant each end user access to the core Sys.Field, Sys.Registration and Sys.Service providers, to enable participation on the Luminesce platform.

End user	Core providers	Additional providers in our scenario
Portfolio Manager	Sys.Field, Sys.Registration, Sys.Service	Lusid.Portfolio, Lusid.Portfolio.Txn.Writer, Lusid.Portfolio.Holding
Administrator		Lusid.Logs.*, Sys.Admin.File.SaveAs, Sys.File, Tools.*
Data Loader		Drive.*

Step 4: Creating a policy for the Portfolio Manager using the LUSID web app

The easiest way to create a single policy is to use the LUSID web app GUI. As an alternative, note it is possible to create policies by running a Luminesce SQL query, which might be better suited to bulk policy creation. See how to do this.

1. Sign in to the LUSID web app using the credentials of a LUSID administrator.
2. From the left-hand menu, select Identity and access > Policies:
   
3. On the Policies dashboard, click the Create policy button (top right).
4. Choose to create a policy using the Policy wizard:
   
5. Choose to create a Features policy for the Luminesce application:
   
6. Specify a unique Code for the policy:
   
7. Click the Add feature button to open the Choose features wizard and select appropriate providers by moving them from the left-hand to the right-hand column:
   
8. Create the policy:
   

Step 5: Assigning the policy to a role and user in the LUSID web app

We'll use the LUSID web app to assign the policy to a role and the role to a user, but as an alternative it is possible to perform these operations using a combination of the Access and Identity APIs.

1. Navigate to the Roles dashboard and click the Create role button (top right).
2. Specify a unique Code for the role and assign the policy from the Policies > Choose dropdown:
   
3. Navigate to the Users dashboard, find the appropriate user row and click the  Edit icon.
4. Click the Add roles button to assign the role to the user and then click the Save button:
   

Step 6: Confirming the user has the correct provider access

Ask the user to sign in to the LUSID web app and navigate to the Data virtualisation > Query editor dashboard:

The Available catalogues area on the right should list all the providers the user has permission to write queries for: 

Appendix A: Running a Luminesce SQL query to create a policy

It's possible to write and execute Luminesce query to create a policy in JSON form. This is an alternative to using the LUSID web app.

1. Specify a comma-separated list of providers on line 5 in the query below, enclosing each provider in single quotes. For example, to create a suitable policy for the Portfolio Manager user in Step 3:
   @providersToInclude =
   select distinct name from Sys.Registration
   where type like '%Provider' and
   (
       name in ('Lusid.Portfolio', 'Lusid.Portfolio.Txn.Writer', 'Lusid.Portfolio.Holding')
   )
   or name in ('Sys.Field', 'Sys.Registration', 'Sys.Service')
   order by 1;
   
   @@selectors = select
       GROUP_CONCAT
           (
           '
           {
               "idSelectorDefinition": {
                   "identifier": {
                       "code": "' || name || '",
                       "scope": "Honeycomb"
                   },
                   "actions": [
                       {
                           "scope": "Honeycomb",
                           "activity": "Execute",
                           "entity": "Feature"
                       }
                   ],
                   "name": "Run ' || name || '",
                   "description": "Run the ' || name || ' provider"
               }
           }',
           ','
           ) as selectors
   from @providersToInclude;
   
   select '
   {
       "description": "Grant permission to use particular providers",
       "applications": [
           "Honeycomb"
       ],
       "grant": "Allow",
       "selectors": [
       ' || @@selectors || '
       ],
       "when": {
           "activate": "2021-09-15T09:47:23.4550399+00:00",
           "deactivate": "9999-12-31T23:59:59.9999999+00:00"
       }
   }
   '
2. Optionally, change the valid from and to dates for the policy (the activate and deactivate values at the bottom).
3. Run the query using a suitable tool, for example the LUSID web app. 
4. Copy the query results, which should consist of a JSON string encapsulating the policy.
5. In the LUSID web app, follow these instructions to create the policy.

To define a suitable policy for the Administrator user, you could change line 5 of the query to specify:

To define a policy for the Data Loader user that grants access to all the Drive providers except the ability to read from Excel files (and to demonstrate that any SQL filter expression is valid here), change line 5 to specify: