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.