Access Policies

Overview

When creating an API Key for using Neurelo APIs in the Environment for your Project, by default you can allow Read-Only or Read/Write permissions for the entire Environment. Access Policies allow more fine-grained control, where you can configure permissions at an object and property level for the schema being used in the environment.

Using Access Policies

Define your schema

Before you start with access policies, you should have your schema already in place (see https://docs.neurelo.com/definitions). This is because you will reference objects and their properties when defining access policies.

Define Access Policies

• Navigate to the “Access Policies” tab under the Definitions for your Project

• Create one or more access policies. See Access Policy definitions for a description of the supported policy definitions and their format.

• Once you have defined your access polices, create a new commit for your definitions.

Create an API Key

• First, if you don’t already have one, you will now have to create an environment (see https://docs.neurelo.com/environments/creating-a-new-environment) and use the Commit of the definitions which include the Access Policy definitions.

• If you already have an environment, navigate to the Environment for your project from the left side navigation bar or from the dashboard for your project and update the Environment to use the Commit of the definitions which include the Access Policy definitions.

• Create the API Key as described in https://docs.neurelo.com/environments/api-keys. Now you will find there an option to choose your access policy to be attached to this key

Use the API Key

• You can use your access policies enabled API key anywhere you would use a regular key.

• The operations that can be performed using the key will follow the policies you have defined and attached to that key.

When using the API Key, access policies only apply for the auto-generated apis in your environment. They are not evaluated for custom api endpoints.

Access policy definitions

Each Access Policy is defined as a list of CRUD (create/ read / update /delete) permissions on an object or inner object.

create

Create an object. This also allows creation of contained inner objects (for MongoDB projects).

Example:

[
   {
      "create":"Book"
   }
]

createAnyObject

Create any object (regardless of the object name). This also allows creation of contained inner objects (for MongoDB projects).

Example:

[
    "createAnyObject"
]

read

Read fields in an object or inner object (for MongoDB projects). This includes checks in a where.

Checks must have these keys

• objectName/innerObjectName: Name of the object or inner object (for MongoDB)

• properties: The properties allowed to be inspected

Example:

[
   {
      "read":{
         "objectName":"Publisher",
         "properties":[
            "id",
            "location",
            "name"
         ]
      }
   },
   {
      "read":{
         "innerObjectName":"Location",
         "properties":[
            "city_name",
            "state_name",
            "zip_code"
         ]
      }
   }
]

readAnyProperty

Read any field in an object or inner object (for MongoDB projects), regardless of the property name. This includes checks in a where.

Checks must have these keys

• objectName/innerObjectName: Name of the object or inner object (for MongoDB)

Example:

[
   {
      "readAnyProperty":{
         "objectName":"Publisher",
      }
   },
   {
      "readAnyProperty":{
         "innerObjectName":"Location",
      }
   }
]

readAnyObject

Read fields in any object or inner object (for MongoDB projects), regardless of the object name. This includes checks in a where.

Example:

[
   "readyAnyObject"
]

update

Alter the contents of an object or inner object (for MongoDB). This is parameterized by a list of properties, allowing only some fields to be modified.

Checks must have these keys

• objectName/innerObjectName: Name of the object or inner object (for MongoDB)

• properties: The properties allowed to be inspected

Example:

[
   {
      "update":{
         "objectName":"Publisher",
         "properties":[
            "id",
            "location",
            "name"
         ]
      }
   },
   {
      "update":{
         "innerObjectName":"Location",
         "properties":[
            "city_name",
            "state_name",
            "zip_code"
         ]
      }
   }
]

updateAnyProperty

Alter the contents of an object or inner object (for MongoDB), regardless of the property names.

Checks must have these keys

• objectName/innerObjectName: Name of the object or inner object (for MongoDB)

Example:

[
   {
      "updateAnyProperty":{
         "objectName":"Publisher",
      }
   },
   {
      "updateAnyProperty":{
         "innerObjectName":"Location",
      }
   }
]

updateAnyObject

Alter the contents of any object or inner object (for MongoDB), regardless of object name.

Example:

[
    "updateAnyObject"
]

delete

Delete an object. This will also allow delete for any inner objects (for MongoDB projects).

Example:

[
   {
      "delete":"Book"
   }
]

deleteAnyObject

Delete any object, regardless of object name. This will also allow delete for any inner objects (for MongoDB projects).

Example:

[
    "deleteAnyObject"
]

customQuery

Allow a specifc custom query, specified by name.

Example:

[
   {
      "customQuery": "find_books_by_publishers_in_new_york"
   }
]

customQueryAny

Allow any custom query, regardless of name.

Example:

[
    "customQueryAny"
]

Usage Notes

Response Code

If the request attempts to perform an operation that isn’t allowed by the policies specified, the response will have the status code HTTP 403 - Forbidden

Updating Policies

If you would like to update the existing attached policies for an api key,

• Edit the policies in the Access Policies tab under Definitions

• Create a new Commit

• Update the Environment to use this new Commit. This step will need Runners for the environment to be stopped and re-started.

Once the environment is updated, new incoming requests with that key will be evaluated against the updated policy definitions

Multiple Policies

You can create and attach multiple policies to an API Key. When multiple policies are identified for an API operation, the operation will be allowed based on the cumulative set of permissions from all of the policies. For example, consider the following permissions:

# `read_city_state` permissions:

[{
    "read": {
        "objectName": "Location",
        "properties": ["city_name", "state_name"]
    }
}]

# `read_zip_code` permissions:

[{
    "read": {
        "objectName": "Location",
        "properties": ["zip_code"]
    }
}]

A GET request to the /rest/Location endpoint with

• the select parameter {"city_name":true,"state_name":true,"zip_code":true}

• specifying the roles ["read_city_state","read_zip_code"]

will be allowed because each selected field is permitted by a rule in one of the policies.

However, the same operation only with the "read_city_state" role but not "read_zip_code" would receive an HTTP 403 response due to no permissions allowing inspection of the zip_code field to be found.

Relations

When performing an operation that accesses or modifies across a relation, permissions for the related object will be checked as needed.

For example, if a schema contains an object called User with a field called blog_post_ids that relates to one or more Post objects,

• querying the blog_posts field of the Users object will require read permissions for the relevant id field of Post that the blog_post_ids field of User references.

• Similarly, an update to the User object that uses the "create" operator to add a reference to new existing Post would require permission to create that