Access Control

Access control lists (ACLs) allow you to define fine-grained access to object instances and their properties directly in your data model.

ACLs are composed of access control definitions. These definitions take the following forms:

{
  "type": <access target type>,
  "target": <access target identifier>,
  "allow": <access level>
}

These definitions are evaluated and applied to the specified targets at runtime.

Access Control Definition Properties

Name	Type	Description
type	Integer	Integer representing the type of entity this ACL applies to at runtime. See Access Types
target	ObjectId	The _id of the role or account that of the ACL target. Not used when type is Self or Owner.
allow	Integer	Integer representing access level being granted to target. Not used in create ACL. See Access Levels

Access Types

Type	Name	Description
1	Account	Target type of Account -- includes anonymous and public principals.
2	Self	Applies to ACL on Account object only. Access principal is the same as the Account instance being accessed.
3	Role	Target type of org role
4	Owner	Access principal is the object instance owner.
5	Access	For share ACL only, allows the access target to be an access level. This overrides the share chain behaviour and enables more fine-tuning.

Access Levels

Level	Name	Description
1	Public	A principal with this access can read public data (eg, Org details).
2	Connected	Granted when making Connections and typically provides read access to context properties.
3	Reserved	Reserved for a future use
4	Read	Grants access to private context properties. This is default access level required for new custom properties.
5	Share	Those with share access can create connections to a context using object’s Share Chain
6	Update	Update access typically provides write access to context properties.
7	Delete	Grants access to delete delete/archive a context.
8	Script	The highest assignable access level, it can only be granted at runtime in a script.

Defining ACL

By default, Cortex enforces a no-access sharing model. This means that without defined ACL, users cannot create, read, update, or delete any data through the API. That is, until the ability to do so is granted through ACL definitions in custom objects and in extensible standard objects.

Standard objects such as the Account Object come pre-defined with Create ACL and Default ACL that enforce a private sharing model.

In a private-sharing model, data is only available to the creator/owner and no one else. In this model, there are only two ways for a user to gain access to another user's data:

1. The owner of the data shares that data with another user directly using Connections.

2. Access to the data is granted to a subset of users (such as through ACLs)

The following ACL definitions make up a typical private-sharing implementation for an object.

Create ACL

createAcl: [{
  "target": "000000000000000000000003",
  "type": 1
}]

Here, the type: 1 specifies the target is an Account, and the target: "000000000000000000000003" is the system identifier for any user in the org. So this ACL is specifying that any authenticated user can create instances of this object.

Default ACL

defaultAcl: [{
  "allow": 7,
  "type": 4
}]

Here, the type: 4 is specifying that the target is the instance Owner, and the allow: 7 specifies that the Owner is granted Delete access.

Share Chain

shareChain: [6, 5, 4, 2]

This share chain specifies that access levels of update (6), share (5), read (4), and connected (2) can be used in connections. Because it is a share chain, a user can create a connection with one of these allow levels as long as it is less than his/her own.

Create ACL

Create ACLs determine who in an Organization can create new object instances. Conversations, for example, can only be created by accounts with the Provider role. An object's create acl can be defined in custom objects and augmented or even overwritten in extensible standard objects.

In the case of Create ACL, allow is not provided in the definition since create access is already implied.

Default ACL

Each Object has it's own set of default rules that determine the level of access users get to object instances. For example, the Account Object default acl allows the account holder Update access to themselves. These defaults can be defined in custom objects and augmented or even overwritten in extensible standard objects.

Share ACL

Share ACLs define how an object instance can be shared. The target in a share ACL entry can be an account, role, owner, or another access level. The allow in a share ACL entry then specifies what role or access level that target is allowed to grant when sharing an object instance via a connection. When share ACL rules are defined, share chains no longer apply.

Example Share ACL

shareAcl:[{
    "type": 5,
    "target": 7,
    "allow": 6
}]

Here, the type: 5 is specifying the target is an access level. This means that a user with an access level of 7 (Delete) to the instance can grant up to access level 6 (Update) to another user via a connection.

shareAcl: [{
  "type": 4,
  "allow": "000000000000000000000005"
}]

Here, the type: 4 is specifying the target is the instance owner and that the owner can grant the provider role (role _id "000000000000000000000005") via a connection. This means that any defaultAcl defined for the provider role in the object definition will be granted to the connected user for that object instance even though they may not have the provider role assigned to their user account.

shareAcl: [{
  "type": 3,
  "target": "5532e499540b0183799b4ee5"
  "allow": "58e96eb0105ddf010067046b"
}]

Here, the type: 3 is specifying the target is a role. We've created some custom roles of Manager (role _id "5532e499540b0183799b4ee5") and Reporter (role _id "58e96eb0105ddf010067046b"). In the share ACL rule, we are specifying that the Manager role can grant the Reporter role to another user for an object instance via a connection.

Share Chains

The share chain for each Object controls the access level that can be granted to a user through a Connection. A user with enough access to create a Connection can grant any level of access in the object's Share Chain as long as it is lesser than their own.

For example, a user who creates a Patient File is granted Delete access through the object's default ACL. That use can then grant others Share or Connected access to the context. Subsequently, a connected invitee with Share access could re-share the context with others, but only grant Connected access.

The share chains for each object are listed in their descriptions.

User Roles

There are three standard roles: Admin, Provider and Developer. An Organization can create custom roles, and assign access controls to these. Custom roles can be also be includes within each other. All accounts holder a role are also assumed to hold the included roles.

Creating custom roles can easily be done under Settings > Roles. Creating a new custom role simply requires providing a role name.

Custom roles can also be hierarchical. For example you can create a custom role and specify that it includes other roles.

Once your custom role is created, it's available to be used in Access Controls as well as in scripts via the Consts Module

Property ACLs

Object properties have ACLs that determine the access required to create, read, update and delete properties. An Organization can also augment read and update access settings for individual properties with custom ACLs. Commonly, properties required with connected access to read and Update access to update.