1 Policy Document Fields
2 Policy Format
3 Principals
4 Request Actions
- 4.1 Policy Actions for Administration (Management API)
- 4.2 Policy Actions for Content (Storage API)
5 Policy Conditions
- 5.1 Referral Condition
- 5.2 Prefix Condition

Best Practice

Each Action domain administrators are allowed to perform can be listed to create a policy for them having broad permissions. It is easier and less error-prone to list the few actions they cannot perform (such as DeleteDomain and CopyDomain) by replacing the entire Action statement with the NotAction statement:

{
   "Version": "2016-10-17",
   "Statement": [
      {
         "Sid": "Grant all except excluded domain operations to admins2",
         "Resource": "/*",
         "Effect": "Allow",
         "Principal": {
            "group": [
               "admins2"
            ]
         },
         "NotAction": [
            "CopyDomain",
            "DeleteDomain"
         ]
      }
   ]
}

Policy Document Fields

Policy documents are JSON-formatted objects.

Field	Sub-field	Description

Field	Sub-field	Description
Version		optional; if used must be "2012-10-17" or "2008-10-17" to match S3
Id		optional name to describe the policy
Statement		a list of rules
	Sid	unique identifier for each statement
	Effect	whether the rule allows or denies an operation
	Principals	defines users and groups to which the rule applies
	Action	content operation (request)
	NotAction	logical inverse of Action; supports all Action values
	Resource	path for which the rule applies; "/" prefix is optional
	Condition	conditional requirements for the request

Policy Example

{
  "Version": "2008-10-17",
  "Id": "Comics-and-Superheros",
  "Statement": [
    {
      "Effect": "Allow",
      "Sid": "1",
      "Principal": {
        "group": [
          "Development",
          "QA",
          "testers@partner.net"
        ],
        "user": [
          "jdoe",
          "gcarlin@funny.com",
          "tony+starkindustries"
        ]
      },
      "Action": [
        "GetObject"
      ],
      "Resource": "/*",
      "Condition": {
        "StringLike": {
          "Referer": [
            "*example.com"
          ]
        }
      }
    }
  ]
}

Policy Format

The format of Gateway's Policy document is modeled after Amazon S3 bucket policies. There is one policy document per tenant, per storage domain, and per bucket. Updating a policy document completely replaces any existing document. The root Policy plus the relevant tenant, storage domain, and bucket policies are all first merged together when evaluating a request.

The policy is a set of rules specifying the conditions under which a request is allowed or denied within the storage API or the management API (such as create a domain, bucket, or object). Each statement in a policy specifies the principals allowed or denied the ability to perform an action on a resource. These are examples of each of these elements of a policy specification.

Principals: user "jdoe", group "Development"
Action: GetObject, DeleteObject
NotAction: CopyDomain, DeleteDomain
Resource: "mybucket/private/*", "mybucket/photos/picture01.jpg"
Condition: "StringLike" : { "Referer" : ["*example.com"]} }
Effect: "Allow", "Deny"

Best Practice

Make the Policy documents as small as reasonable for best performance. Performance is affected because the statements need to be evaluated for each request to check if the resource matches. Choose the most efficient definitions; NotAction lists may be shorter than Action lists.

The Id field is provided for end-user use only and is ignored by the policy evaluation. The Version field is optional and the sole valid value is "2008-10-17" if defined.

Caution

Do not prefix resources with "arn:aws:s3:::" and actions with "s3:" strings. These are ignored by the policy evaluation and negatively impact performance.

Principals

Principals are users or groups to whom the access control statement applies. This includes the specification of an anonymous user that has not authenticated. The format is:

Specifying Authenticated Users

"{user|group}":[{list- of- principals}]

These notation formats are recognized for anonymous principals:

Anonymous Principals

This is an example that includes users and groups from other storage domains and tenants.

Including Users and Groups

See Cross-tenant Access Control below for the meaning of the @domain and +tenantsuffixes for users and groups.

The following table explains the meaning of the different forms of the principal specifications.

Principal	Description

Principal	Description
"anonymous":["*"]	An anonymous, unauthenticated user
"user":["*"]	Any authenticated user from the context’s IDSYS scope
"user":["*@austin"]	Any authenticated user in the ‘austin’ domain’s idsys (or inherited IDSYS if applicable).
"user":["*+texas"]	Any authenticated user in the ‘texas’ tenant’s idsys (or inherited IDSYS if applicable).
"user":["gcarlin"]	A user named 'gcarlin' from this scope's IDSYS (or inherited IDSYS if applicable). This is a non-qualified user name since no domain, tenant, or root scope is specified.
"user":["gcarlin@cars"]	A user named 'gcarlin' from the 'cars' storage domain's IDSYS (or its inherited IDSYS if applicable)
"user":["gcarlin+movies"]	A user named 'gcarlin' from the 'movies' tenant's IDSYS (or its inherited IDSYS if applicable)
"user":["gcarlin@"]	A user named 'gcarlin' only from the root IDSYS
"group":["admins"]	Any member of the group named 'admins' from this scope's IDSYS (or inherited IDSYS if applicable). This is a non-qualified group name since no domain, tenant, or root scope is specified.
"group":["admins@hockey"]	Any member of the group named 'admins' from the 'hockey' storage domain's IDSYS (or its inherited IDSYS if applicable)
"group":["admins+sports"]	Any member of the group named 'admins' from the 'sports' tenant's IDSYS (or its inherited IDSYS if applicable)
"group":["admins@"]	Any member of the group named 'admins' only from the root IDSYS

In many cases it is unnecessary to explicitly grant permissions to the user named by the X-Owner-Meta header, of a tenant, storage domain, or bucket because they are granted permission for all operations by default. This default permission means that careful consideration should be given when assigning ownership to another user — especially for tenants or storage domains.

User and group principals can be written as fully-qualified or non-qualified within Policy documents. A fully-qualified principal is one that defines the domain, tenant, or root scope (example: "gcarlin@cars"). A non-qualified principal does not include the scope for the principal (example: "gcarlin"). The scope of a principal defined the starting point for looking for the first available IDSYS definition with which to look for the principal. The starting point for the IDSYS search starts from the point of the resource being requested if the principal is non-qualified.

The IDSYS precedence model allows the root scope to be overridden by the tenant and the domain scopes. The search order when looking for the first available IDSYS is to search backwards from domain to tenant to root. The Gateway looks for the first IDSYS that is defined at the domain, then the tenant, then at the root if a group is specified as "admins@hockey" for requests within the "hockey" storage domain. The group "admins" from only that IDSYS are used upon finding the first IDSYS definition.

Request Actions

Policy documents are used to control actions with both the Management API and the Storage API. The policy actions that apply to a given request depends upon the API being used, management or storage. The list of Policy documents that are merged together for policy evaluation is determined by the path in the API hierarchy being accessed.

Request actions are included in the Effect field result when listed within an Action field. The listed actions are explicitly denied if the effect is "Deny". Request actions are excluded from the Effect field results when listed within a NotAction field. All actions other than those listed are explicitly denied if the effect is "Deny".

Policy Actions for Administration (Management API)

These are the Management API actions that can be controlled within a Policy document and the applicable scope where the actions are used. If an action is granted or denied within a scope where not applicable, it has no effect.

Scope indicates where the policy action is applicable: (R) root, (T) tenant, (D) domain, (B) bucket.

Manage	Action	Scope	Description

Manage	Action	Scope	Description
Global	*	R,T,D,B	all actions
Tenants	ListTenants	R	List all tenants
	CreateTenant	R	Create a new or change an existing tenant
	GetTenant	R,T	Retrieve tenant properties
	DeleteTenant	R,T	Permanently remove tenant properties
	ListEtc	R,T	List documents associated with a tenant
Domains	ListDomains	R,T	List the domains owned by the _system tenant
	CreateDomain	R,T	Create a domain for the _system tenant
	GetDomain	R,T,D	GET a domain
	DeleteDomain	R,T,D	Delete a domain
Policies	ListEtc	R,T,D	List documents associated with a tenant or a storage domain
	PutPolicy	R,T,D	Create or update an access control policy JSON document
	GetPolicy	R,T,D	Read an access control policy JSON document
	DeletePolicy	R,T,D	Permanently remove an access control policy JSON document

Authentication Tokens	TokenAdmin	R,T,D	Create and list authorization tokens for other users in the same scope
	CreateToken	R,T,D	Create an authentication token
	ListTokens	R,T,D	List user authentication tokens
	ValidateToken	R,T,D	Read an authentication token
	DeleteToken	R,T,D	Delete an authentication token

Policy Actions for Content (Storage API)

This table defines the Storage SCSP API actions that can be controlled within a Policy document and the applicable scope where the actions are used. An action has no effect if granted or denied within a scope where not applicable.

See http://docs.aws.amazon.com/AmazonS3/latest/dev/using-with-s3-actions.html in the AWS documentation for Amazon S3 operation permissions.

Scope indicates where the policy action is applicable: (R) root, (T) tenant, (D) domain, (B) bucket.

Storage	Action	Scope	Description

Storage	Action	Scope	Description
Global	*	R,T,D,B	all actions
Quotas	PutQuota	R,T,D,B	Create or update quota configuration settings on a tenant, domain, or bucket. This is not granted by "*"; it must be granted explicitly.
Quotas	GetQuota	R,T,D,B	Retrieve quota configuration settings on a tenant, domain, or bucket. This is not granted by "*"; it must be granted explicitly.
Objects	GetObject	R,T,D,B	Retrieve an object and its metadata
	GetObjectAcl	R,T,D,B	Retrieve the Access Control List (ACL) settings on an object
	CreateObject	R,T,D,B	Add a new object and metadata to a domain (unnamed) or bucket (named). There is no S3 equivalent, and it is permissioned separately here because Swarm distinguishes POST and PUT.
	AppendObject	R,T,D,B	Append to an object
	CopyObject	R,T,D,B	Update metadata on an object while keeping the same object name
	PutObject	R,T,D,B	Update an object PutObject, unlike S3, is for overwriting an existing object, not creating new one (CreateObject).
	PutObjectAcl	R,T,D,B	Set an object's access control list
	DeleteObject	R,T,D,B	Permanently remove an object and its metadata
Buckets	CreateBucket	R,T,D	Create a bucket
	PutBucket	R,T,D	Synonym for CreateBucket
	PutBucketAcl	R,T,D	Set bucket access control list
	PutBucketCORS	R,T,D,B	Set CORS configuration on a bucket
	GetBucket	R,T,D,B	GET or HEAD a bucket
	GetBucketAcl	R,T,D,B	Get bucket access control list
	GetBucketCORS	R,T,D,B	Get CORS configuration on a bucket
	CopyBucket	R,T,D,B	Update the metadata on a bucket while keeping the same bucket name
	DeleteBucket	R,T,D,B	Delete a bucket
	ListBucket	R,T,D,B	List and search the objects contained in a bucket
Bucket Sub-Resources	PutPolicy	R,T,D,B	Create or update a policy, xform, sub-resource for a bucket. While an owner of bucket can always overwrite the policy, this allows a group to be granted this permission.
	GetPolicy	R,T,D,B	GET or HEAD the policy, xform, sub-resource for a bucket
	DeletePolicy	R,T,D,B	Permanently remove a policy, xform, sub-resource for a bucket
Domains	CreateDomain	R *	Create a domain
	GetDomain	R,T,D	GET or HEAD a domain
	CopyDomain	R,T,D	Update the metadata on a domain while keeping the same domain name
	DeleteDomain	R,T,D	Permanently remove a domain
	ListDomain	R,T,D	List and search all objects (buckets and unnamed objects) within the domain
	ListDomains	R *	List all domains that exist in the cluster
Domain Sub-Resources	PutPolicy	R,T,D	Create or update a policy, xform, idsys, sub-resource for a domain
	GetPolicy	R,T,D	GET or HEAD policy, xform, idsys, sub-resource for a domain
	DeletePolicy	R,T,D	Permanently remove a policy, xform, idsys, sub-resource from a domain
Authentication Tokens	CreateToken	R,T,D	Add a new authentication token
	ListTokens	R,T,D	Search for and list authentication tokens
	ValidateToken	R,T,D	Read and verify an authentication token
	DeleteToken	R,T,D	Permanently remove an authentication token

Policy Conditions

The Condition field of the Policy document allows for conditions other than user and action to be placed upon the request.

Conditionals in a Policy document allow for the value matching functions:

StringEqualsIgnoreCase matching is an exact match ignoring letter case.
StringLike matching allows for glob-style pattern matching for the values and ignores letter case.

All matching conditionals are evaluated on each request similar to the way paths are matched to resources.

Referral Condition

Gateway supports conditional requirements on the value of the HTTP/1.1 Referer header.

The Referer header is commonly provided by web browsers when retrieving content referenced by an HTML document. While the browser, or HTTP client library, is free to provide any value they wish for this header, it is commonly used to detect the source reference for a resource request. The following logical evaluation takes place for the referral matching condition:

Policy statements without Referer conditions are considered for authorization if there is no Referer header in the request.
Policy statements without Referer conditions are considered for authorization if there is a Referer header in the request.
The policy statement is considered for authorization if the values match if there is a Referer header in the request and there are policy statements with Referer conditions. Values are matched as follows:
- The condition matches if any value matches for the condition-key if there are multiple values in a conditional value list. It is a logical OR match.
- All conditions must match if there are multiple condition-types in a condition-block. It is a logical AND match.

Rules that match a request are chosen from available rules according to Resource, Action, referral Conditions as described. Among those rules, further filtering is performed by Principal and lastly according to deny/apply semantics. Note: referral conditions are processed in all actions.

This example shows a conditional restriction that the Referer value must be example.com or another.com.

This example shows a conditional restriction that uses the StringLike match to restrict the Referer value to any subdomain within a parent domain.

While Referer header restrictions are commonly used to prevent bandwidth stealing due to cross-linking by unaffiliated web sites, the requesting client is being trusted to accurately populate this header. Referer header restrictions work well to prevent unauthorized cross-linking, this is not a mechanism to be relied upon to provide site security.

Prefix Condition

Gateway supports conditional requirements on the prefix match. This can be used to require object searching be constrained to a set of prefix patterns.

This is an example of a policy that only allows the listing of objects if a prefix query argument is specified.

Allowed: GET /usersbucket?format=json&prefix=home/Shared/
Denied: GET /usersbucket?format=json&prefix=home/Shared