How do I create a feature policy?

Providing you are a LUSID user with sufficient privileges, you can create a feature policy to restrict access to one or more LUSID API endpoints.

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.

Note a feature policy applies even to a personal user using the LUSID web app, since the web app itself calls the API. Note also that a feature policy requires an equivalent data policy in order to yield any data.

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

Using the LUSID web app 

  1. Log 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 features specified:

  5. Select the checkbox of each feature (corresponding to API endpoints) to add to the policy:
    Selecting which API endpoints is subjective, but to grant read-only access to the instrument master for example, you might choose: GetInstrument, GetInstruments, ListInstruments, GetInstrumentIdentifierTypes, GetInstrumentProperties, ListInstrumentProperties.  

    API endpoints are identified by their operation ID. Examine the API reference for more information on each endpoint; the operation ID is printed under the URL:

  6. Select Next to reach the Data Resources tab. Optionally, select any data resources you want to add to the policy.

  7. 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.

  8. 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.

  9. 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 features are within, for example LUSID, Drive or Workflow.

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

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

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

      • identifiers to restrict the policy to, including:

        • A scope value of the API application the policy refers to, for example LUSID or Drive.

        • A code value in the relevant format:

          • For API endpoints, use api-<endpoint>-<operationID>. For example, ListInstruments could use api-instruments-listinstruments.

            Tip

            Examine the API reference for more information on each endpoint; the operation ID is printed under the URL:

          • For Luminesce providers, specify the provider name, for example Lusid.Instrument.Equity.

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

        • The same scope value as specified in identifiers.

        • The activity value Execute.

        • The entity value Feature.

      • 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 documentation to see the allowed values for each option.

For example, to create a policy that allows read-only access to the instrument master:

curl -X POST "https://<your-domain>.lusid.com/access/api/policies"
  -H "Authorization: Bearer <your-API-access-token>"
  -d "{
  "code": "feature-policy-allow-instrument-endpoints",
  "description": "A policy that allows access to Instrument API GET and LIST endpoints",
  "applications": [ "LUSID" ],
  "grant": "Allow",
  "selectors": [
        { "idSelectorDefinition": {
                "identifier": {
                    "code": "api-instruments-getinstrument",
                    "scope": "LUSID"
                },
                "actions": [ {
                        "scope": "LUSID",
                        "activity": "Execute",
                        "entity": "Feature"
                    } ],
                "name": "Run GetInstrument"
            } },
        { "idSelectorDefinition": {
                "identifier": {
                    "code": "api-instruments-getinstrumentidentifiertypes",
                    "scope": "LUSID"
                },
                "actions": [ {
                        "scope": "LUSID",
                        "activity": "Execute",
                        "entity": "Feature"
                    } ],
                "name": "Run GetInstrumentIdentifierTypes"
            } },
        { "idSelectorDefinition": {
                "identifier": {
                    "code": "api-instruments-getinstrumentproperties",
                    "scope": "LUSID"
                },
                "actions": [ {
                        "scope": "LUSID",
                        "activity": "Execute",
                        "entity": "Feature"
                    } ],
                "name": "Run GetInstrumentProperties"
            } },
        { "idSelectorDefinition": {
                "identifier": {
                    "code": "api-instruments-getinstruments",
                    "scope": "LUSID"
                },
                "actions": [ {
                        "scope": "LUSID",
                        "activity": "Execute",
                        "entity": "Feature"
                    } ],
                "name": "Run GetInstruments"
            } },
        { "idSelectorDefinition": {
                "identifier": {
                    "code": "api-instruments-listproperties",
                    "scope": "LUSID"
                },
                "actions": [ {
                        "scope": "LUSID",
                        "activity": "Execute",
                        "entity": "Feature"
                    } ],
                "name": "Run ListInstrumentProperties"
            } },
        { "idSelectorDefinition": {
                "identifier": {
                    "code": "api-instruments-listinstruments",
                    "scope": "LUSID"
                },
                "actions": [ {
                        "scope": "LUSID",
                        "activity": "Execute",
                        "entity": "Feature"
                    } ],
                "name": "Run ListInstruments"
            } }
    ],
  "when": {
    "activate": "2016-08-31T18:00:00.0000000+00:00",
    "deactivate": "2027-08-31T18:00:00.0000000+00:00"
  }
}"