Access control

Last Updated: Jul 29, 2017

Send an OSS access request

You can access the OSS directly by calling a RESTful API provided by the OSS or using an API-encapsulated SDK. Each request for access to the OSS requires identity verification or direct anonymous access based on the current bucket permission and operation.

  • According to the roles of visitors, the access to OSS resources is divided into owner access and third-party access. Here, the owner refers to the bucket owner, also known as “developer”. Third-party users are users who access resources in a bucket.

  • According to the identity of visitors, the access to OSS resources is divided into anonymous access and signature-based access. In the OSS, a request that does not contain any identification information is considered anonymous access. Signature-based access refers to requests that, according to the rules in the OSS API documentation, contain signature information in the request header or URL.

Types of AccessKeys

Currently, there are three types of AccessKey for OSS access. They are described below:

Alibaba Cloud account AccessKeys

These are the AccessKeys of bucket owners. The AccessKey provided by each Alibaba Cloud account has full access to its own resources. Each Alibaba Cloud account can simultaneously have 0 to 5 active or inactive AccessKey pairs (AccessKeyID and AccessKeySecret). You can add or delete AccessKey pairs on AccessKey console. Each AccessKey pair may be in two states: active and inactive.

  • Active indicates that the user’s AccessKey is in the active state and can be used for identity authentication.
  • Inactive indicates that the user’s AccessKey is in the inactive state and cannot be used for identity authentication.

The AccessKey of the Alibaba Cloud account should not be directly used unless necessary.

RAM account AccessKeys

Resource Access Management (RAM) is a resource access control service provided by Alibaba Cloud. RAM account AKs are the access keys granted by RAM. These AKs only allow access to resources in a bucket according to the rules defined by RAM. RAM helps you to collectively manage your users (such as employees, systems or applications) and controls which resources your users can access. For example, you can allow your users to have only the read permission on a bucket.
Subaccounts are subordinate to normal accounts and cannot own any actual resources. All resources belong to primary accounts.

STS account AccessKeys

The Alibaba Cloud STS (Security Token Service) is a service that provides temporary access credentials. STS account AKs are the AKs issued by the STS. These AKs only allow access to buckets in accordance with the rules defined by the STS.

Implementation of identity authentication

Currently, there are three methods of authentication:

  • AK authentication
  • RAM authentication
  • STS authentication

Before sending a request to the OSS as an individual identity, a user needs to generate a signature string for the request according to the format specified by the OSS and then encrypt the signature string using the AccessKeySecret to generate a verification code.
After receiving the request, the OSS finds the corresponding AccessKeySecret based on the AccessKeyID, and obtains the signature string and verification code in the same way. If the obtained verification code is the same as the provided verification code, the request is assumed valid. If not, the OSS rejects the request and returns an HTTP 403 error.
Users can directly use the SDKs provided by the OSS with different types of AccessKeys for different types of identity authentication.

Permission control

OSS provides various permission control mechanisms for access to its stored objects:

  • Bucket-level permissions
  • Object-level permissions
  • Account-level permissions (RAM)
  • Temporary account permissions (STS)

Bucket-level permissions

Bucket permission types

The OSS provides an Access Control List (ACL) for permission control. The OSS ACL provides bucket-level access control. Currently, three access permissions are provided for a bucket: public-read-write, public-read, and private. They are described as follows:

Permission Access Restriction
Public-read-write Anyone (including anonymous users) can read, write, and delete the objects in the bucket. The fees incurred by such operations shall be borne by the owner of the bucket. Use this permission with caution.
Public-read Only the owner of a bucket can write or delete the objects in the bucket. Anyone (including anonymous users) can read the objects in the bucket.
Private Only the owner of a bucket can read, write, and delete the objects in the bucket. Others cannot access the objects in the bucket without authorization.

Bucket permission settings and read methods

Function usage reference:

Object-level permissions

Object permission types

The OSS ACL also provides object-level permission access control. Currently, four access permissions are available for an object, including private, public-read, public-read-write and default. You can use the “x-oss-object-acl” header in the Put Object ACL request to set the access permission. Only the bucket owner has the permission to perform this operation.

Permission Access restriction
public-read-write Indicates that the object can be read and written by the public. That is, all users have the permission to read and write the object.
public-read Indicates that the object can be read by the public. Only the owner of the object has the permission to read and write the object. Other users only have the permission to read the object.
private Indicates that the object is a private resource. Only the owner of the object has the permission to read and write the object. Other users have no permission to operate the object.
default Indicates that the object inherits the permission of the bucket.


  • If no ACL is configured for an object, the object uses the default ACL, indicating that the object has the same ACL as the bucket where the object is stored.
  • If an ACL is configured for an object, the object ACL has higher-level permission than the bucket ACL. For example, an object with the public-read permission can be accessed by authenticated users and anonymous users, regardless of the bucket permission.

Object permission settings and read methods

Function usage reference:

Account-level permissions (RAM)

Application scenarios

If you have purchased cloud resources and multiple users in your organization need to use them, these users have to share the AccessKey of your Alibaba Cloud account. There are two problems:

  • If your key is shared by many people, it has a high risk of leakage.
  • You cannot determine which resources (e.g. buckets) can be accessed by the users.

Solution: Under your Alibaba Cloud account, you can use RAM to create subusers with their own AccessKeys. In this case, your Alibaba Cloud account will be the primary account and the created accounts will be subaccounts. Subaccounts can only use their AccessKeys for the operations and resources authorized by the primary account.

Specific implementation

For details about the RAM, refer to RAM User Guide. The RAM User Guide describes how to grant permissions, create RAM accounts, and manage group permissions in details.

For details about how to configure the policies required in authorization, refer to the final section Configuration Rules of this chapter.

Temporary account permissions (STS)

Application scenarios

Users managed by your local identity system, such as your app users, your local corporate account, or third-party apps, may also directly access OSS resources. They are called federated users. In addition, users can also be the applications you create that have access to your Alibaba Cloud resources.

With respect to these federated users, short-term access permission management is provided for the Alibaba Cloud account (or RAM users) through the Security Token Service (STS) of Alibaba Cloud. You do not need to reveal the long-term key (such as the login password and AccessKey) of your Alibaba Cloud account (or RAM users), but only need to create a short-term access credential for a federated user. The access permission and validity of this credential are both up to you. You do not need to care about permission revocation. The access credential automatically becomes invalid when it expires.

STS-based access credentials include the security token (SecurityToken) and the temporary access key (AccessKeyId and AccessKeySecret). The AccessKey method is the same as the method of using the AccessKey of the Alibaba Cloud account or RAM user. In addition, each OSS access request must carry a security token.

Specific implementation

For details about the STS, refer to Role management in the RAM User Guide. The key is to call AssumeRole of the STS interface to obtain valid access credential. You can also directly use STS SDK to call the access credential.

For details about how to configure the policies required in authorization, refer to the final section of this chapter.

RAM and STS application scenario practices

In different application scenarios, how the access identity is verified may vary. The following describes two methods for access identity verification in typical application scenarios.

A mobile app is used as an example. Assume that you are a mobile app developer. You attempt to use the Alibaba Cloud OSS to store end user data of the app. You also have to ensure data is isolated between app users to prevent an app user from obtaining data of other app users.

Mode 1: Using AppServer for data transit and data isolation

As shown in the figure above, you need to develop an AppServer. Only the AppServer can access the ECS. The ClientApp can read or write data only through the AppServer. The AppServer ensures isolated access to different user data.

In this method, you can use the key provided by your Alibaba Cloud account or RAM account for signature verification. In case of any security problem, you are recommended not to directly use the key of your Alibaba Cloud account (root account) to access the OSS.

Mode 2: Using STS for direct access to OSS

The STS solution is shown below:

The solution is described in detail as follows:

  1. Log in as the app user. The app user is irrelative to the Alibaba Cloud account but is an end user of the app. The AppServer allows the app user to log in. For each valid app user, the AppServer needs to define the minimum access permission for them.
  2. The AppServer requests a security token (SecurityToken) from the STS. Before calling STS, the AppServer needs to determine the minimum access permission (described in policy syntax) of app users and the expiration time of the authorization. Then, the AppServer uses AssumeRole to obtain a security token indicating a role. For details about role management and usage, refer to Role Management in the RAM User Guide.
  3. The STS returns a valid access credential to the AppServer, where the access credential includes a security token, a temporary access key (AccessKeyID and AccessKeySecret), and the expiry time.
  4. The AppServer returns the access credential to the ClientApp. The ClientApp caches this credential. When the credential becomes invalid, the ClientApp needs to request a new valid access credential from the AppServer. For example, if the access credential is valid for one hour, the ClientApp can request the AppServer to update the access credential every 30 minutes.
  5. The ClientApp uses the access credential cached locally to request Alibaba Cloud Service APIs. The ECS perceives the STS access credential, relies on STS to verify the credential, and correctly responds to the user request.

RAM and STS authorization policy configuration

The detailed rules of the use of policies during RAM or STS authorization are as follows.


First, let’s look at the following policy example:

  1. {
  2. "Version": "1",
  3. "Statement": [
  4. {
  5. "Action": [
  6. "oss:GetBucketAcl",
  7. "oss:ListObjects"
  8. ],
  9. "Resource": [
  10. "acs:oss:*:1775305056529849:mybucket"
  11. ],
  12. "Effect": "Allow",
  13. "Condition": {
  14. "StringEquals": {
  15. "acs:UserAgent": "java-sdk",
  16. "oss:Prefix": "foo"
  17. },
  18. "IpAddress": {
  19. "acs:SourceIp": ""
  20. }
  21. }
  22. },
  23. {
  24. "Action": [
  25. "oss:PutObject",
  26. "oss:GetObject",
  27. "oss:DeleteObject"
  28. ],
  29. "Resource": [
  30. "acs:oss:*:1775305056529849:mybucket/file*"
  31. ],
  32. "Effect": "Allow",
  33. "Condition": {
  34. "IpAddress": {
  35. "acs:SourceIp": ""
  36. }
  37. }
  38. }
  39. ]
  40. }

This is an authorization policy. You can use this policy to grant permissions for users through RAM or STS. The policy has a Statement (one policy can have multiple Statements). In the Statement, Action, Resource, Effect, and Condition are specified.

This policy authorizes your ‘mybucket’ and ‘mybucket/file*’ resources to corresponding users and supports GetBucketAcl, GetBucket, PutObject, GetObject, and DeleteObject actions. The Condition indicates that authentication is successful and authorized users can access related resources only when UserAgent is java-sdk and the source IP address is Prefix and Delimiter conditions apply during the GetBucket (ListObjects) action. For details about the two fields, see OSS API Documentation.

Configuration rules


Policy version is defined. For configuration method in this document, it is set to “1”.


The Statement describes the authorization meaning. It can contain multiple meanings based on the business scenario. Each meaning includes a description of the Action, Effect, Resource, and Condition. The request system will check each statement for a match one by one. All successfully matched statements will be divided into Allow and Deny based on the difference of Effect settings, and Deny is given priority. If the matches are all Allow, the request passes authentication. If one of the matches is Deny or there are no matches, this request is denied to access.


Actions fall into two categories: bucket-level actions and object-level actions. Bucket-level actions include oss:PutBucketAcl and oss:GetBucketLocation. The action objects are buckets and the action names correspond to the involved interfaces in a one-to-one manner. Object-level actions include oss:GetObject, oss:PutObject, oss:DeleteObject, oss:DeleteObject, and oss:AbortMultipartUpload. If you want to authorize actions for a type of object, you can select one or more of the above actions. In addition, all action names must be prefixed with “oss:”, as shown in the example above. Action is a list. There can be multiple Actions. The mapping between Actions and APIs is as follows:


API Action
GetService (ListBuckets) oss:ListBuckets


API Action
PutBucket oss:PutBucket
GetBucket (ListObjects) oss:ListObjects
PutBucketAcl oss:PutBucketAcl
DeleteBucket oss:DeleteBucket
GetBucketLocation oss:GetBucketLocation
GetBucketAcl oss:GetBucketAcl
GetBucketLogging oss:GetBucketLogging
PutBucketLogging oss:PutBucketLogging
DeleteBucketLogging oss:DeleteBucketLogging
GetBucketWebsite oss:GetBucketWebsite
PutBucketWebsite oss:PutBucketWebsite
DeleteBucketWebsite oss:DeleteBucketWebsite
GetBucketReferer oss:GetBucketReferer
PutBucketReferer oss:PutBucketReferer
GetBucketLifecycle oss:GetBucketLifecycle
PutBucketLifecycle oss:PutBucketLifecycle
DeleteBucketLifecycle oss:DeleteBucketLifecycle
ListMultipartUploads oss:ListMultipartUploads
PutBucketCors oss:PutBucketCors
GetBucketCors oss:GetBucketCors
DeleteBucketCors oss:DeleteBucketCors
PutBucketReplication oss:PutBucketReplication
GetBucketReplication oss:GetBucketReplication
DeleteBucketReplication oss:DeleteBucketReplication
GetBucketReplicationLocation  oss:GetBucketReplicationLocation
GetBucketReplicationProgress oss:GetBucketReplicationProgress

Object level

API Action
GetObject oss:GetObject
HeadObject oss:GetObject
PutObject oss:PutObject
PostObject oss:PutObject
InitiateMultipartUpload oss:PutObject
UploadPart oss:PutObject
CompleteMultipart oss:PutObject
DeleteObject oss:DeleteObject
DeleteMultipartObjects oss:DeleteObject
AbortMultipartUpload oss:AbortMultipartUpload
ListParts oss:ListParts
CopyObject oss:GetObject,oss:PutObject
UploadPartCopy oss:GetObject,oss:PutObject
AppendObject oss:PutObject
GetObjectAcl oss:GetObjectAcl
PutObjectAcl oss:PutObjectAcl


Resource stands for a specific resource or resources on the OSS (the wildcard is supported). Resources are named in the format of “acs:oss:region:bucket_owner:bucket_name/object_name”. For all bucket-level actions, the final part “/object_name” is not required. You can just render it as “acs:oss:region:bucket_owner:bucket_name”. Resource is also a list and there can be multiple Resources. Here, the region field is currently not supported and set as “*”.


Effect indicates the authorization result of the Statement. Two value options are available: Allow and Deny. When there are multiple Statement matches, the Deny is given higher priority.

For example, deny the deletion of a certain directory, but allow all operations for other files:

  1. {
  2. "Version": "1",
  3. "Statement": [
  4. {
  5. "Effect": "Allow",
  6. "Action": [
  7. "oss:*"
  8. ],
  9. "Resource": [
  10. "acs:oss:*:*:bucketname"
  11. ]
  12. },
  13. {
  14. "Effect": "Deny",
  15. "Action": [
  16. "oss:DeleteObject"
  17. ],
  18. "Resource": [
  19. "acs:oss:*:*:bucketname/index/*",
  20. ]
  21. }
  22. ]
  23. }


Condition indicates the conditions for the authorization policy. In the above example, you can set check conditions for acs:UserAgent and acs:SourceIp. The oss:Delimiter and oss:Prefix fields are used to restrict resources during the GetBucket action.

The OSS supports the following conditions:

Condition Function Valid value
acs:SourceIp Specifying the IP address segment Common IP address, wildcard (*) supported
acs:UserAgent Specifying the http useragent header String
acs:CurrentTime Specifying valid access time ISO8601 format
acs:SecureTransport Whether HTTPS is used “true” or “false”
oss:Prefix Used as the prefix for ListObjects Valid object name

Best practices

RAM and STS User Guide

Thank you! We've received your feedback.