Setting up access control for different Drive users

In this tutorial we'll see how to set up access control for different LUSID users so they can operate Drive.

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

• An Administrator who needs to upload, edit and delete files, and organise folders.
• An Operator who just needs to see a list of available files and download them on an ad hoc basis.

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

Note: Once permissioned, users can interact with Drive either via the LUSID 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 Operator
• Step 4: Creating a data policy for the Operator
• Step 5: Creating a website policy for the Operator
• Step 6: Creating a role for the Operator
• Step 7: Assigning the role to the Operator user
• Step 8: Helping users get started

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 Drive API endpoints. This is irrespective of whether a user ultimately interacts with Drive via the LUSID web app or by calling the API directly (since the web app itself calls the API).
• A data policy controls access to information about files and folders.

To perform any real-world operation in Drive, 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.

For much more on identity and access management (IAM) in the LUSID platform, see our IAM documentation.

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

For our users, we need the following:

Step 3: Creating a feature policy for the Operator

Let's start with the Operator and the drive-features-files-download feature policy.

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

The Operator requires access to Drive API endpoints that list files and download them. They don't need access to API endpoints that upload or edit files or create folders:

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 Drive application:
   
6. Specify a unique Code for the policy:
   
7. Click the Add feature button to open the Choose features wizard and select appropriate API endpoints by moving them from the left-hand to the right-hand column:
   
   Selecting precisely which API endpoints is subjective, but to enable the Operator to list files and download them, you might choose:
   
   DownloadFile, GetFile, GetFolder, GetFolderContents, GetRootFolder
   
   Note: For the Administrator, it would be reasonable to select all API endpoints.
   
   API endpoints are identified in the left hand column of this dialog by their operation ID. Examine the Swagger specification for more information on each endpoint; the operation ID is listed in the documentation title:
   
8. Create the policy:
   

Step 4: Creating a data policy for the Operator

We now need to create an equivalent drive-data-files-download data policy that grants the Operator read-only access to information about files.

1. On the Policies dashboard, click the Create policy button again.
2. Choose to create a policy using the Policy wizard.
3. This time, choose to create a Data policy for the Drive application:
   
4. Specify a unique Code for the policy:
   
5. Choose Selected resource types and both File and Folder to allow the Operator to see all files in the root folder and in subfolders. But select just the Read and List actions to prevent the Operator uploading or editing files:
   
   Note: For the Administrator, it would be reasonable to retain the default All resources option, which grants read-write access.
6. Click the Add identifier button for files and accept the default value of * for both File path and File name to grant access to any file in any folder in Drive:
   
   If you wanted, you could restrict access to just a particular file, or files in particular folders, by specifying appropriate values. Note this dialog accept wildcards:
   • * matches all
   • *.txt matches all files with that extension
   • secret* matches all file beginning secret...
   So for example you could specify a File path of /Instruments and a File name of trade* to restrict the Operator to seeing just files with names beginning trade... in folders named Instruments.
7. Click the Add identifier button for folders and accept the default value of * for both File path and File name to grant access to the root folder and any subfolder:
   
   If you wanted, you could restrict access to just a particular folder(s) by specifying appropriate values. Note this dialog accept wildcards:
   • * matches all
   • /* matches the root folder and any subfolder
   • /Marketing matches a folder named Marketing under the root folder
   • /Operation* matches a folder named Operation under the root folder and any subfolder.
8. Create the policy:
   

Step 5: Creating a website policy for the Operator

There's a special policy we need to create for any user who intends to interact with Drive using the LUSID web app.

Note: You can skip this step if your users will only interact with Drive by calling the Drive API.

This policy enables access to the Data Management > Drive menu. Without it, the Drive menu option is not visible, and the user cannot navigate to the Drive dashboard:

The policy is the same for every user. Copy the following JSON document and follow these instructions to create the policy:

{
    "description": "Allow access to the Data Management > Drive menu option",
    "applications": [
        "Website"
    ],
    "grant": "Allow",
    "selectors": [
        {
            "idSelectorDefinition": {
                "identifier": {
                    "code": "drive",
                    "scope": "data-management"
                },
                "actions": [
                    {
                        "scope": "default",
                        "activity": "view",
                        "entity": "data-management"
                    }
                ]
            }
        }
    ],
    "when": {
        "activate": "2020-07-15T22:00:00+00:00",
        "deactivate": "9999-12-31T23:59:59.9999999+00:00"
    }
}

The Operator now has matching feature and data policies, and the special website policy to allow UI access, ready to assign to their role:

Step 6: Creating a role for the Operator

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 drive-operator 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 assign the appropriate policies 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.

Step 7: Assigning the role to the Operator user

The last step is to assign the drive-operator role to the LUSID user representing this person. To do this:

1. Navigate to the Users dashboard, find the appropriate user row, and click its  Edit icon:
2. Click the Add roles button to assign the appropriate role to the user:
   

Helping users get started

The Operator can now interact with the LUSID web app straight away. Tell this person to navigate to your LUSID domain (for example https://acme.lusid.com/app) and sign in using their own account credentials.

This person should be able to navigate to the Data Management > Drive dashboard, see files and download them. Other operations will not be available:

To interact with Drive programmatically:

• Using the Drive REST API, tell the Operator to first follow these instructions to obtain an API access token. Note the Drive Swagger specification hosts a pre-authenticated Try it out facility; tell the Operator to navigate to https://<your-domain>.lusid.com/drive/swagger/index.html and click the button for an appropriate API endpoint:
  
• Using either the Drive Python or C# SDK, tell the Operator to first follow these instructions to assemble credentials and pass them securely into the appropriate SDK.