ACL Customization Examples

In order to allow a subject to read KiiObjects in a bucket, it is not sufficient to add an ACL entry with the QUERY_OBJECTS_IN_BUCKET action.

Use the READ_OBJECTS_IN_BUCKET action to allow reading all KiiObjects in a bucket. Adding an ACL entry with this action to a bucket ACL permits the subject to read all KiiObjects in the bucket.

See the below cases to understand different effects of ACLs with and without the READ_OBJECTS_IN_BUCKET action. Suppose Alice shares a bucket in her user scope with Bob.

Without the READ_OBJECTS_IN_BUCKET action

A subject other than the scope owner cannot get KiiObjects created by any other user or thing through a query because the subject is not permitted to read KiiObjects returned by a query.

  1. Alice creates a KiiObject in her user-scope bucket. Only Alice can access this scope.

  2. In order to share information with Bob, Alice adds ACL entries for Bob with the CREATE_OBJECTS_IN_BUCKET and QUERY_OBJECTS_IN_BUCKET actions to the bucket ACL. This allows Bob to create and query KiiObjects.

    However, Bob cannot read KiiObjects created by any user other than himself. Bob's query for KiiObjects in the bucket returns no result because he cannot read KiiObjects created by Alice.

  3. Bob now creates a KiiObject in Alice's user-scope bucket.

    Alice can find both KiiObjects because she is the scope owner.

    Bob can find only the second KiiObject because he is the creator of the second KiiObject.

  4. Alice now creates another KiiObject in her user-scope bucket.

    Alice can find all KiiObjects because she is the scope owner.

    Bob can find only the second KiiObject because he is the creator of the second KiiObject.

As you can see in this example, permitting a subject who is not the scope owner to create and query KiiObjects in a bucket does not permit them to read KiiObjects in a bucket. If your application frequently creates and deletes shared KiiObjects, it is not feasible to share data with the permission setting in this example because it requires frequent ACL changes. Consider using the READ_OBJECTS_IN_BUCKET action as in the next example or the group feature in such a case. For an example of using the group feature, see Designing with the Group Feature.

With the READ_OBJECTS_IN_BUCKET action

A subject permitted to read KiiObjects in a bucket can read all KiiObjects in a bucket with no limitation.

See how a subject can access data with this permission using the previous example of Alice and Bob.

  1. Alice creates a KiiObject in her user-scope bucket. Only Alice can access this scope.

  2. In order to share information with Bob, Alice adds ACL entries for Bob with the CREATE_OBJECTS_IN_BUCKET and QUERY_OBJECTS_IN_BUCKET actions to the bucket ACL. This allows Bob to create and query KiiObjects.

    Additionally, Alice also adds an ACL entry for Bob with the "READ_OBJECTS_IN_BUCKET" action to the bucket ACL. This allows Bob to read all KiiObjects in the bucket.

    Although Bob is not directly permitted to read KiiObjects created by Alice, he is now permitted to read all KiiObjects in the bucket. Bob's query for KiiObjects in the bucket returns the KiiObject created by Alice.

  3. Bob now creates a KiiObject in Alice's user-scope bucket.

    Alice can find both KiiObjects because she is the scope owner.

    Bob can find both KiiObjects because he is permitted to read KiiObjects in the bucket.

  4. Alice now creates another KiiObject in her user-scope bucket.

    Alice can find all KiiObjects because she is the scope owner.

    Bob can find all KiiObjects because he is permitted to read KiiObjects in the bucket.

As shown in this example, you can provide "read-only" data sharing easily by permitting the "Read all KiiObjects in the bucket" action.

Note that you cannot support read/write data sharing (i.e., allowing Bob to update KiiObjects created by Alice) with this method. Consider using the group feature. For an example of using the group feature, see Designing with the Group Feature.