6. Access Control

Access control in xGT can be enabled on both frames and rows.

6.1. Frame Access Control

Frame access control protects all the rows in a frame with the same permissions. Each frame in the system can have different access permissions for each authenticated user. Frame access control is based on matching the access permissions required for a frame with the access permissions granted to an authenticated user. Access permissions are determined by matching security labels for frames with the labels that the user possesses.

A frame has four sets of labels, one for each of the following access types:

  • Create: The create access type allows the insertion of new rows into the frame.

  • Read: The read access type allows reading operations on the data rows held by the frame.

  • Update: The update access type allows the updating of existing rows in the frame. Columns of existing rows can be modified if this access type is granted.

  • Delete: The delete access type allows the deletion of existing rows from a frame. Delete access on a frame is also required to delete the frame itself.

Having create, update, or delete access requires also having read access.

xGT uses the term CRUD labels for the sets of labels attached to a frame (frame label).

6.2. Row Access Control

Row access control protects individual rows in frames. The word “row” means a frame element, such as a vertex in a vertex frame, an edge in an edge frame, or a row in a table frame. Each row in a frame can have multiple security labels attached to it and permission to access the row is determined by matching its labels with those that the user possesses. Unlike frame security, row access control is binary and does not have CRUD types: a user can either access a row or not (row label).

A frame with row security also has frame security. Both the frame and row permissions are checked when accessing data in xGT. To read, update, or delete a row, the user must have both the corresponding frame CRUD permissions and the security labels attached to that row. Frame labels restrict the type of operation that can be performed, while row labels restrict which rows will be affected by that operation.

For example, a user with read access to a frame may perform a read operation, but will only see those rows that the user has permission to access. Similarly, a user with delete and read access to frame WorksFor and People may perform the following query that deletes edges, but this only removes edges the user has permissions for. If there are edges that the user cannot access or whose endpoint vertices the user cannot access, they will be unaffected.

MATCH (a:People)-[b:WorksFor]->(:People)
WHERE a.status = transferred
DELETE b

6.3. User Labels and Validation

xGT uses a simple model for access control. The set of labels a user possesses must contain the labels on the frame the user wishes to access for the desired CRUD operation. To access a row within a frame with row security, the set of labels a user possesses must also contain the labels attached to that row. The set of labels a user possesses is determined by taking the union of the labels of all the groups they belong to (user labels).

The rest of this section explains how access control works in detail. If you need to learn how to configure it see instead Configuring Groups and Labels.

When a user authenticates, a list of groups is retrieved from the external authentication system via PAM. xGT maps those groups to a set of labels for the user’s identity by using the mapping stored in the system frame xgt__Group_Label.

Each entry in the xgt__Group_Label frame maps a group to a specific label. Because a group may appear in multiple rows of the frame, the same group may map to different labels (one-to-many). The only restriction is that the labels must be present in the master label catalog in the frame xgt__Label.

System frames, such as the xgt__Label and xgt__Group_Label frames, are discussed in detail in System Frames (system frames).

Since a user can belong to multiple groups simultaneously, the mapping of users-to-labels is a many-to-many mapping. For example user01 may belong to groupA and groupB. The groupA group is mapped to labels label01, label02 and label03, while groupB is mapped to label03 and label05. The resulting set of labels for user01 is { label01, label02, label03, label05 }.

xGT assesses the type of operation requested by the user to determine which of the CRUD label sets to validate the user labels against. The following example shows a simple query without modifications to queried frames that writes to a results table.

MATCH (a:People)-[b:WorksFor]->(c:Companies)
WHERE 100 >= a.person_id AND a.person_id <= 150
RETURN a.name, c.name
INTO results__Result

To be able to execute this query, the user’s labels must contain all the read labels on each frame being read: People, WorksFor and Companies. The user’s labels must also contain the read labels of the results namespace frame and the read and create labels of the results__Result frame. If the results table doesn’t already exist, the user’s labels must also contain the create labels of the results namespace. The query will only return a result for those edges and vertices whose row labels the user possesses. For any of the frames in the query that have row access control, the query will only return a result that includes rows whose row labels the user possesses. A query may mix frames with no labels attached, only frame labels, only row labels, or both.

Namespaces and frame types are described in more detail in Frames and Namespaces.

6.4. Inheriting Namespace Labels

The configuration setting security.inherit_namespace_labels enables the system administrator to prevent the users from creating frames that have no CRUD labels (i.e. access is allowed for all users) inside namespaces that are access controlled.

If set to true and a frame with no labels is created inside a namespace with labels, then the frame inherits the CRUD labels of the namespace. This mechanism increases the security of the system by preventing other users that do not possess the labels of the namespace from accessing the newly created frame.

The default for the label inheritance setting is false as it matches the semantics of UNIX directory and file access. In UNIX, a user can access a file using its absolute path, even if they cannot access the enclosing directory.

6.5. Per User Private Namespaces

The configuration setting system.auto_create_user_namespace enables the automatic creation of private, per user namespaces when the users log on to xGT.

The user’s identity (user ID) in the system is used to generate names for a group and a label. The generated label is then used for all four CRUD permissions on a private namespace named after the user’s ID.

If the namespace already exists, then nothing is done. If the group and label names already exist, they are applied to the newly created user namespace.

The default for private namespace creation is false.