Stratus Permissions

Default Permission Template

You can create a bucket with one of two types of default permission templates.

• Authenticated Permission Template: A bucket created using this default permission template will dictate that all the objects of your bucket can only be accessed by users that are authenticated on the client portal of your application.

• Public Permission Template: A bucket created using this default permission template will allow any end-user on the internet to access the objects of your bucket without any authorization requirement.

Custom Permissions

When you create a bucket, you are mandated to choose a default permission template— Authenticated, or Public. Based on your choice, a default permission template will be loaded, and your bucket will be created. In addition to this, regardless of the permission template you had chosen, you can define the permissions of every individual object or sub-directory as a whole using simple JSON code.

The default permission templates that will be loaded based on your choice are shown below:

Default Authenticated Permission Template

{
    "rules": [
        {
            "rule_id": "AuthenticatedBucket_Rule1",
            "condition": {
                "user": {
                    "auth_type": "authenticated",
                    "zuid": "*"
                }
            },
            "allowed_actions": [
                "GetObject"
            ],
            "paths": [
                "vendorstats::/*"
            ],
            "effect": "allow"
        }
    ],
    "version": "v1"
}

Default Public Permission Template

{
    "rules": [
        {
            "rule_id": "PublicBucket",
            "condition": {
                "user": {
                    "auth_type": "public"
                }
            },
            "actions": [
                "GetObject"
            ],
            "paths": [
                "zylker-bucket-pubs::/*"
            ],
            "effect": "allow"
        }
    ],
    "version": "v1"
}

To effectively edit both the permission templates and employ custom permissions, you need to familiarize yourself with the following JSON keys and their purpose:

Dynamic Variables

You can use dynamic variables to define the object path while configuring permissions. During runtime, these variables will hold relevant values that define the path of the object. In Stratus, you can use the following dynamic variables to define your path:

• X_ZUID: Will hold actual UserIDs during runtime.
• X_ORGID: Will hold actual OrgIDs during runtime.

Syntax to Create Dynamic Variables

You have to employ the syntax shown below to use dynamic variables:

“paths”: [“bucket_name::/${var:X_ZUID}/*”]

“paths”: [“bucket_name::/${var:X_ORGID}/*”]

Syntax to use Dynamic Variables

Let’s look at the following example, where we define the path of the object using the X_ZUID dynamic variable

{
    "version": "v1",
    "rules": [
        {
            "rule_id": "Example rule to allow user to access the path which has their ZUID in the path",
            "condition": {
                "user": {
                    "auth_type": "authenticated",
                    "zuid": "*"
                }
            }
        }
    ],
    "effect": "allow",
    "allowed_actions": [
        "GetObject"
    ],
    "paths": [
        "bucketName::/${var:X_ZUID}"  //Use the X_ORGID variable to define the path using OrgIDs
    ]
}

Examples Illustrating Custom Permissions

Now, let’s go over a few examples of custom permission templates that can be created to define permissions for an object or objects in a bucket.

Example 1

{
 "version" : "v1",
    "rules" : [
  {
   "rule_id" :  "Example rule where all authenticated ZUID users can perform all actions on a particular object",
   "effect"   :  "allow",
   "allowed_actions" : ["GetObject", "PutObject", "DeleteObject"],
   "paths" : ["bucketName::/user/*", "bucketName::/document/readme.md"],
   "condition" : [
    "user" :  {
     "auth_type" : "authenticated",
     "zuid" : "*"
    }
   ]  
  }
 ]
}

From the above snippet, we can understand that:

• The permission is configured for an authenticated permission template bucket

• The permissions will be defined to allow users to perform GetObject, PutObject, and DeleteObject operations.

• This permission is only applicable for all of the objects present in the user/ path and it is applicable only for the readme.md object present in document/ path in the bucket.

• The permission is relevant for all ZUID present.

Putting all this together, we can understand that the above permission is defined for all authenticated users to perform all actions on the readme.md object present in the document/ path, and for all the objects present in the user/ path.

Example 2

{
 "version" : "v1",
"rule" : [
  {
   "rule_id"  : "Example rule to allow user to access the path which has their ZUID in the path",
   "effect" : "allow",
   "allowed_actions" : ["GetObject"],
   "paths" : ["bucketName::/${var:X_Zuid}"],
  }
 ]
}

From the above snippet, we can understand that:

• The path name of the object is defined based on the ZUID, whose value will be attained dynamically during runtime.

• The particular objects in the path will be allowed to perform the GetObject action on the object.

Putting all this together, we can understand that the above permission is defined in a manner where a GetObject action will on the object whose name has to match the ZUID value that will be attained dynamically.

Example 3

{
 "version" : "v1",
"rule" : [
  {
   "rule_id"  : "Example rule to deny specific users from accessing all the objects present in a particular path",
   "effect" : "deny",
   "allowed_actions" : ["GetObject", "PutObject", "DeleteObject"],
   "paths" : ["bucketName::/denyPath/*"],
   "condition" : {
    "user" : {
      "auth_type" : "authenticated",
      "zuid" : ["123", "456", "789"]
     }
   }
  }
 ]
}

From the above snippet, we can understand that:

• The permission applies to what particular authenticated users whose ZUIDs are listed as an array.

• The particular users cannot perform GetObject, PutObject, or DeleteObject actions on all objects present in the bucket.

Putting all this together, we can understand that the above permission is defined for authenticated users with the mentioned ZUIDs. The mentioned users are not allowed to perform any actions on all objects present in the particular path.

Example 4

{
 "version" : "v1",
"rule" : [
  {
  "rule_id"  : "Example rule employing specific action for specific public paths in the bucket",
  "effect" : "allow",
  "allowed_actions" : ["GetObject"],
  "paths" : ["bucketName::/publicPath/*", "bucketName::/otherPath/otherPublicPath/*"],
   "condition" : {
    "user" : {
      "auth_type" : "public",
     }
    }
  },
  {
   "rule_id" : "Example rule where specifc actions can be performed on objects present in specific authenticated path, and these actions can be performed by all authenticated users",
   "effect" : "allow",
   "allowed_actions" : ["GetObject", "PutObject", "DeleteObject"],
   "paths" : ["bucketName::/authenticatedUser/*", "bucketPath::/otherProtectedPath/*"],
   "condition" : {
    "user" : {
     "auth_type" : "authenticated",
     "zuid" : "*"
    }
   }
  }
  ]
}

From the above snippet, we can understand that:

• Two rules are being defined for this bucket. Specific paths in the bucket are listed as public, and specific paths in the bucket can only be accessed by authenticated users.

• GetObject is the only action that can be performed on objects that fall under public path. However, for the objects that are in the authenticated path, and can be accessed by only authenticated users, the actions that are allowed to be performed on the authenticated path are GetObject, PutObject, and DeleteObject.

Putting all this together, we can comprehend that the above permission is defined by two rules. The first rule defines a permission for a path, where all the objects present in the path can be accessed by anyone as it is public. GetObject only action that can be performed on the objects in the public path.

In the second rule, all authenticated users can perform GetObject, PutObject, and DeleteObject actions on all objects listed in the authenticated path.

Example 5

{
    "version" : "v1",
    "rules" : [ 
        {
            "rule_id" : "RuleNumber1",
            "effect" : "allow",
            "allowed_actions" : ["GetObject", "PutObject"],
            "paths" : ["bucketname::/protectedpath/*"],
            "condition" : {
                "user" : {
                    "auth_type" : "authenticated",
                    "zuid" : "*"
                },
                "string_equal" : {
                    "user_agent" : ["Mozilla/5.0"],
                    "referrer" : ["https://www.example.com", "https://www.example.com/get_user/"]
                },
             "ip_address" : {
                    "source_ip" : ["121.67.8.1"]
                }
            }
        },
        {
            "rule_id" : "RuleNumber2",
            "effect" : "deny",
            "allowed_actions" : ["GetObject"],
            "paths" : ["bucketname::/denypath/*"],
            "condition" : {
                "user" : {
                    "auth_type" : "authenticated"
                },
                "string_like" : {
                    "user_agent" : ["PostmanRuntime/7.39.0"]
                }
            }
        },
       {
            "rule_id" : "RuleNumber3",
            "effect" : "allow",
            "allowed_actions" : ["PutObject"],
            "paths" : ["bucketname::/uploadhere/*"],
            "condition" : {
                "user" : {
                    "auth_type" : "authenticated",
                    "org_details" : {
                        "zaaid" : ["12096000001275047", "12096000001278879"]                    }
                },
                "not_ip_address" : {
                    "source_ip" : ["122.23.44.19"]
                }
            }
        }
    ]
}

From the above snippet, we can understand that four rules have been defined — RuleNumber1, RuleNumber2, and RuleNumber3.

• RuleNumber1

  • Object access is only possible if the IP addresses of the system that are attempting access match the values listed in source_ip in the ip_address JSON.
  • Object access is only possible by users whose zaaid (User IDs) matches the ones listed in the org_details JSON.
  • Object access is only possible if the access attempt is made by a Mozilla browser from the web, and only if the access request originates from the mentioned referrers.
  • The rule is defined for all authenticated users.
  • If the access request satisfies all the above mentioned conditions, then only GetObject and PutObject actions are permitted to occur in the defined path.

• RuleNumber2

  • The rule is defined for an authenticated user that attempts an access request with user_agent is Postman (request was made using Postman API platform).
  • In the defined path, such a user will be denied access to perform GetObject operation.

• RuleNumber3

  • The rule is defined in a manner where it is applicable, if the request was made from any IP address except the one mentioned in source_ip in the not_ip_address JSON.
  • The rule is applicable for only authenticated users and specifically to the users whose zaaid are defined in org_details JSON.
  • If the user attempts an access request satisfying all the above mentioned conditions, then they are allowed to perform a PutObject in the defined path.

Configure Custom Permissions for Objects Stored in a Bucket

To set custom permissions:

1. Select the required bucket from the list.
   

2. You will be directed to the Bucket Permissions tab. Click Edit Permission.
   

3. Edit the permissions according to your requirements, then click Update to confirm your changes.
   

The permissions will be applied according to your configurations.