Setting up basic access control for different LUSID users

In this tutorial we'll see how to set up roles and policies for different LUSID users at a fictional investment management company.

The goal is to give them exactly the permissions they need to perform their professional responsibilities, and no more.

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 fictional users are:

• A data controller. This user needs write access to all the data in LUSID.

• 3 x portfolio managers. These users need to see transactions, calculate holdings and review quotes, but not change any data. The US portfolio manager should have read-only access to the US fund, the UK portfolio manager should have read-only access to the UK fund, and the global portfolio manager should have read-only access to both.

• A risk manager. This user needs to have read-only access to all the data in LUSID.

This tutorial assumes these fictional users already exist in LUSID. See how to onboard users.

Note

Once onboarded, users can interact with LUSID either via the web app or by calling the API directly; the access control system makes no distinction between these two workflows.

Step 1: Understanding access control in LUSID

LUSID's powerful role-based access management system consists of users, roles, policies and policy collections. In summary:

Note that an individual policy manages access to features and/or data:

• A feature policy controls access to API endpoints. This is irrespective of whether a user ultimately interacts with LUSID via the graphical web app or by calling the API directly (since the web app itself calls the API).

• A data policy controls access to entity datasets. An entity in LUSID is a portfolio, quote or similar repository of a particular category of data.

To perform any real-world operation in LUSID, a user must be assigned both types of policy. This is because a data policy without an equivalent feature policy cannot perform operations, and a feature policy without an equivalent data policy yields no data.

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

For our fictional investment company, we need the following:

Step 3: Creating a policy for the US portfolio manager

Let's start with the US portfolio manager and the feature-data-read-portfolios-quotes-us policy.

Note

We'll create this policy using the LUSID graphical web app, but it could equally be created by calling the Access API directly.

This person requires all the API endpoints that perform read-only operations such as get and list on the US portfolio and on quotes. They also need read-only access to the US portfolio’s transaction and holding data, and to quotes. They don't need access to API endpoints that add or update.

Note in our example the US portfolio is uniquely identified by the (fictional) us-equities-trading code within the access-control-tutorial scope.

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.
   

4. Specify a unique Code for the policy:
   

5. On the Features tab, select features (corresponding to API endpoints) to add to the policy. Selecting precisely which API endpoints is subjective, but a read-only set of portfolio and quote-related endpoints for our US portfolio manager might be:
   GetValuation, GetInstrument, GetInstruments, ListInstruments, GetPortfolio, ListPortfolios, GetQuotes, ListQuotes, InstrumentsSearch, SearchPortfolios, GetTransactions, GetHoldings, GetDetails
   For a complete list of endpoints, see the API specification. The identifier for an endpoint is its operation ID, so for example GetInstrument equates to https://www.lusid.com/docs/api/lusid/endpoints/instruments/GetInstrument/

6. Click Next to reach the Data Resources tab. Select the relevant checkboxes to provide read-only access to the Portfolio and Quote resources.
   

7. For Portfolio, select Identifier as the Selector and specify the Scope (data partition) and Code of the US portfolio to restrict access to just this portfolio:
   

8. For Quote, allow access to any quote stored in LUSID by selecting Identifier as the Selector and specifying * values. Note you could restrict quote access by specifying appropriate values for any of the following categories:
   

9. Create the policy:
   

The US portfolio manager now has a suitable feature and data policy, ready to assign to their role.

Exercise

Can you create the other policies in the table from step 2?

Step 4: Creating a role for the US portfolio manager

Now we need to create a suitable role, since policies are assigned to roles rather than directly to users. A role should represent an aspect of that user's professional responsibilities; you can divide these responsibilities into one or many roles, depending on your needs.

We'll create a single us-portfolio-manager role for this user, encompassing their entire responsibilities:

1. Navigate to the Roles dashboard:
   

2. Click the Create role button (top right).

3. Specify a unique Code for the role, and then select the appropriate policies to assign from the Policies > Choose dropdown:
   

4. Create the role.

Note:

• Roles have a precedence, so if you do assign two roles to a person and those roles contain conflicting policies, the role with the highest precedence takes effect.

• If you change the policies assigned to a role, these changes take effect immediately.

Exercise

Can you create the other roles in the table from step 2?

Step 5: Assigning the role to the US portfolio manager user

The last step is to assign the us-portfolio-manager role to the LUSID user representing this person. To do this:

1. Navigate to the Users dashboard, find the appropriate user and click the Edit icon:
   

2. Select the appropriate role to assign to the user from the Roles > Choose dropdown, for example:
   

Note that if you change the roles assigned to a user, these changes take effect the next time that user logs in (not immediately).

Step 6: Composing roles and policies to aggregate responsibilities

When it comes to the global portfolio manager, there's no need to create distinct roles and policies. Since this person simply requires an aggregation of the responsibilities of the US and UK portfolio managers, it is sufficient to assign both those roles to that person: