Access Control List

The access permission is defined by the ACL (Access Control List).

The scopes and instances of buckets, KiiOobjects, and push notification topics have an ACL. Every time when the currently logged-in user accesses any of them, Kii Cloud checks their privileges with the ACL and determines if the user is allowed to perform an action on it.

Structure of an ACL

As shown in the figure below, an ACL in Kii Cloud is a whitelist, a collection of permission entries. Each permission is called an ACL entry and composed of a subject (which performs an action) and an action (which is performed by a subject).

Here is an example. Suppose Bob creates a new KiiObject in Alice's user-scope bucket. As explained in KiiObject Access Control, both Alice (as the scope owner) and Bob (as the KiiObject creator) will have the read and write permission on the KiiObject by default. The KiiObject's ACL will be set as illustrated in the following figure.

Settable actions for an ACL vary depending on the target of the ACL. See ACL Entries for the complete list of actions.

See the below figure for the relation of instances and ACLs.

When an instance is created, Kii Cloud automatically assigns a predefined ACL to it. A scope indicates to which entity data belongs to and you do not create it as an instance, but it also has the default ACL according to its type.

You can customize ACLs with the ACL modification feature of the client SDKs and REST APIs.

Flow of permission checking

The following figure illustrates how Kii Cloud checks permissions of a bucket.

When a user accesses the storage, Kii Cloud checks permissions at the two levels: the bucket level and/or the KiiObject level. The check is done at either or both depending on the user action. You need to be aware of the two different levels in order to obtain expected results.

Here are examples:

  • Creating a KiiObject: This action is taken against the bucket, so the create permission is checked only at the bucket level.

  • Querying and retrieving a KiiObject: This is a combination of a query action on the bucket and a retrieval action on the KiiObject. The first query permission is checked at the bucket level when querying the KiiObject and the second read permission is checked at the KiiObject level when downloading the KiiObject.

  • Directly getting a KiiObject with the URI: This action creates an empty KiiObject instance from the URI and refreshes it to get the content. This action is taken against the KiiObject, so the read permission is checked at the KiiObject level only.

Considerations

Here are some notes you need to consider when handling the ACL.

No "deny" entry

Kii Cloud does not support an ACL entry for denying access. You cannot, for example, revoke the access permission of a specific member in a group.

Though the API to modify an ACL seems usable for denying access, it actually revokes an added ACL entry. Specifically, the KiiACLEntry class is composed of KiiSubject, KiiAction, and grant (a bool value). Updating an existing ACL entry with grant set to false deletes the ACL entry. For example, if you want to delete an ACL entry which allows Alice to read from an ACL, update the existing ACL entry by specifying "Alice, read, grant=false".

Cannot delete default ACL entries of scope owners and creators

Even the application administrator or users with the privilege to modify ACLs cannot delete default ACL entries of scope owners (group owners, users, or things that own a scope) and creators of buckets, KiiObjects, and topics. For example, you cannot delete an ACL entry which permits the QUERY_OBJECTS_IN_BUCKET action to the bucket creator from the ACL of a bucket in a group scope.

The below is a list of ACL entries that cannot be revoked:

Application scope:

  • READ_EXISTING_OBJECT and WRITE_EXISTING_OBJECT of KiiObject creators
  • SUBSCRIBE_TO_TOPIC and SEND_MESSAGE_TO_TOPIC of topic creators

Group/user/thing scope:

  • CREATE_NEW_BUCKET and CREATE_NEW_TOPIC of scope owners
  • QUERY_OBJECTS_IN_BUCKET, CREATE_OBJECTS_IN_BUCKET, READ_OBJECTS_IN_BUCKET, and DROP_BUCKET_WITH_ALL_CONTENT of bucket creators
  • READ_EXISTING_OBJECT and WRITE_EXISTING_OBJECT of scope owners and KiiObject creators
  • SUBSCRIBE_TO_TOPIC and SEND_MESSAGE_TO_TOPIC of scope owners and topic creators

ACL sequence has no meaning

Since the ACL is a whitelist, the sequence of the ACL entries has no meaning.

Cannot add a duplicating ACL entry

If you try to add a duplicating ACL entry (or any other invalid ACL entry), you will get an error.

Updating multiple ACL entries might partially fail

The Android, iOS, and JavaScript SDK allow you to update multiple ACL entries at the same time (you cannot do this with the REST).

When multiple ACL entries are updated and the save method is executed, these ACL entries are updated sequentially inside the SDK. If the update is interrupted (e.g. by an error or by the process down), only some portions of the ACL entries might be updated. In case the ACL updating is critical, consider implementing a retry mechanism in your application (see Transactions for the related information).

Some client SDKs allow you to get a set of ACL entries that have been successfully updated and the ones failed to be updated when an error occurs.