Help & Documentation>Cloud Object Storage>Best Practice>Access Control and Permission Management>Working with COS API Authorization Policies

Working with COS API Authorization Policies

Last updated: 2024-11-20 20:08:07

On this page:

Note
When granting API operation permissions to sub-users or collaborators, please ensure that you follow the principle of least privilege and grant permissions based on business needs. If you grant sub-users or collaborators access to all resources (resource:*) or all actions (action:*), there is a risk of data security breaches due to overly broad permissions.

Overview

When using a temporary key to access COS, the operation permissions required vary by API or series of APIs that you specify.
A COS API authorization policy is a JSON string. For example, below is a policy that grants the permission to perform uploads (including simple upload, upload through an HTML form, and multipart upload) for objects prefixed with doc and downloads for objects prefixed with doc2 for the bucket examplebucket-1250000000 in the region "ap-beijing" under the APPID 1250000000:
{
    "version": "2.0",
    "statement": [{
            "action": [
                // Simple upload operation 
                "name/cos:PutObject",
                //Upload objects using a form 
                "name/cos:PostObject",
                // Multipart upload: Initialize the multipart operation 
                "name/cos:InitiateMultipartUpload",
                // Multipart upload: List ongoing multipart uploads
                "name/cos:ListMultipartUploads",
                // Multipart upload: List uploaded parts operation 
                "name/cos:ListParts",
                // Multipart upload: Upload part operation 
                "name/cos:UploadPart",
                // Multipart upload: Complete all multipart upload operations 
                "name/cos:CompleteMultipartUpload",
                // Cancel multipart upload operation 
                "name/cos:AbortMultipartUpload"
            ],
            "effect": "allow",
            "resource": [
                "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
            ]
        },
        {
            "action": [
                // Download operation 
                "name/cos:GetObject"
            ],
            "effect": "allow",
            "resource": [
                "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc2/*"
            ]
        }
    ]
}

Authorization Policy Elements

Name
Description
version
Policy syntax version, which is 2.0 by default.
effect
Allow or deny.
resource
The specific data for authorization can be any resource, a resource with a specified path prefix, a resource with an absolute path, or a combination of these.
Note: If the path contains Chinese characters, keep them as is. For example, examplebucket-1250000000/文件夹/文件名.txt.
action
Here, the COS API refers to specifying a single action or a combination of actions based on your requirements, or all actions (*), such as action being name/cos:GetService. Please note the distinction between uppercase and lowercase letters in English.
condition
Optional condition. For more information, see Element Reference.
Examples of authorization policy settings for each COS API are as listed below.

Service API

Querying the bucket list

For the API "GET Service", if granted operation permission, the policy's action would be name/cos:GetService, and the resource would be *.

Sample

The following policy grants the permission to query the bucket list:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetService"
      ],
      "effect": "allow",
      "resource": [
        "*"
      ]
    }
  ]
}

Bucket API

The resource field for bucket API access policies is outlined in further detail below:
To operate on buckets in all regions, set the policy's resource to *. Please note that this policy has a broad scope, which may pose data security risks. Configure with caution.
To allow operations only on buckets in a specific region, for example, only allowing operations on buckets with APPID 1250000000 in the Beijing region (ap-beijing), the policy's resource should be qcs::cos:ap-beijing:uid/1250000000:*.
To allow operations only on a specific bucket with a specified name and region, for example, a bucket named examplebucket-1250000000 in the region "ap-beijing" under the APPID 1250000000, the policy's resource should be set to qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/*.
The action field for bucket API policies varies by operation. The following section lists several bucket API access policies for your reference.

Create a bucket

To grant permission to access this API, the action field in the policy should be set to name/cos:PutBucket.

Sample

The following policy grants the user with the APPID 1250000000 permission to create a bucket named examplebucket-1250000000 in the Beijing region:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutBucket"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}
Note
The bucket name must comply with the naming conventions. For more information, please refer to Bucket Naming Conventions.

Checking a bucket and its permission

To grant permission to access this API, the action field in the policy should be set to name/cos:HeadBucket.

Sample

The following policy grants the permission to extract only the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:HeadBucket"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Querying the object list

To grant permission to access this API, the action field in the policy should be set to name/cos:GetBucket.

Sample

The following policy grants the permission to query only the list of objects in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetBucket"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Deleting a bucket

To grant permission to access this API, the action field in the policy should be set to name/cos:DeleteBucket.

Sample

The following policy grants the permission to delete only the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:DeleteBucket"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Setting bucket ACL

To grant permission to access this API, the action field in the policy should be set to name/cos:PutBucketACL.

Sample

The following policy grants the permission to set an ACL only for the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutBucketACL"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Querying bucket ACL

To grant permission to access this API, the action field in the policy should be set to name/cos:GetBucketACL.

Sample

The following policy grants the permission to get the ACL only of the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetBucketACL"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Setting a cross-origin access configuration

To grant permission to access this API, the action field in the policy should be set to name/cos:PutBucketCORS.

Sample

The following policy grants the permission to set a cross-origin access configuration only for the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutBucketCORS"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Querying a Cross-Origin Configuration

To grant permission to access this API, the action field in the policy should be set to name/cos:GetBucketCORS.

Sample

The following policy grants the permission to query the CORS configuration only of the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetBucketCORS"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Deleting a Cross-Origin Configuration

To grant permission to access this API, the action field in the policy should be set to name/cos:DeleteBucketCORS.

Sample

The following policy grants the permission to delete the CORS configuration only of the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:DeleteBucketCORS"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Setting a Lifecycle Configuration

To grant permission to access this API, the action field in the policy should be set to name/cos:PutBucketLifecycle.

Sample

The following policy grants the permission to set a lifecycle configuration only for the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutBucketLifecycle"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Querying lifecycle

To grant permission to access this API, the action field in the policy should be set to name/cos:GetBucketLifecycle.

Sample

The following policy grants the permission to query the lifecycle configuration only of the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetBucketLifecycle"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Deleting lifecycle

To grant permission to access this API, the action field in the policy should be set to name/cos:DeleteBucketLifecycle.

Sample

The following policy grants the permission to delete the lifecycle configuration only of the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:DeleteBucketLifecycle"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Object API

The resource field for object API access policies is outlined in further detail below:
To operate on any object, the policy's resource should be set to *.
To restrict operations to any object within a specific bucket, such as the bucket named examplebucket-1250000000 in the region "ap-beijing" under the APPID 1250000000, the policy's resource should be set to qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/*.
To restrict operations to a specific bucket and objects with a specified path prefix, such as allowing operations only on objects with the path prefix doc in the bucket examplebucket-1250000000 in the region "ap-beijing" under the APPID 1250000000, the policy's resource should be set to qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*.
To operate on an object with a specified absolute path, such as an object with the absolute path doc/audio.mp3 in the bucket examplebucket-1250000000 in the region "ap-beijing" under the APPID 1250000000, the policy's resource should be qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/audio.mp3.
The action field for Object API access policies varies by operation. All Object API access policies are listed below.

Uploading an object using simple upload

To grant permission to access this API, the action field in the policy should be set to name/cos:PutObject.

Sample

The following policy grants the permission to use simple upload to upload only objects with the path prefix doc in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
 {
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Multipart upload

Multipart upload includes Initiate Multipart Upload, List Multipart Uploads, List Parts, Upload Part, Complete Multipart Upload, and Abort Multipart Upload. To grant permissions for these operations, the policy's action should be: "name/cos:InitiateMultipartUpload", "name/cos:ListMultipartUploads", "name/cos:ListParts", "name/cos:UploadPart", "name/cos:CompleteMultipartUpload", "name/cos:AbortMultipartUpload"
UploadPart","name/cos:CompleteMultipartUpload","name/cos:AbortMultipartUpload" collection.

Sample

The following policy grants the permission to use multipart upload to upload only objects with the path prefix doc in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:InitiateMultipartUpload",
        "name/cos:ListMultipartUploads",
        "name/cos:ListParts",
        "name/cos:UploadPart",
        "name/cos:CompleteMultipartUpload",
        "name/cos:AbortMultipartUpload"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Querying multipart upload

To grant the permission to access this API, the action field in the policy should be set to name/cos:ListMultipartUploads.

Sample

The following policy grants the permission to query ongoing multipart uploads only in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:ListMultipartUploads"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Uploading an object using a form

To grant permission to access this API, the action field in the policy should be set to name/cos:PostObject.

Sample

The following policy grants the permission to use the POST method to upload only objects with the path prefix doc in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PostObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Appending parts

To grant permission to access this API (Append Object), set the action field in the policy to name/cos:AppendObject.

Sample

The following policy grants permission to use append upload for objects with the path prefix doc in the bucket examplebucket-1250000000 residing in the region ap-beijing under the account whose APPID is 1250000000:
 {
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:AppendObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Querying object metadata

To grant permission to access this API, the action field in the policy should be set to name/cos:HeadObject.

Sample

The following policy grants the permission to query objects only with the path prefix doc in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:HeadObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Downloading object

To grant permission to access this API, the action field in the policy should be set to name/cos:GetObject.

Sample

The following policy grants the permission to download only objects with the path prefix doc in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Replicating Objects

To grant permission to access this API, the action field for the destination object should be set to name/cos:PutObject and the action field for the source object should be set to name/cos:GetObject.

Sample

The following policy grants the permission to use multipart copy to copy objects from the path prefixed with doc to the path prefixed with doc2 in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    },
    {
      "action": [
        "name/cos:GetObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc2/*"
      ]
    }
  ]
}
Here, "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc2/*" is the source object.

Copying a part

For the API "Upload Part - Copy", if granted operation permissions, the target object's action should be a set of "name/cos:InitiateMultipartUpload", "name/cos:ListMultipartUploads", "name/cos:ListParts", "name/cos:PutObject", "name/cos:CompleteMultipartUpload", "name/cos:AbortMultipartUpload", and the source object's action should be "name/cos:GetObject".

Sample

The following policy grants the permission to use multipart copy to copy objects from the path prefixed with doc to the path prefixed with doc2 in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:InitiateMultipartUpload",
        "name/cos:ListMultipartUploads",
        "name/cos:ListParts",
        "name/cos:PutObject",
        "name/cos:CompleteMultipartUpload",
        "name/cos:AbortMultipartUpload"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    },
    {
      "action": [
        "name/cos:GetObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc2/*" 
      ]
    }
  ]
}
Here, "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc2/*" is the source object.

Setting object ACL

To grant permission to access this API, the action field in the policy should be set to name/cos:PutObjectACL.

Sample

The following policy grants the permission to set an ACL only for objects with the path prefix doc in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutObjectACL"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Querying object ACL

To grant permission to access this API, the action field in the policy should be set to name/cos:GetObjectACL.

Sample

The following policy grants the permission to query the ACL only of objects with the path prefix doc in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetObjectACL"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Configuring a Preflight Request for Cross-origin Access

To grant permission to access this API, the action field in the policy should be set to name/cos:OptionsObject.

Sample

The following policy grants the permission to send an OPTIONS request only for objects with the path prefix doc in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:OptionsObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Restoring archived objects

To grant permission to access this API, the action field in the policy should be set to name/cos:PostObjectRestore.

Sample

The following policy grants the permission to restore archived objects only with the path prefix doc in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PostObjectRestore"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Deleting One Object

To grant permission to access this API, the action field in the policy should be set to name/cos:DeleteObject.

Sample

The following policy grants the permission to delete only the object audio.mp3 in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:DeleteObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/audio.mp3"
      ]
    }
  ]
}

Deleting Multiple Objects

To grant permission to access this API, the action field in the policy should be set to name/cos:DeleteObject.

Sample

The following policy grants the permission to batch delete only the objects audio.mp3 and video.mp4 in the bucket examplebucket-1250000000 in the region ap-beijing under the APPID 1250000000:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:DeleteObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/audio.mp3",
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/video.mp4"
      ]
    }
  ]
}

Common Scenarios

Granting full access to all resources

The following policy grants full access to all resources:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "*"
      ],
      "effect": "allow",
      "resource": [
        "*"
      ]
    }
  ]
}

Granting read-only access to all resources

The following policy grants read-only access to all resources:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:HeadObject",
        "name/cos:GetObject",
        "name/cos:GetBucket",
        "name/cos:OptionsObject"
      ],
      "effect": "allow",
      "resource": [
        "*"
      ]
    }
  ]
}

Granting read-write access to resources with specified path prefix

The following policy grants the permission to access only files under the path with prefix doc in the bucket examplebucket-1250000000 and does not allow any operations on files in other paths:
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "*"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-shanghai:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

中国站 - English