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.
Note:
Both the permission templates are default types that you have to select while you create your bucket. These templates are editable, and you can also edit the permissions of individual objects stored in your bucket.
The permissions that are configured are only applicable to project users and not collaborators.
These permissions are meant to define the access level of end-users and not Collaborators or Administrators. You can define Collaborator’s access level in the Profiles & Permissions section.
Regardless of the permission template you have chosen, upload actions in the bucket can only be performed by authenticated users.
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:
To effectively edit both the permission templates and employ custom permissions, you need to familiarize yourself with the following JSON keys and their purpose:
JSON Key Name
Purpose
rules
This is the JSON key where you configure your permissions
This key will contain all the rules you define for the objects present in the bucket
rule_id
This is a string that will contain the name of the rule you are going to define.
You need to name the rule in a manner you can uniquely identify it.
effect
This is a key where you can only enter one of two values: allow or deny
Based on the value, the rule will be to allow a specific user or users to perform an action, or to deny a specific user or users to deny an action.
The following behaviour is to be expected when you recieve an access request that satisfies conditions present in more than one configured permission statement
Even if one matching statement has the effect as deny then the deny will override all allow statements.
For an allow effect to take place, then atleast one statement with the matching condition should have its effect as allow and none of the statements should have effect as deny.
allowed_actions
This is a key to define the actions that can be performed on the object by the user.
The allowed actions are:
GetObject: To fetch the object data
PutObject: To create, write and update object data
DeleteObject: To delete object data
paths
This key will define the location path of an object.
You will be providing this value in standard file path format. The value needs to be provided as an array.
To denote all the objects present in a subdirectory or a bucket, you can use the asterisk '*' special character.
You can also use Dynamic Variables; X_ZUID and X_ORGID to define the path. These dynamic variables will hold the value of the UserID, and OrgID respectively. So, to use these dynamic variables you need to have defined your directories and objects with actual UserID and OrgID names. Please visit this section to learn more about defining your object path using Dynamic Variables.
condition
This JSON key will define the conditions under which the actions need to occur.
user
This JSON key will be used in the condition key to specify which user, or set of users, does the condition that is being defined apply to.
Will contain two other json keys: auth_type and zuid.
You can define the type of user using the auth_type json key
The auth_type will contain a default value when you create the bucket using a default permission template
The auth_type json key can only contain two values: "public" or "authenticated".
The zuid json key will be used to determine which users do the conditions apply to.
zuid can contain the special character asterisk "*" to mean all ZUIDs qualify for the condition, or can contain an array of ZUIDs to specify which users alone do the conditions apply to.
org_details is a JSON key that will accept a JSON object. The JSON object will be defined as a JSON key value pair, with the key as zaaid, and the value as an array of zuid values.
Note: You can determine access based on user IDs either using zuid values JSON key-value pair or org_details JSON. You cannot use both to define user access.
Operators
These are JSON keys that will help you in defining cases for the conditions to apply or not apply.
string_equals
Dictate actions that need to occur if the string values are equal.
string_not_equals
Define actions that need to occur if the string value does not match.
string_equals_ignore_case
Define actions where the string value can match regardless of the case (upper/lower) that is used.
string_not_equals_ignore_case
Define actions that need to occur if the string values do not match regardless of the case that is used.
string_like
If part of the string value matches with the key you provide, then actions can be performed on the object.
string_not_like
If part of the string value does not match with the key you provide, then actions can be performed on the object.
ip_address
Define an action if the source of the request comes from a particular IP or IPs that you are allowing.
not_ip_address
Define actions that should if the source of the request comes from IP or IPs that you are particularly halting.
Condition Keys
referrer
This JSON key will contain the value of the complete URL where the action was requested. The value needs to be provided as an array. For example, let's say you have created a microservice and you have hosted it on Catalyst AppSail. The value of referrer will be the complete URL of this microservice, and the permission will be defined for actions pertaining to this microservice alone. This key will be used for the following operators:
string_equals
string_not_equals
string_equals_ignore_case
string_not_equals_ignore_case
string_like
string_not_like
user_agent
This JSON key will contain the value of the source from which the request has been made. The value needs to be provided as an array. Whether the source of the request is an API, from a browser, or so on. This key will be used for the following operators:
string_equals
string_not_equals
string_equals_ignore_case
string_not_equals_ignore_case
string_like
string_not_like
source_ip
This JSON key will contain the value of only publicly listed IP addresses. The value needs to be provided as an array. It will help you in defining a permission that allows, or denies actions from a particular IP. This key will be used for the following operators:
ip_address
not_ip_address
version
States the version of the permission template, and will hold the current version value - v1.
We strongly urge that you do not change the value of this key.
Note: Ensure that you are using the exact names for JSON keys to define your permissions.
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.
Note: For dynamic variables to work, you will need to create your object path with either UserIDs or OrgIDs, as the dynamic variables will only hold those values.
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}/*”]
Note:
paths: Will hold the value of the path of the object
bucket_name: Will hold the value of the name of the bucket
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
Define path using the X_ZUID dynamic variable
copy
{
"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
]
}
Note:
It is best to use dynamic variables in buckets where the permission template is set as Authenticated throughout.
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
Custom Permission Example
copy
{
"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
Custom Permission Example
copy
{
"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
Custom Permission Example
copy
{
"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
Custom Permission Example
copy
{
"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.
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:
Select the required bucket from the list.
You will be directed to the Bucket Permissions tab. Click Edit Permission.
Edit the permissions according to your requirements, then click Update to confirm your changes.
The permissions will be applied according to your configurations.
Note: Refer to this help documentation to learn more about custom permissions.
