Use access points for fine grained access control - Object Storage Service

To manage access for multiple applications or teams that require different permissions for the same bucket, you can create a separate access point for each. This approach uses a dedicated access point policy for each entity, avoiding the complexity of a single, intricate bucket policy.

How it works

An access point acts as a proxy layer for bucket access. When you create an access point, Object Storage Service (OSS) generates a unique access point alias that you use instead of the bucket name in your requests. Each access point can be configured with its own access point policy, which defines the allowed actions, resources, and identities, and a network origin (internet or a specific Virtual Private Cloud (VPC)), enabling isolated access based on your use case.

When you make a request through an access point, the system evaluates three types of policies: RAM Policy, Bucket Policy, and AP Policy. A request is allowed only if the combined result of the RAM Policy and Bucket Policy is Allow, and the AP Policy is also Allow. For details about the permission evaluation logic, see Permission evaluation logic.

By default, an access point cannot access bucket resources. You must first configure permission delegation in the bucket policy by using the oss:DataAccessPointArn, oss:DataAccessPointAccount, or oss:AccessPointNetworkOrigin condition keys to explicitly authorize specific access points to access the bucket.

Quick start

This section guides you through the three steps to get started with access points: creating an access point, configuring permission delegation, and using an access point to access resources.

Step 1: Create an access point

Create an access point and configure its policy to define "which identities" can perform "what actions" on "which OSS resources" under "what conditions".

Go to the Access Points list and click Create Access Point.
Enter an Access point name, select the associated bucket and network origin, and then click Next.
Note
- If you set Network origin to VPC, you must enter a VPC ID. You can obtain the ID from the VPC console.
- The region of the specified VPC must be a region that supports OSS gateway endpoints. A region mismatch prevents authentication requests from being correctly associated with the VPC, which causes authentication to fail.

Turn off the block public access option and configure the access point policy.

Visual editor

Parameter	Description
Applied To	Select whether to grant permissions on the Whole Bucket or Specific Resources.
Resource Paths	If you select Applied To for Whole Bucket, the Resource Paths is `accesspoint/{access-point-name}/`. If you select Applied To* for Specific Resources, enter the directory or individual object. You can add multiple entries.
Authorized User	Specify the identity to be granted permissions. RAM user: Select a RAM user under the current Alibaba Cloud account. To view the list of RAM users for the current account, the logged-in account must be an Alibaba Cloud account or a RAM user with management permissions for this bucket and the `ListUsers` permission for the Resource Access Management (RAM) console. Other accounts: Enter the UID of another account or RAM user, or a temporary user ARN that starts with `arn:sts` (for example, `arn:sts::1798************:assumed-role/role-name/session-name`). You can authorize multiple users, with one entry per line.
Authorized Operation	Simple settings: Select from common combinations of permissions. Options include Read-Only (excluding ListObject), Read-Only (including ListObject), Read/Write, Full Access, and Deny Access. Advanced settings: Customize the Effect (Allow or Reject) and the authorized actions.

JSON editor

Enter the policy in JSON format in the editor.

Example policy: Grant read/write permissions to user 20816353761158****.

{
  "Version": "1",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "oss:GetObject",
      "oss:PutObject",
      "oss:GetObjectAcl",
      "oss:PutObjectAcl",
      "oss:ListObjects",
      "oss:AbortMultipartUpload",
      "oss:ListParts",
      "oss:RestoreObject",
      "oss:ListObjectVersions",
      "oss:GetObjectVersion",
      "oss:GetObjectVersionAcl",
      "oss:RestoreObjectVersion"
    ],
    "Principal": [
      "20816353761158****"
    ],
    "Resource": [
      "acs:oss:{region-id}:179882766168****:accesspoint/{ap-name}/object/*"
    ]
  }, {
    "Effect": "Allow",
    "Action": [
      "oss:ListObjects",
      "oss:GetObject"
    ],
    "Principal": [
      "20816353761158****"
    ],
    "Resource": [
      "acs:oss:{region-id}:179882766168****:accesspoint/{ap-name}"
    ],
    "Condition": {
      "StringLike": {
        "oss:Prefix": [
          "*"
        ]
      }
    }
  }]
}

A complete policy includes a Version and one or more Statement elements.

Version: The policy version. This is fixed at 1 and cannot be changed.

Statement: The main body of the policy, which contains one or more rules that grant or deny permissions. Each statement includes an effect, action, principal, resource, and condition.

Policy element	Description
Effect	The effect of the policy, which can be `Allow` or `Deny`.
Action	The specific operations to be performed on the resource. Wildcard characters (`*`) are supported.
Principal	The identity (for example, a user, account, or role) to which the policy applies.
Resource	The resources to which the policy applies.
Condition	The conditions that must be met for the policy to take effect. When multiple conditions are configured, all conditions must be met (an AND relationship) for the policy to take effect.

For a complete list of authorization elements, see Policy syntax and structure.

Click Submit and wait for the access point to be created.

Step 2: Delegate permissions

After creating an access point, you must also create a bucket policy to delegate permissions. This policy defines which access points can access the bucket. There are three types of permission delegation for access points:

oss:DataAccessPointArn: Delegates access permissions for a specific access point.
oss:DataAccessPointAccount: Delegates access permissions for all access points under the current account.
oss:AccessPointNetworkOrigin: Delegates access permissions for all access points from a specified network origin.

Delegate to specific access point

Go to the Buckets list and click the target bucket.
In the navigation pane on the left, click Permissions > > Bucket Policy, and then select Add by Policy Syntax.

Click Edit and enter the policy in JSON format in the editor.

Note

When configuring, replace the UID, bucket name, region ID, and access point name in the example with your own values. If the bucket policy is not empty, add the Statement element to the existing policy.

{
  "Version": "1",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "oss:*"
    ],
    "Principal": [
      "*"
    ],
    "Resource": [
      "acs:oss:*:179882766168****:example-bucket",
      "acs:oss:*:179882766168****:example-bucket/*"
    ],
    "Condition": {
      "StringEquals": {
        "oss:DataAccessPointArn": [
          "acs:oss:oss-{region-id}:179882766168****:accesspoint/{ap-name}"
        ]
      }
    }
  }]
}

Click Save to complete the bucket policy configuration.

Delegate to all access points

Go to the Buckets list and click the target bucket.
In the navigation pane on the left, click Permissions > > Bucket Policy, and then select Add by Policy Syntax.

Click Edit and enter the policy in JSON format in the editor.

Note

When configuring, replace the UID and bucket name in the example with your own values. If the bucket policy is not empty, add the Statement element to the existing policy.

{
  "Version": "1",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "oss:*"
    ],
    "Principal": [
      "*"
    ],
    "Resource": [
      "acs:oss:*:179882766168****:example-bucket",
      "acs:oss:*:179882766168****:example-bucket/*"
    ],
    "Condition": {
      "StringEquals": {
        "oss:DataAccessPointAccount": [
          "179882766168****"
        ]
      }
    }
  }]
}

Click Save to complete the bucket policy configuration.

Delegate by network origin

Go to the Buckets list and click the target bucket.
In the navigation pane on the left, click Permissions > > Bucket Policy, and then select Add by Policy Syntax.
Click Edit and enter the policy in JSON format in the editor.
Note
- When configuring, replace the UID and bucket name in the example with your own values. If the bucket policy already contains content, add the new element to the Statement array in the existing policy.
- When oss:AccessPointNetworkOrigin is set to internet, permissions are delegated to all access points with a network origin of Internet. This configuration allows access from both the public internet and VPCs. To restrict access to VPCs only, change this value to vpc.
```
{
  "Version": "1",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "oss:*"
    ],
    "Principal": [
      "*"
    ],
    "Resource": [
      "acs:oss:*:179882766168****:example-bucket",
      "acs:oss:*:179882766168****:example-bucket/*"
    ],
    "Condition": {
      "StringEquals": {
        "oss:AccessPointNetworkOrigin": [
          "internet"
        ]
      }
    }
  }]
}
```
Click Save to complete the bucket policy configuration.

Note

If you receive a message indicating "The bucket policy contains public access semantics," turn off the block public access option for the bucket before delegating permissions to the access point.

Step 3: Access resources via access point

When you create an access point, OSS automatically generates an access point alias. An authorized identity, such as a RAM user, can then use this alias to access the corresponding OSS resources.

Compatible APIs

API	Description
PutAccessPointPolicy	Configures an access point policy.
GetAccessPointPolicy	Retrieves the configuration of an access point policy.
DeleteAccessPointPolicy	Deletes an access point policy.
ListObjects (GetBucket)	Lists information about all objects in a bucket.
ListObjectsV2 (GetBucketV2)	Lists information about all objects in a bucket.
ListObjectVersions (GetBucketVersions)	Lists all versions of objects in a bucket, including delete markers.
PutObject	Uploads an object.
GetObject	Retrieves an object.
CopyObject	Copies an object.
AppendObject	Uploads an object by appending data.
DeleteObject	Deletes a single object.
DeleteMultipleObjects	Deletes multiple objects.
HeadObject	Retrieves an object's metadata without its content.
GetObjectMeta	Returns partial metadata of an object, including its ETag, Size, and LastModified, without returning its content.
PostObject	Uploads an object by using an HTML form.
RestoreObject	Restores an object of the Archive, Cold Archive, or Deep Cold Archive storage class.
SelectObject	Executes an SQL statement on a target object and returns the result.
InitiateMultipartUpload	Initializes a multipart upload event.
UploadPart	Uploads a part based on the specified object name and upload ID.
UploadPartCopy	Copies data from an existing object to upload a part by calling the `UploadPart` operation with the `x-oss-copy-source` request header.
CompleteMultipartUpload	After uploading all parts, call this operation to complete the multipart upload.
AbortMultipartUpload	Cancels a multipart upload and deletes its parts.
ListMultipartUploads	Lists all multipart upload events that are in progress, meaning they have been initiated but not yet completed or aborted.
ListParts	Lists all successfully uploaded parts for a specified upload ID.
PutObjectACL	Modifies the access permissions of an object.
GetObjectACL	Views the access permissions of an object.
PutSymlink	Creates a symbolic link.
GetSymlink	Retrieves a symbolic link.
PutObjectTagging	Sets or updates object tags.
GetObjectTagging	Retrieves object tag information.
DeleteObjectTagging	Deletes specified object tags.

SDK

Currently, only the Java SDK and Python SDK support accessing OSS resources by using access point aliases.

Java

import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.StaticCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.GetObjectRequest;

import java.io.File;

/**
 * This is an OSS Java SDK v2 example that shows how to download an object to a local file by using an access point.
 */
public class DownloadObjectWithAccessPoint {

    public static void main(String[] args) {
        // Create an OSS client.
        String accessKeyId = System.getenv("OSS_ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");
        CredentialsProvider provider = new StaticCredentialsProvider(accessKeyId, accessKeySecret);
        OSSClient client = OSSClient.newBuilder()
                .credentialsProvider(provider)
                .region("<region-id>")
                .build();

        // Download an object to a local file by using an access point alias.
        String bucket = "example-ap-b156d01070a10322664d6704cd1d47****-ossalias";
        String key = "example.jpg";
        File file = new File("example.jpg");
        client.getObjectToFile(GetObjectRequest.newBuilder()
                .bucket(bucket)
                .key(key)
                .build(), file);
        System.out.println("File downloaded: " + key + " -> " + file.getPath());

        // Close the client.
        try {
            client.close();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Python

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""This is an OSS Python SDK v2 example that shows how to download an object to a local file by using an access point."""

import alibabacloud_oss_v2 as oss


def main() -> None:
    """The main function."""
    # Create an OSS client.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
    config = oss.config.load_default()
    config.credentials_provider = credentials_provider
    config.region = "<region-id>"
    config.endpoint = "oss-<region-id>.aliyuncs.com"
    client = oss.Client(config)

    # Download an object to a local file by using an access point alias.
    bucket = "example-ap-b156d01070a10322664d6704cd1d47****-ossalias"
    key = "example.jpg"
    file_path = "example.jpg"
    request = oss.GetObjectRequest(bucket, key)
    client.get_object_to_file(request, file_path)
    print(f"File downloaded: {key} -> {file_path}")


if __name__ == "__main__":
    main()

ossutil

When using ossutil to access OSS resources, use the access point alias as the bucket name.

ossutil cp oss://example-ap-b156d01070a10322664d6704cd1d47****-ossalias/example.jpg /tmp

REST API

When using the REST API to access OSS resources, use the access point alias in the Host header. The following is an example:

GET /ObjectName HTTP/1.1
Host: example-ap-b156d01070a10322664d6704cd1d47****-ossalias.oss-{region-id}.aliyuncs.com 
Date: GMT Date
Authorization: SignatureValue

Use case

The following example shows how to design an access point solution for a big data analytics scenario, enabling secure, isolated access for multiple departments through fine-grained permission control.

Scenario

A company with the Alibaba Cloud account UID 137918634953**** stores centrally collected data in a bucket named examplebucket. Ten business departments must access this bucket with the following requirements:

Department	Access scope	Permissions	Network origin
Departments 1–3	`dir1/` directory	Read-only	Internet
Department 4	Entire bucket	Read/Write	Internet
Departments 5–10	`dir2/` directory	Read/Write	VPC only

Solution design

Based on the business isolation and security requirements, this solution uses three access points for different access scenarios. Access point policies are used to implement precise permission control and network access restrictions.

Access point	Name	Network origin	Authorized users	Authorized resources	Permissions
Access Point 1	`ap-01`	Internet	RAM users from departments 1–3 (UID: `26571698800555****`)	`dir1/*`	Read-only
Access Point 2	`ap-02`	Internet	RAM user from department 4 (UID: `25770968794578****`)	`*` (Entire bucket)	Read/Write
Access Point 3	`ap-03`	VPC	RAM users from departments 5–10 (UID: `26806658794579****`)	`dir2/*`	Read/Write

AP policy configuration

ap-01: Read-only

{
  "Version": "1",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "oss:GetObject",
      "oss:GetObjectAcl",
      "oss:ListObjects",
      "oss:RestoreObject",
      "oss:ListObjectVersions",
      "oss:GetObjectVersion",
      "oss:GetObjectVersionAcl",
      "oss:RestoreObjectVersion"
    ],
    "Principal": [
      "26571698800555****"
    ],
    "Resource": [
      "acs:oss:{region-id}:137918634953****:accesspoint/ap-01/object/dir1/*"
    ]
  },{
    "Effect": "Allow",
    "Action": [
      "oss:ListObjects",
      "oss:GetObject"
    ],
    "Principal": [
      "26571698800555****"
    ],
    "Resource": [
      "acs:oss:{region-id}:137918634953****:accesspoint/ap-01"
    ],
    "Condition": {
      "StringLike": {
        "oss:Prefix": [
          "dir1/*"
        ]
      }
    }
  }]
}

ap-02: Read/write

{
  "Version": "1",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "oss:GetObject",
      "oss:PutObject",
      "oss:GetObjectAcl",
      "oss:PutObjectAcl",
      "oss:ListObjects",
      "oss:AbortMultipartUpload",
      "oss:ListParts",
      "oss:RestoreObject",
      "oss:ListObjectVersions",
      "oss:GetObjectVersion",
      "oss:GetObjectVersionAcl",
      "oss:RestoreObjectVersion"
    ],
    "Principal": [
      "25770968794578****"
    ],
    "Resource": [
      "acs:oss:{region-id}:137918634953****:accesspoint/ap-02/object/*"
    ]
  },{
    "Effect": "Allow",
    "Action": [
      "oss:ListObjects",
      "oss:GetObject"
    ],
    "Principal": [
      "25770968794578****"
    ],
    "Resource": [
      "acs:oss:{region-id}:137918634953****:accesspoint/ap-02"
    ],
    "Condition": {
      "StringLike": {
        "oss:Prefix": [
          "*"
        ]
      }
    }
  }]
}

ap-03: VPC read/write

{
  "Version": "1",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "oss:GetObject",
      "oss:PutObject",
      "oss:GetObjectAcl",
      "oss:PutObjectAcl",
      "oss:ListObjects",
      "oss:AbortMultipartUpload",
      "oss:ListParts",
      "oss:RestoreObject",
      "oss:ListObjectVersions",
      "oss:GetObjectVersion",
      "oss:GetObjectVersionAcl",
      "oss:RestoreObjectVersion"
    ],
    "Principal": [
      "26806658794579****"
    ],
    "Resource": [
      "acs:oss:{region-id}:137918634953****:accesspoint/ap-03/object/dir2/*"
    ]
  },{
    "Effect": "Allow",
    "Action": [
      "oss:ListObjects",
      "oss:GetObject"
    ],
    "Principal": [
      "26806658794579****"
    ],
    "Resource": [
      "acs:oss:{region-id}:137918634953****:accesspoint/ap-03"
    ],
    "Condition": {
      "StringLike": {
        "oss:Prefix": [
          "dir2/*"
        ]
      }
    }
  }]
}

Bucket policy delegation

Since this scenario involves multiple access points under the same account, we recommend using oss:DataAccessPointAccount for unified delegation. This approach simplifies the bucket policy configuration. For more granular control, you can also use oss:DataAccessPointArn to delegate permissions to each access point individually.

Unified delegation

{
  "Version": "1",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "oss:*"
    ],
    "Principal": [
      "*"
    ],
    "Resource": [
      "acs:oss:*:137918634953****:examplebucket",
      "acs:oss:*:137918634953****:examplebucket/*"
    ],
    "Condition": {
      "StringEquals": {
        "oss:DataAccessPointAccount": [
          "137918634953****"
        ]
      }
    }
  }]
}

Individual delegation

{
  "Version": "1",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "oss:*"
    ],
    "Principal": [
      "*"
    ],
    "Resource": [
      "acs:oss:*:137918634953****:examplebucket",
      "acs:oss:*:137918634953****:examplebucket/*"
    ],
    "Condition": {
      "StringEquals": {
        "oss:DataAccessPointArn": [
          "acs:oss:oss-{region-id}:137918634953****:accesspoint/ap-01",
          "acs:oss:oss-{region-id}:137918634953****:accesspoint/ap-02",
          "acs:oss:oss-{region-id}:137918634953****:accesspoint/ap-03"
        ]
      }
    }
  }]
}

Permission evaluation logic

RAM and bucket policy	Access point policy	Final result
Allow	Allow	Allow
Allow	Deny	Deny
Allow	Ignore	Ignore
Deny	Allow	Deny
Deny	Deny	Deny
Deny	Ignore	Deny
Ignore	Allow	Ignore
Ignore	Deny	Deny
Ignore	Ignore	Ignore

Allow: The access request matches an Allow statement in the permission policy and does not match any Deny statements.
Deny (explicit deny): The access request matches a Deny statement in the permission policy. A Deny statement always takes precedence over an Allow statement, resulting in an explicit deny.
Ignore (implicit deny): The access request does not match any Allow or Deny statements. By default, a RAM user has no permissions to perform any operations. Any action that is not explicitly allowed is implicitly denied.

Limitations

Item	Description
Creation method	You can create access points by using the OSS console, API, or ossutil, but not with SDKs.
Quantity	You can create up to 1,000 access points per Alibaba Cloud account.
Modification rules	Once an access point is created, you can only modify its access point policy. Its basic information, such as the name or alias, cannot be changed.
Access method	Anonymous access is not supported.

FAQ

Support for IP address whitelisting

Yes. You can add an IP address-based condition such as "IpAddress": {"acs:SourceIp": ["xxx"]} to an access point policy by using the JSON editor.

Permissions for creating access points

The following permissions are required: oss:CreateAccessPoint, oss:GetAccessPoint, oss:DeleteAccessPoint, oss:ListAccessPoints, oss:PutAccessPointPolicy, oss:GetAccessPointPolicy, oss:DeleteAccessPointPolicy, oss:PutBucketPolicy, oss:GetBucketPolicy, and oss:DeleteBucketPolicy.

Object Storage Service:Accessing OSS with access points

How it works

Quick start

Step 1: Create an access point

Visual editor

JSON editor

Step 2: Delegate permissions

Delegate to specific access point

Delegate to all access points

Delegate by network origin

Step 3: Access resources via access point

SDK

ossutil

REST API

Use case

Scenario

Solution design

AP policy configuration

ap-01: Read-only

ap-02: Read/write

ap-03: VPC read/write

Bucket policy delegation

Unified delegation

Individual delegation

Permission evaluation logic

Limitations

FAQ

Support for IP address whitelisting

Permissions for creating access points

References