Permissions

Permissions

This page outlines the general design used for managing User Access Control to S3 Objects. This page is mainly targeted for users and for people who are planning on implementing and leveraging COMS.

Table of Contents

• Overview
• Access Model
  • Endpoints
• Permission Codes
  • Bucket/Object Inheritance
  • Mode Considerations
• Overrides
  • Public

Overview

When COMS is operating in either OIDCAUTH or FULLAUTH mode with a database, it will enforce access control and permissions to bucket and object resources. This is one of the core features offered by COMS, centered on leveraging your specified identity authentication provider. While the permission concepts were designed to hopefully be self-documenting and self-evident in nature, there are several nuances to how COMS leverages these permissions that we will discuss in further depth below.

Access Model

COMS leverages what is known as a Discretional Access Control (DAC) model for granting access to and sharing buckets and objects. This model was chosen in order to maximize the ability for users and clients to be able to choose at will who they wish to share their resources with. The primary benefits of the DAC model are:

1. Simplicity - as long as a user has a permission attached to the resource, they will be able to access the resource.
2. Flexibility - access control management is decentralized, allowing resource owners to grant and revoke access to their objects at will without the overhead of going through a chain of command.
3. Granularity - the data owner is able to add or remove access permissions based on individual needs and concerns.

The key thing to take from COMS access control model is that it is decentralized, and the original creator of the resource will have general ownership rights to share and distribute their objects at will. If your use cases require more oversight and classification, you may want to consider implementing a different access control model that better reflects your needs and overlay that over the COMS DAC model.

Endpoints

There are a suite of endpoints under the /permission path available for users to be able to interact with the COMS permission system. These endpoints directly focus on the following goals:

• List and search for all resources that a user has explicit or implicit permissions to
• Create, update and delete permission bindings for users to bucket and/or object resource

Permission operation endpoints directly focus on associating users to resources with specific permissions. All of these endpoints require a database to function. Existing permissions can be searched for using GET /permission, and standard create, read and delete operations for permissions exist to allow users to modify access control for specific resources they have management permissions over.

While any authorized user will be able to query for the current permission states to determine whether they have access to certain resources, only users that have the MANAGE permission for their associated resources will be able to modify, grant and revoke permissions to their specific resource at their discretion.

Permission Codes

COMS DAC model contains 5 discrete permission codes. Each of the codes represents a different set of permissions and actions that are allowed to be performed on the resource. For the most part, the permissions follow general CRUD principles and should be relatively self-explanatory.

PermCode	Permission	Description
CREATE	Create	Grants resource creation permission. Normally only the owner will have this permission assigned.
READ	Read	Grants resource read permission. Ignored when in public mode for only objects.
UPDATE	Update	Grants resource update permission. Allows user to upload a new version and/or edit metadata/tags for the object, or to edit bucket details.
DELETE	Delete	Grants resource deletion permission. Allows user to delete objects and versions.
MANAGE	Manage	Grants resource permission management. Allows the user to add/remove these permissions to other users.

Note that should you have the MANAGE permcode, it is possible for you to delete and lock yourself out of your own resources if you are not careful! COMS does not provide any safeguards for accidental lockouts when authenticating as a user. In the event this occurs, you must contact the custodian of your COMS instance. They will likely need to authenticate as a basic auth superuser to restore your permissions on the affected resources.

Bucket/Object Inheritance

As of COMS v0.4.0, there is now a multi-leveled permission system relating to both buckets as well as objects. While the original core concepts of the DAC model still apply, there are a few key points of note:

• General permission grants and revocations focus on binding a user to a specific resource with a specific permission code.
• Logically, objects reside in specific buckets. As such, permissions are now computed based on whether you have permissions in either the bucket or the object, depending on which resource you are trying to access.
• API endpoints still focus on the direct one to one bindings between a user and the resource. By default, the permission endpoints will only report the exact permissions explicitly defined to a specific resource.
• You will be able to expand the response scope to also include inherited permissions by either adding in the bucketPerms or objectPerms query parameter on the respective endpoints

One of the key concepts for object and bucket permissions in COMS v0.4.0 and onwards is that while the permission codes still mean precisely what they are scoped for, a user may be allowed to perform an action on an object if and only if they have the required permission from either having the permission explicitly defined for themselves OR having the associated bucket permission that the object resides in.

Examples

While the following examples are non-exhaustive, they hopefully provide a general idea of how permission transitivity applies in COMS.

Suppose Alice wishes to update object O which resides in bucket B. For this to happen, one of the following must be true:

1. Alice must have the UPDATE permission for Object O.
2. Alice must have the UPDATE permission for Bucket B. As object O resides in bucket B, the permission "cascades" to the object. This will be visible by using the bucketPerms query param.

Suppose Alice wishes to manage object O which resides in bucket B. For this to happen, one of the following must be true:

1. Alice must have the MANAGE permission for Object O.
2. Alice must have the MANAGE permission for Bucket B. As object O resides in bucket B, the permission "cascades" to the object. This will be visible by using the bucketPerms query param.

Suppose Alice wishes to read bucket B. For this to happen, one of the following must be true:

1. Alice must have the READ permission for Bucket B.
2. Alice has at least one permission binding with object O which resides in Bucket B. This will be visible by using the objectPerms query param. In this scenario, Alice does not have the ability to read the bucket, but they will be able to know it exists.

Suppose Alice wishes to list all buckets they have access to. For this to happen, one of the following conditions must be true:

1. Alice shall know about bucket B when they have at least one permission relation binding Alice with the bucket in question.
2. Alice shall know about bucket B when they have at least one or more objects O residing in bucket B which have at least one or more permissions binding Alice with object O. This will be visible by using the objectPerms query param.

Mode Considerations

The above permission system will only be enforced if your instance of COMS is running in either OIDCAUTH or FULLAUTH. COMS will also require a database as it needs to have a way of persisting permission information. However, the following modes will have alternate behaviors:

• Both NOAUTH and BASICAUTH modes will completely ignore permissions as they are not in scope of permission and security enforcement. This applies whether or not there is a backing database or not.
• While running in FULLAUTH mode, if the client authenticates with a Basic authorization header, permissions will be ignored as basic auth behaves as a system superuser and has "sudo" permissions to the COMS system. This applies whether or not there is a backing database or not.

Overrides

While the COMS DAC model is generally precise about what users are able to do, there are specific escape hatches and situations where the DAC is superceded or ignored by COMS for a different ruleset. This is done because while the DAC is rich and capable of expressing many access control needs, there are situations where the user may not be known in advance, and asuch binding a permission to the potential user is not possible.

Public

The simplest way of sharing your objects as a data owner is to set your object as public through the PATCH /object/:objId/public endpoint. When an object is marked as public, any anonymous user or entity will be able to read and download that specific object. In this state, all granular DAC permission codes are effectively ignored for the read object operation, as the public flag will override those permissions.