Customizing a Bucket's ACL

You can change the access control applied to a bucket by setting the bucket's ACL.

In order to customize the permission to create buckets, you need to change the ACL of the scope in which buckets are to be created.

When a KiiObject inside a bucket is accessed, the KiiObject's ACL will be also checked.

Bucket ACL entries

By setting a bucket ACL entry, you can, for example, allow anonymous users to create new KiiObjects in the bucket.

A bucket ACL entry is composed of an action and a subject:

  • Action

    This item defines "what" the target user/group/thing can execute.

    Action What the target user/group/thing can execute
    CREATE_OBJECTS_IN_BUCKET Create new KiiObjects in the bucket.
    QUERY_OBJECTS_IN_BUCKET Query KiiObjects in the bucket.
    READ_OBJECTS_IN_BUCKET Read KiiObjects in the bucket.
    DROP_BUCKET_WITH_ALL_CONTENT Drop the bucket along with all KiiObjects inside.

    Note: The "READ_OBJECTS_IN_BUCKET" action allows the subject to unconditionally read all KiiObjects in the bucket. For more information, see ACL Customization Examples.

  • Subject

    This item defines "who" can execute.

    Subject Who can execute the designated action?
    UserID:{USER_ID} The specified user.
    GroupID:{GROUP_ID} The members of the specified group.
    ThingID:{THING_ID} The specified thing.
    UserID:ANY_AUTHENTICATED_USER Any authenticated users.
    UserID:ANONYMOUS_USER Anonymous users.

    See Subject for the definition of the "Any authenticated users" and "Anonymous users".

You then specify the "target bucket" in the URL as follows. The URL also includes the action and subject:

  • In the application scope:

    https://api-jp.kii.com/api/apps/{APP_ID}/buckets/{BUCKET_ID}/acl/{ACTION}/{SUBJECT}
    You need to present the app administrator token (See Admin Features).

  • In a group scope:

    https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/buckets/{BUCKET_ID}/acl/ {ACTION}/{SUBJECT}
    You need to present the access token of the group owner.

  • In a user scope:

    https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/ {ACTION}/{SUBJECT}
    https://api-jp.kii.com/api/apps/{APP_ID}/users/me/buckets/{BUCKET_ID}/acl/{ACTION}/{SUBJECT}
    You need to present the access token of the scope owner.

  • In a thing scope:

    https://api-jp.kii.com/api/apps/{APP_ID}/things/VENDOR_THING_ID:{VENDOR_THING_ID}/ buckets/{BUCKET_ID}/acl/{ACTION}/{SUBJECT}
    https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/buckets/{BUCKET_ID}/acl/ {ACTION}/{SUBJECT}
    You need to present the access token of the thing or thing owner.

Managing a bucket's ACL

You can add and delete an ACL entry in a bucket's ACL. You can also get a list of ACL entries.

Adding a bucket ACL entry

Authorized subjects can add ACL entries to the ACL of buckets not in the application scope to add permissions (e.g., allowing anonymous users to create KiiObjects in the bucket). Only the app administrator can modify the ACL of buckets in the application scope (See the hint below).

Here is a sample API call for adding two new ACL entries to the ACL of a users-scope bucket. In this example, the CREATE_OBJECTS_IN_BUCKET action is permitted to a user with an id {USER_ID_2}:

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET/UserID:{USER_ID_2}" \
  -d ""

You can also set an ACL entry to a non-existent bucket. In this case, the bucket will be auto-generated with the specified ACL entry.

See the following examples of adding a bucket ACL entry:

Permitting the CREATE_OBJECTS_IN_BUCKET action to ANONYMOUS_USER:

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET/UserID:ANONYMOUS_USER" \
  -d ""

Permitting the CREATE_OBJECTS_IN_BUCKET action to ANY_AUTHENTICATED_USER:

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET/UserID:ANY_AUTHENTICATED_USER" \
  -d ""

Permitting the CREATE_OBJECTS_IN_BUCKET action to a group:

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET/GroupID:{GROUP_ID}" \
  -d ""

Permitting the CREATE_OBJECTS_IN_BUCKET action to a thing:

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET/ThingID:{THING_ID}" \
  -d ""

Deleting a bucket ACL entry

To revoke an action that was allowed before, send a DELETE request for the target ACL entry.

In this example, we delete an ACL entry of the CREATE_OBJECTS_IN_BUCKET action permitted to the user {USER_ID_2}.

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET/UserID:{USER_ID_2}"

You can delete ACL entries in other scopes by specifying the corresponding URL.

Getting a bucket's ACL

To get the ACL set on a bucket, send a GET request to the corresponding URL with no action or subject.

The following example gets a list of all subjects who are permitted the CREATE_OBJECTS_IN_BUCKET action.

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET"

The next example gets a list of all ACL entries in a bucket's ACL.

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl"

Both examples specify a bucket in a user scope. To get the ACL of a bucket in any other scope, specify the corresponding URL.

Troubleshooting

  • The subject is permitted the "QUERY_OBJECTS_IN_BUCKET" action but failed to query KiiObjects in the bucket

    The QUERY_OBJECTS_IN_BUCKET action only allows the subject to execute the query. To read the result (i.e., the KiiObjects queried), the subject also needs to have the privilege to read the KiiObjects.

    The easiest way to grant the privilege to read the KiiObjects is to permit the READ_OBJECTS_IN_BUCKET action to the subject together with the QUERY_OBJECTS_IN_BUCKET action. This will allow the subject to read all KiiObjects in the bucket, so they will be able to read the query result.

    Alternatively, you can permit the READ_EXISTING_OBJECT action on the KiiObjects in the bucket. See KiiObject Access Control for more information about the KiiObject ACL.

    You can find the related discussion in ACL Customization Examples.

  • I cannot delete an ACL entry

    You cannot delete default ACL entries applied to scope owners and bucket creators. See Cannot delete default ACL entries of scope owners and creators for more details.

  • I cannot change the ACL of an application-scope bucket

    Changing the ACL of an application-scope bucket requires the app administrator privilege. Follow the procedure described in Admin Features to get an app administrator token and change the ACL.

    For more information about who can change a bucket's ACL, see Bucket Access Control.