How do I create a data policy?

Providing you are a LUSID user with sufficient privileges, you can create a data policy to restrict access to one or more entity datasets.

Note

If you are the LUSID domain owner, you are automatically assigned the built-in lusid-administrator role, which has all the permissions necessary to perform the operations in this article.

An entity in LUSID is a portfolio, quote or similar repository of LUSID data. Note not all entities support every access check LUSID is capable of making. Note also that a data policy requires an equivalent feature policy in order for appropriate API endpoints to be called to perform operations on that data.

When creating a data policy, note that in addition to nominating entity dataset(s) you also specify actions the user can perform:

Note

The table above does not list every available action a user can perform across all the applications in the FINBOURNE platform. The easiest way to explore all the available actions for a particular entity is through the Data Resources tab when creating a policy in the LUSID web app.

Once created, you should assign the policy to a role.

Using the LUSID web app

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 Policy code, Policy validity dates if necessary, and select whether the policy should Allow or Deny access to the data specified:
   

5. Optionally, select any features you want the policy to cover.

6. Click Next to reach the Data Resources tab.

7. Add Actions to the policy. For example, to allow write access to portfolio data:
   

8. Choose a Selector type from the following options to nominate a data partition to restrict the policy to:

   • Identifier allows you to specify a Scope and Code pair to restrict the policy to. Note the * value applies the policy to every code within the specified scope.

   • MetadataExpression allows you to restrict the policy based on an access metadata expression. Read more.

   • Match all applies the policy to every scope in LUSID.

   For example, to restrict the policy to just portfolios within the scope Finbourne-Examples:
   

9. Click Next to reach the Time Restrictions tab. Optionally, specify any time restrictions for your policy, such as taking effect on the first day of the month. Read more.
   

10. Click Next to reach the Advanced Options tab. Optionally, specify any conditions for your policy to apply at runtime for any given evaluation of access control permissions. You can specify:

    • Request header to apply the policy if the request has a specified header and value.

    • Identity claim to apply the policy if the user’s authentication token has a specified claim and value.

    • Identity scope to apply the policy if the user’s authentication token is issued in response to supplying a specified scope.

11. Select Done to review the policy, and Save to create the policy:
    

Using the Access API

The syntax of the JSON object you need to provide in the body of the request to the CreatePolicy API is complicated and highly specific to the nature of the policy you are trying to create.

Currently, we recommend creating the policy in the LUSID web app. Once created, you can manage the policy entirely programmatically.

If you do need to create a policy using the CreatePolicy API, you can create one policy per API call.

1. Obtain an API access token.

2. Call the CreatePolicy API for your LUSID domain, passing in your API access token and:

   • A code that uniquely identifies the policy.

   • A friendly description.

   • The applications the data resources are within, for example LUSID, Drive or Workflow.

   • Whether the policy grant should Allow or Deny access to the specified data resources.

   • A date from when the policy should activate, and optionally deactivate.

   • An array of selectors, that is, data resources to control access to. If you have generated selectors from a policy template, you can use them here. Each selector should contain:

     • One of:

       • idSelectorDefinition to specify an identifier to restrict the policy to. The shape of this parameter varies depending on the entity type; for most data resources, the identifier is a scope and code pair. You can specify a * value to apply the policy to all identifiers of a particular identifier type.

       • metadataSelectorDefinition to restrict the policy based on access metadata (AMD) expressions for the AMD associated with an identifier. Each expression should specify:

         • A metadataKey, for example FundGroup.

         • An operator, for example Equals or In.

         • A textValue to match on, for example FundGroup1.

         Tip

         Read more on access metadata (AMD) here.

       • matchAllSelectorDefinition to apply the policy to every scope for the entity in LUSID.

     • An array of actions the policy should allow or deny access to. Each action should specify:

       • A scope value of default.

       • The activity the policy should allow or deny access to (as listed in the table at the start of this article), for example Read or List.

       • The entity the policy relates to, for example Portfolio.

     • Optionally, a friendly name and description for the selector.

   • Values for when the policy should be applied, out of asAtRangeForSpec, asAtRelative, effectiveDateHasQuality, effectiveDateRelative and effectiveRange.

   • if values for when the policy should be applied, out of:

     • ifRequestHeaderExpression to apply the policy if the request has a specified header and value.

     • ifIdentityClaimExpression to apply the policy if the user’s authentication token has a specified claim and value.

     • ifIdentityScopeExpression to apply the policy if the user’s authentication token is issued in response to supplying a specified scope.

   • If you used a policy template to generate the policy selectors, specify the templateMetadata to track the policy when changes are made to the template used. Read more on policy templates.

   Tip

   You can examine the CreatePolicy API Reference documentation to see the allowed values for each option.
   

For example, to create a policy that allows full data access to portfolios within the Finbourne-Examples scope:

curl -X POST "https://<your-domain>.lusid.com/access/api/policies"
  -H "Authorization: Bearer <your-API-access-token>"
  -d "{
  "code": "data-policy-allow-write-portfolio-data",
  "description": "A policy that allows write access to portfolio data",
  "applications": [ "LUSID" ],
  "grant": "Allow",
 "selectors": [
        {
            "idSelectorDefinition": {
                "identifier": {
                    "code": "*",
                    "scope": "Finbourne-Examples"
                },
                "actions": [
                    {
                        "scope": "default",
                        "activity": "Read",
                        "entity": "Portfolio"
                    },{
                        "scope": "default",
                        "activity": "Add",
                        "entity": "Portfolio"
                    },{
                        "scope": "default",
                        "activity": "Delete",
                        "entity": "Portfolio"
                    },{
                        "scope": "default",
                        "activity": "Update",
                        "entity": "Portfolio"
                    },{
                        "scope": "default",
                        "activity": "List",
                        "entity": "Portfolio"
                    },{
                        "scope": "default",
                        "activity": "Any",
                        "entity": "Portfolio"
                    },{
                        "scope": "default",
                        "activity": "ReadMetadata",
                        "entity": "Portfolio"
                    },{
                        "scope": "default",
                        "activity": "UpdateMetadata",
                        "entity": "Portfolio"
                    } 
         ] } } ],
  "for": [
    { "effectiveDateHasQuality": {
        "quality": "IsFirstDayOfAnyMonth"
      } } ],
  "when": {
    "activate": "2024-10-15T18:00:00.0000000+00:00",
    "deactivate": "2027-01-01T18:00:00.0000000+00:00"
  }
}"