-
Notifications
You must be signed in to change notification settings - Fork 2
Pebbles Security Model (Visibility)
This document outlines how PSM defines visibility of objects in the pebblephere. Policies for actions like update, create, delete is documented here:
https://github.com/bengler/checkpoint/wiki/Pebbles-Security-Model-(Actions)
The Pebbles Security Model aims to enable different access privileges to specific groups of people to specific subsets of pebbles content. Use cases include:
- An organization is modelled in Origami. Using PSM the organization gives certain operatives in the organization access to read or update specific records in their organization model based on their credentials in the organization.
- An application for a newspaper include a public data set and a private set of records containing sensitive private information about contributors. The general public have access to all public content, while a group of application administrators have the privilege of accessing the private information.
- An application for a media coglomerate is used by a wide selection of publications. Through PSM operatives of each publication are given administrative privileges to the data pertaining to their specific instance of the application.
Every object in the pebbles ecology has a place in The Great Tree. A node in the tree is called a Location and is expressed as a period-delimited string of labels, e.g. "dna.dittforslag.topic_1" or "apdm.bandwagon.bands". The tree is analogous to a folder structure in a file system.
The first label in a location is the Realm of the node. Roughly each organization using a pebbles installation corresponds to one node. In our case the Labor Party has the realm "dna" while AMedia has the realm "apdm". No links across realms is allowed within a pebbles installation. E.g. an identity that is registered in the dna realm cannot be the owner of an object posted in the apdm realm.
The second label in the location corresponds roughly to one application. The usage of the subtree after this level may be totally application specific.
Different pebbles maintain separate layers of the tree. Every object of the class post is handled by Grove, while unit, associate etc. is handled by Origami. The PSM describes how every pebble that maintains objects in the tree should treat security, but each implementation will probably be different.
Each realm can define a set of Gods. These are users with unrestricted privileges in all areas of the realm. This is necessary to bootstrap configuration of the realm and typically granted daemons that are tasked with configuring the realm according to some data source. Having the god-bit bypasses any other PSM-related processing.
Generally all content in the pebblesphere is readable to all. Restricted content is objects that are readable only to certain users according to the PSM. For unrestricted content no PSM processing is required.
Many objects in the pebblesphere defines an owner. Typically this is the originator of the object. An object is always visible to its owner, even if the PSM otherwise would deny access.
Within a realm the maintainers may define a number of Access Groups. Each access group is a set of checkpoint identities and a list of locations. The purpose of the access groups is to grant specific priveleges to a given set of identities for a specific subtree of The Great Tree.
Each location listed in the access group points to a subtree of The Great Tree. The members of the access group may read all restricted content whithin these subtrees.
An application lets any user contribute policy-suggestions to the ruling party. For each suggestion two documents are stored in Grove. post.suggestion contains the actual suggestion, while post.author_info contains sensitive personal information of the suggester. The suggestion is public, while the author_info-record is restricted.
When a visitor with no special privileges queries grove for content, only the suggestions are visible. Additionally the users own author_info-records are visible because they are owned by her.
An acces group is defined for the admins of this application. The access group lists all the admins and the location of the content for this app: dna.dittforslag. When these users query the application data they are able to retrieve all author_info-records in addition to the suggestions. Thus they may access restricted content in dna.dittforslag.topic_1 and dna.dittforslag.topic_2.subtopic_B, but they would not be able to read restricted content in dna.secret_agenda.sinister.stuff. That is unless they are also listed in another access group with access to this secret stuff.
Checkpoint is the central authority on access_groups. Only gods may configure or inspect access groups. An api is provided that allows creation and inspection of groups, management of identities and locations attached to the group.
An access_group has the following properties:
- realm
- external_id - an optional secondary id according to an external system maintaining the access_group
- title - an informal name for debugging
Attached to the access_group:
access_group_memberships
- access_group_id
- identity_id
Can not be a join-table because it will for sure aquire other fields to modify the role of the identity.
access_group_locations
- access_group_id
- location - a string representing a node in The Great Tree
In addition to the http-api provided by checkpoint, every update of the access_groups is broadcast on the river. Pebbles that need to update their state to deliver PSM-compliant results in a timely manner listens to the river and perform updates accordingly.
It is the responsibility of each pebble to respect PSM policies when processing queries. Every pebble may need to implement PSM compliance in its own special way according to how it organizes its data.
Here are some suggestions on how to implement PSM in individual pebbles.
Every location used in Grove has an entry in the locations-table. To determine if a restricted document is visible to a given user, we need to determine if the location is within the subtree of one of the access_groups that the user is enrolled in.
A daemon is listening to the river for locations that are added or removed from access groups. It maintains the table access_group_locations which enumerates all locations associated with an access_group.
access_group_locations
- access_group_id - the id of the group
- label_0, label_1, label_2 … - the path of the location
When the access_group_locations is updated, the groups_locations table is updated. For each location in grove this table contains every group that has access to the document in the location. In pratice the complete subtree mentioned in the location of an access_group_locations-entry is traversed and entries are added (or removed if the entry was deleted).
groups_locations
- location_id - the id of the location record
- access_group_id - the id of the group
Also when a location is added to grove, the applicable access_group_locations are retrieved and the groups_locations updated accordingly.
When querying grove the current access_groups of the current identities is retrieved from checkpoint (with readtrhough caching with memcached with a relatively short TTL (10 minutes)). Then a scope is applied that checks that if the object is restricted, at least one of its locations must be associated with at least one of the groups that the user is in. (And of course: If the user is a god, all this is bypassed anyway)
Grove maintains a real time shadow copy of the access data in Checkpoint in order to provide results very fast. This is however complex and brittle. For Sherlock and Origami we opted to retrieve access data from Checkpoint through a cache for every query which turned out to work really well. In the future we might modify Grove to behave in the same way because it is simple and robust.
These Pebbles uses the helper class Pebblebed::Security::Client provided in the pebblebed gem. Instantiated with a connector with god privileges it provides the method access_data_for(identity_id). This yields an instance of Pebblebed::Security::AccessData. This can then be queried for specific paths the user has access to which then can be applied as scopes to the queries used in the service. When e.g. sherlock is asked to retrieve data for the wildcard path "dna.^organization.unit1.unit2.*" it will retrieve access_data for the current user and ask the access_data object for a list of relevant subpaths pertaining to the imminent query:
security_client.access_data_for(current_user).relevant_subtrees("dna.^organization.unit1.unit2.*")
Which will yield an array of strings representing every subpath that this user has restricted access to that could impact the results of a query into this wildcard path. This is used by Sherlock to augment its Elasticsearch query, and by Origami to augment its sql.
Relevant lines in Sherlock:
- https://github.com/bengler/sherlock/blob/master/api/v1/search.rb#L28
- https://github.com/bengler/sherlock/blob/master/lib/sherlock/query.rb#L115
Relevant lines in Origami: