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 graphical 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
• Step 2: Defining the roles and policies we want to create
• Step 3: Creating a feature policy for the US portfolio manager
• Step 4: Creating a data policy for the US portfolio manager
• Step 5: Creating a role for the US portfolio manager
• Step 6: Assigning the role to the US portfolio manager user
• Step 7: Composing roles and policies to aggregate responsibilities

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 either features 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:

User	Role	Policies
Data operator	data-operator	feature-write-all data-write-all
US portfolio manager	us-portfolio-manager	feature-read-portfolios-quotes-us data-read-portfolios-quotes-us
UK portfolio manager	uk-portfolio-manager	feature-read-portfolios-quotes-uk data-read-portfolios-quotes-uk
Global portfolio manager	us-portfolio-manager uk-portfolio-manager	feature-read-portfolios-quotes-us data-read-portfolios-quotes-us feature-read-portfolios-quotes-uk data-read-portfolios-quotes-uk
Risk manager	risk-manager	feature-read-all data-read-all

Step 3: Creating a feature policy for the US portfolio manager

Let's start with the US portfolio manager and the feature-read-portfolios-quotes-us feature 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 don't need access to API endpoints that add or update:

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 LUSID app:
   
6. Specify a unique Code for the policy:
   
7. Add features (corresponding to API endpoints) 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#operation/GetInstrument.
8. Use the Choose features wizard to move the endpoints you want from the left-hand to the right-hand column:
9. Create the policy:
   

You can view or edit the policy at any time from the Policies dashboard:

Step 4: Creating a data policy for the US portfolio manager

We now need to create an equivalent data-read-portfolios-quotes-us data policy that enables read-only access to the US portfolio's transaction and holding data, and to quotes.

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

1. On the Policies dashboard, click the Create policy button (top right).
2. Choose to create a policy using the Policy wizard.
3. This time, choose to create a Data policy for the LUSID app:
   
4. Specify a unique Code for the policy:
   
5. Specify the Scope (data partition) in which the US portfolio resides (note the default * value would signify every scope in LUSID):
6. Ensure the policy has read-only access just to the Portfolio and Quote resources within the scope:
7. Enter the Code of the US portfolio to restrict access to just this portfolio:
   
8. Allow access to any Quote stored in LUSID by retaining the default * 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:

Step 5: 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 that 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.

Note also that if you change the policies assigned to a role, these changes take effect immediately.

Step 6: 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 7: 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: