Control OSS bucket and directory access with RAM policies-Object Storage Service(OSS)-阿里云帮助中心

Configure fine-grained access control for OSS buckets, directories, and objects using RAM policies. Learn how the flat storage model and prefix-based listing affect policy design, and how to grant directory-level permissions to different RAM users.

Storage structure and authorization

OSS storage model

OSS uses a flat storage model to store objects as key-value pairs. All objects belong directly to a bucket, and no physical directory hierarchy exists. The 'directories' displayed in the console are created by using the prefixes of object keys and a delimiter (/) to simulate a folder hierarchy.

For the bucket examplebucket, the console displays the following directory structure and object keys:

examplebucket
├── Development/                     # Key: Development/ (directory object)
│   ├── Alibaba Cloud.pdf            # Key: Development/Alibaba Cloud.pdf
│   ├── ProjectA.docx                # Key: Development/ProjectA.docx
│   └── ProjectB.docx                # Key: Development/ProjectB.docx
├── Marketing/                       # Key: Marketing/ (directory object)
│   ├── data2020.xlsx                # Key: Marketing/data2020.xlsx
│   └── data2021.xlsx                # Key: Marketing/data2021.xlsx
├── Private/                         # Key: Private/ (directory object)
│   └── 2017/                        # Key: Private/2017/ (directory object)
│       ├── images.zip               # Key: Private/2017/images.zip
│       └── promote.pptx             # Key: Private/2017/promote.pptx
└── oss-dg.pdf                       # Key: oss-dg.pdf

A directory object's key ends with /. OSS uses this suffix to identify directories. In storage, all objects, including directory objects, are stored flat.

Because OSS has no true directory hierarchy, granting access to a 'directory' means granting access to all objects with a specific prefix. For example, granting access to the Development/ directory is equivalent to granting access to all objects whose keys start with Development/.

Bucket, directory, and object request differences

Different operations require different API requests and Resource configurations.

ListObjects request mechanism

The console displays a directory-like structure by using two parameters of the GetBucket (ListObjects) API operation:

Parameter	Description	Example value
`prefix`	Restricts the response to include only objects whose keys begin with the specified prefix.	`Development/`
`delimiter`	The character for grouping objects, typically `/`.	`/`

Clicking the Development/ folder in the console sends this request to OSS:

GET /?prefix=Development/&delimiter=/ HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com

OSS returns all objects that start with Development/. Because delimiter=/ is specified, OSS returns subdirectories (such as Development/SubFolder/) as CommonPrefixes instead of listing all files within them.

`Resource` configuration

Operation target	Triggered API	`Resource` configuration	Policy configuration points
List the root directory of a bucket	ListObjects, prefix is empty, delimiter is `/`	`acs:oss:::examplebucket`	`Resource` points to the bucket itself, not a specific path.
Enter a directory	ListObjects, where prefix is `folder_name/` and delimiter is `/`	`acs:oss:::examplebucket`	`Resource` refers to the bucket, not a path. The `oss:Prefix` condition restricts the listable scope.
Read and write file content	GetObject, PutObject	`acs:oss:::examplebucket/directory_name/*`	The Resource can be specified down to a path and supports the wildcard `*`.

Console vs. API/SDK access

Console access requires navigating from the bucket list to the target directory, which needs more permissions than direct API or SDK calls.

Access method	Required permissions
API/SDK	Only target resource permissions are required, such as `oss:GetObject`.
Console	Target resource permissions plus auxiliary permissions such as `oss:ListBuckets` (list buckets) and `oss:GetBucketInfo` (display bucket details).

Scenario

Assume that the default read/write ACL for all files in the bucket examplebucket is private. The bucket structure is as follows:

examplebucket
├── Development/           # Development directory
│   ├── Alibaba Cloud.pdf
│   ├── ProjectA.docx
│   └── ProjectB.docx
├── Marketing/             # Marketing directory
│   ├── data2020.xlsx
│   └── data2021.xlsx
├── Private/               # Confidential directory
│   └── 2017/
│       ├── images.zip
│       └── promote.pptx
└── oss-dg.pdf

Access control objectives:

RAM user/user group	Authorization target	Permission type
RAM user Anne	`Development/` folder and all its files	Read-write
RAM user Leo	The `Marketing/` folder and all its files	Read-only
All members of a specific user group	The `Private/` directory and all its files	Deny access

Step 1: Create a bucket and upload objects

Go to the Bucket List and Create Bucket, such as examplebucket.
In the bucket, Create Directory: Development, Marketing, and Private (and create a subdirectory 2017 under Private).
Click Upload Object to upload objects to the following paths:
- Root directory: oss-dg.pdf
- Development/ directory: Alibaba Cloud.pdf, ProjectA.docx, ProjectB.docx
- Marketing/ directory: data2020.xlsx, data2021.xlsx
- Private/2017/ directory: images.zip, promote.pptx

Step 2: Create RAM users Anne and Leo

Go to the Users page in the RAM console and click Create User to create the users Anne and Leo.

Step 3: Grant read-write access to the Development directory

Policy design

Read/write access to Development/ requires two permission types:

List permission: List objects in Development/ (oss:ListObjects), with a Condition that restricts listing to the Development prefix.
Read/write permissions: Read and upload files in Development/ (oss:GetObject, oss:PutObject), with Resource set to examplebucket/Development/*.

Create and attach a policy

Go to the Policies page in the RAM console and click Create Policy.

On the JSON tab, enter the following policy document:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "oss:ListObjects",
      "Resource": "acs:oss:*:*:examplebucket",
      "Condition": {
        "StringLike": {
          "oss:Prefix": [
            "Development",
            "Development/*"
          ]
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetObject",
        "oss:PutObject",
        "oss:GetObjectAcl"
      ],
      "Resource": "acs:oss:*:*:examplebucket/Development/*"
    }
  ]
}

Policy analysis:

First statement: Grants list permission on the bucket, using Condition with oss:Prefix to restrict listing to the Development directory and subdirectories.
Second statement: Grants read/write access to all objects under Development/*.

Click OK, enter a Policy Name (such as AllowAnneAccessDevelopment), and click OK to complete the creation.
Go to the Users page, find the RAM user Anne, and add permissions by attaching the newly created policy.

Step 4: Grant read-only access to the Marketing directory

Create and attach a read-only policy for RAM user Leo using the same procedure as Step 3. This policy includes only read operations in Action:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "oss:ListObjects",
      "Resource": "acs:oss:*:*:examplebucket",
      "Condition": {
        "StringLike": {
          "oss:Prefix": [
            "Marketing",
            "Marketing/*"
          ]
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetObject",
        "oss:GetObjectAcl"
      ],
      "Resource": "acs:oss:*:*:examplebucket/Marketing/*"
    }
  ]
}

Because oss:PutObject is excluded from Action, Leo can read files but cannot upload or modify them.

Step 5: Deny access to the Private directory

Add RAM users who should not access the Private/ folder to a user group, then attach a deny policy to the group.

Note

This applies only to group members. To deny access for all RAM users in your account, including future ones, use a bucket policy instead.

Create a user group and add members

Go to the RAM user group list and click Create User Group (such as DenyPrivateAccessGroup).
Click Add Group Members, and add the RAM users who need to be denied access to the Private/ folder to the user group.

Create and attach a deny policy

Go to the Policies page in the RAM console and click Create Policy.

On the JSON tab, enter the following policy document:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Deny",
      "Action": "oss:*",
      "Resource": "acs:oss:*:*:examplebucket/Private/*"
    },
    {
      "Effect": "Deny",
      "Action": "oss:ListObjects",
      "Resource": "acs:oss:*:*:examplebucket",
      "Condition": {
        "StringLike": {
          "oss:Prefix": [
            "Private/",
            "Private/*"
          ]
        }
      }
    }
  ]
}

Policy analysis:

First statement: Denies all operations on objects under Private/.
Second statement: Denies listing Private/ contents, preventing users from viewing the file list.

Click OK, enter a Policy Name (such as DenyAccessPrivateFolder), and click OK to complete the creation.
Go to the Groups page, find the user group, and add permissions by attaching the policy that you just created.

If a group member attempts to list or download files in the Private/ folder, OSS returns a permission denied error.

Control OSS access with RAM policies

Storage structure and authorization

OSS storage model

Bucket, directory, and object request differences

ListObjects request mechanism

`Resource` configuration

Console vs. API/SDK access

Scenario

Step 1: Create a bucket and upload objects

Step 2: Create RAM users Anne and Leo

Step 3: Grant read-write access to the Development directory

Policy design

Create and attach a policy

Step 4: Grant read-only access to the Marketing directory

Step 5: Deny access to the Private directory

Create a user group and add members

Create and attach a deny policy

Related documents

Storage structure and authorization

OSS storage model

Bucket, directory, and object request differences

ListObjects request mechanism

Resource configuration

Console vs. API/SDK access

Scenario

Step 1: Create a bucket and upload objects

Step 2: Create RAM users Anne and Leo

Step 3: Grant read-write access to the Development directory

Policy design

Create and attach a policy

Step 4: Grant read-only access to the Marketing directory

Step 5: Deny access to the Private directory

Create a user group and add members

Create and attach a deny policy

Related documents

`Resource` configuration