# oss-access-control Part of **OSS** > πŸ’‘ **Path Selection**: This skill is one implementation path for [Configure bucket-level security policies](../../intent/oss-configure-security/SKILL.md). If you're unsure which path to take, check the routing skill first. # Object Storage Service Access Control ## Capabilities Overview | Sub-capability | Calling Mode | Description | |----------------|--------------|-------------| | Manage Access Point | Synchronous | Create, delete, list, and retrieve information about access points. | | Configure Access Point Policy | Synchronous | Set, retrieve, and delete policies that define permissions for access points. | | Configure Access Point Config | Synchronous | Set and retrieve configuration settings for object process access points. | ## API Calling Patterns ### Authentication The primary authentication method is **OSS4-HMAC-SHA256 signature-based authorization**. - Use the `Authorization` header with the format: `Authorization: OSS4-HMAC-SHA256 Credential=///oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=` - Store your credentials in environment variables: - `ALIBABA_CLOUD_ACCESS_KEY_ID` - `ALIBABA_CLOUD_ACCESS_KEY_SECRET` - Alternative legacy method (`Authorization: OSS AccessKeyID:Signature`) is supported but not recommended. ### Service Endpoint (Endpoint) APIs use region-specific endpoints with the pattern: `https://{BucketName}.oss-{region}.aliyuncs.com` Common regions include: - `cn-hangzhou` - `cn-shanghai` - `cn-beijing` - `cn-qingdao` - `cn-shanghai` For user-level operations (e.g., listing all access points), use the regional endpoint without a bucket name: `https://oss-{region}.aliyuncs.com` ### Synchronous API Pattern All operations in this domain follow a **synchronous** calling pattern: 1. Construct an HTTP request (GET, PUT, or DELETE) to the appropriate endpoint with query parameters (e.g., `?accessPoint`, `?accessPointPolicy`) 2. Include required headers: - `Date`: Current UTC time in RFC 1123 format - `Host`: The full hostname of the endpoint - Operation-specific headers (e.g., `x-oss-access-point-name`) - `Authorization`: Signed credential as described above 3. For PUT operations, include a well-formed XML or JSON body as specified 4. Send the request and receive an immediate response 5. Parse the response body (XML for most operations, JSON for policy operations) No polling or streaming is requiredβ€”each request completes in a single round trip. ## Parameter Reference ### Manage Access Point | Parameter | Type | Required | Default | Constraints | Description | |----------|------|----------|---------|-------------|-------------| | AccessPointName | string | true | null | 3-19 characters; only lowercase letters, digits, hyphens; cannot start/end with hyphen; cannot end with -ossalias | The name of the access point. Must be unique in a region. | | NetworkOrigin | string | true | null | one of: vpc, internet | The network origin of the access point. | | VpcConfiguration | container | false | null | null | The container that stores information about the VPC. Required only if NetworkOrigin is set to 'vpc'. | | VpcId | string | false | null | null | The ID of the VPC. Required only when NetworkOrigin is set to 'vpc'. | | x-oss-access-point-name | string | true | null | null | The name of the access point (used in Get/Delete/List operations). | | max-keys | String | false | null | For user-level: (0,1000]; for bucket-level: (0,100] | The maximum number of access points that can be returned. | | continuation-token | String | false | null | null | The token from which the list operation must start. | | x-oss-access-point-for-object-process-name | string | true | null | max 63 characters, contains only lowercase letters, digits, and hyphens (-), cannot start or end with a hyphen | The name of the Object FC Access Point. | ### Configure Access Point Policy | Parameter | Type | Required | Default | Constraints | Description | |----------|------|----------|---------|-------------|-------------| | x-oss-access-point-name | string | true | null | null | The name of the access point. | | x-oss-access-point-for-object-process-name | string | true | null | null | The name of the Object FC Access Point. | ### Configure Access Point Config | Parameter | Type | Required | Default | Constraints | Description | |----------|------|----------|---------|-------------|-------------| | x-oss-access-point-for-object-process-name | string | true | null | max 63 characters, contains only lowercase letters, digits, and hyphens (-), cannot start or end with a hyphen | The name of the Object FC Access Point. | | PublicAccessBlockConfiguration.BlockPublicAccess | boolean | false | false | true or false | Specifies whether to enable Block Public Access. | | ObjectProcessConfiguration.AllowedFeatures.AllowedFeature | string | false | null | one of: GetObject-Range | Specifies that Function Compute supports Range GetObject requests. | | ObjectProcessConfiguration.TransformationConfigurations.TransformationConfiguration.Actions.Action | string | false | null | one of: GetObject | The supported OSS API operations. | | ObjectProcessConfiguration.TransformationConfigurations.TransformationConfiguration.ContentTransformation.FunctionCompute.FunctionAssumeRoleArn | string | false | null | null | The ARN of the role used by OSS for accessing Function Compute resources. | | ObjectProcessConfiguration.TransformationConfigurations.TransformationConfiguration.ContentTransformation.FunctionCompute.FunctionArn | string | false | null | null | The ARN of the function to associate with the access point. | ## Code Examples ### Create Access Point - Bash - All Regions ```bash PUT /?accessPoint HTTP/1.1 Date: Mon, 19 Jun 2023 03:15:40 GMT Content-Length: 0 Content-Type: application/xml Host: oss-example.oss-cn-hangzhou.aliyuncs.com Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e ap-01 vpc vpc-t4nlw426y44rd3iq4xxxx ``` ### Get Access Point Policy - Bash - All Regions ```bash GET /?accessPointPolicy HTTP/1.1 Date: Mon, 19 Jun 2023 03:15:40 GMT Content-Length: 230 Content-Type: application/xml Host: oss-example.oss-cn-hangzhou.aliyuncs.com x-oss-access-point-name: ap-01 Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e ``` ### Configure Object FC Access Point Config - Python - All Regions ```python import requests import hashlib import hmac import base64 import time import urllib.parse # Configuration bucket_name = "oss-example" region = "cn-qingdao" access_key_id = "LTAI********************" access_key_secret = "your-secret-key" endpoint = f"https://{bucket_name}.oss-{region}.aliyuncs.com" access_point_name = "fc-ap-01" request_url = f"{endpoint}/?accessPointConfigForObjectProcess" # Headers headers = { "Date": time.strftime("%a, %d %b %Y %H:%M:%S GMT", time.gmtime()), "Content-Type": "application/xml", "Host": f"{bucket_name}.oss-{region}.aliyuncs.com", "x-oss-access-point-for-object-process-name": access_point_name, } # Body xml_body = ''' GetObject-Range GetObject acs:ram::111933544165****:role/aliyunossobjectfcforossdefaultrole acs:oss:cn-qingdao:111933544165****:services/oss-fc.LATEST/functions/oss-fc-02 true ''' # Content-Length headers["Content-Length"] = str(len(xml_body)) # Signature def sign_string(key, string_to_sign): return hmac.new(key.encode('utf-8'), string_to_sign.encode('utf-8'), hashlib.sha256).hexdigest() # Canonicalized resource canonicalized_resource = "/" + bucket_name + "/?accessPointConfigForObjectProcess" # Canonicalized headers canonicalized_headers = "host:" + headers["Host"] + "\n" # String to sign string_to_sign = f"PUT\n\n{headers['Content-Type']}\n{headers['Date']}\n{canonicalized_headers}{canonicalized_resource}" # Signing key signing_key = f"{access_key_secret}+{region}/{bucket_name}/aliyun_v4_request" signature = sign_string(signing_key, string_to_sign) # Authorization header headers["Authorization"] = f"OSS4-HMAC-SHA256 Credential={access_key_id}/20250417/{region}/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature={signature}" # Send request response = requests.put(request_url, headers=headers, data=xml_body) print(response.status_code) print(response.headers) print(response.text) ``` ### List Object FC Access Points - Bash - All Regions ```bash GET /?accessPointForObjectProcess&max-keys=10&continuation-token=abcd HTTP/1.1 Date: Mon, 30 Oct 2023 03:15:40 GMT Content-Length: 0 Content-Type: application/xml Host: oss-cn-qingdao.aliyuncs.com Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e ``` ### Delete Access Point Policy - Bash - All Regions ```bash DELETE /?accessPointPolicy HTTP/1.1 Date: Mon, 19 Jun 2023 03:15:40 GMT Content-Length: 230 Content-Type: application/xml Host: oss-example.oss-cn-hangzhou.aliyuncs.com x-oss-access-point-name: ap-01 Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e ``` ### Get Object FC Access Point Config - Curl - All Regions ```bash curl -X GET \ 'https://oss-example.oss-cn-qingdao.aliyuncs.com/?accessPointConfigForObjectProcess' \ -H 'Date: Mon, 30 Oct 2023 03:15:40 GMT' \ -H 'Content-Length: 0' \ -H 'Content-Type: application/xml' \ -H 'Host: oss-example.oss-cn-qingdao.aliyuncs.com' \ -H 'x-oss-access-point-for-object-process-name: fc-ap-01' \ -H 'Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e' ``` ## Response Format (Response Format) ```xml acs:oss:cn-hangzhou:128364106451xxxx:accesspoint/ap-01 ap-01-45ee7945007a2f0bcb595f63e2215cxxxx-ossalias ``` **Key Fields**: - `AccessPointArn` β€” The Alibaba Cloud Resource Name (ARN) of the created access point - `Alias` β€” The alias of the access point used for endpoint construction ```xml ap-01 oss-example 111933544165xxxx vpc vpc-t4nlw426y44rd3iq4xxxx arn:acs:oss:cn-hangzhou:111933544165xxxx:accesspoint/ap-01 1626769503 ap-01-ossalias enable ap-01.oss-cn-hangzhou.oss-accesspoint.aliyuncs.com ap-01.oss-cn-hangzhou-internal.oss-accesspoint.aliyuncs.com true ``` **Key Fields**: - `AccessPointName` β€” Name of the access point - `Bucket` β€” Associated bucket name - `AccountId` β€” Alibaba Cloud account ID - `NetworkOrigin` β€” Network origin (vpc or internet) - `VpcConfiguration.VpcId` β€” VPC ID if applicable - `AccessPointArn` β€” Full ARN of the access point - `CreationDate` β€” Unix timestamp of creation time - `Alias` β€” Access point alias - `Status` β€” Current status (enable/disable) - `Endpoints.PublicEndpoint` β€” Public endpoint URL - `Endpoints.InternalEndpoint` β€” Internal endpoint URL - `PublicAccessBlockConfiguration.BlockPublicAccess` β€” Whether public access is blocked ## Error Handling (Error Handling) | Error Code (Code) | Description (Description) | Recommended Action (Recommended Action) | |-------------------|---------------------------|----------------------------------------| | 400 | Bad Request – The request parameters are invalid or malformed. Check the XML structure, required fields, and naming constraints. | Validate request syntax, parameter names, and values against documentation. | | 403 | Forbidden – The user does not have the necessary permissions (e.g., oss:CreateAccessPoint) to perform the operation. Verify RAM policies or STS credentials. | Ensure your RAM user or role has the required OSS permissions. | | 404 | The specified access point or bucket does not exist. | Verify the access point name and region; ensure it exists before operating on it. | | 409 | Conflict – An access point with the same name already exists in the region. | Choose a different, unique access point name. | | 429 | Too Many Requests – Rate limit exceeded. Wait before retrying or reduce the frequency of requests. | Implement exponential backoff and respect rate limits. | | 500 | Internal Server Error – A server-side issue occurred. Retry the request after a short delay. | Retry with exponential backoff; contact support if persistent. | ### Rate Limits & Retry - Account-level limits: Up to 1,000 access points per account; up to 100 access points per bucket - QPS limits: Typically 10-100 requests per second per account depending on operation - Retry strategy: Use exponential backoff (e.g., 1s, 2s, 4s, 8s) for 429 and 5xx errors - Respect the `Retry-After` header if provided in error responses ## Environment Requirements (Requirements) - Set environment variables for credentials: ```bash export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret ``` - For Python examples: `requests` library required (`pip install requests`) - Date/time must be synchronized with NTP for signature validation ## FAQ Q: What is the difference between regular access points and Object FC Access Points? A: Regular access points provide secure, named entry points to OSS buckets with VPC or internet network origins. Object FC Access Points integrate with Function Compute to transform objects during retrieval (e.g., image resizing, format conversion). Q: How do I authenticate API requests to OSS access point endpoints? A: Use OSS4-HMAC-SHA256 signature authentication with your Alibaba Cloud AccessKey ID and Secret. Include the properly formatted Authorization header in every request. Q: Can I use the same access point name across different regions? A: Yes, access point names only need to be unique within a single region. You can have an access point named "ap-01" in both cn-hangzhou and cn-shanghai. Q: What permissions are required to manage access points? A: You need specific OSS permissions like oss:CreateAccessPoint, oss:GetAccessPoint, oss:DeleteAccessPoint, etc. These can be granted via RAM policies to users or roles. Q: Are access point operations free? A: Creating, deleting, and configuring access points themselves are generally free or very low cost (typically Β₯0.0001 per request), but data transfer and storage through access points incur standard OSS charges. ## Pricing & Billing ### Billing Model Per-request billing model. Each API call (create, delete, get, list, configure) counts as one request regardless of success or failure. ### Price Reference | Tier/Model | Input Price | Output Price | Other Fees | |------------|-------------|--------------|------------| | standard | Β₯0.0001 per request | Β₯0.0001 per request | Creating access points is free; data operations through access points billed separately | ### Free Tier - GetAccessPoint, GetAccessPointPolicy, GetAccessPointForObjectProcess: 1,000 free requests per month - DeleteAccessPointForObjectProcess: 10,000 free requests per month - Other operations: No free tier ### Usage Limits - Maximum 1,000 access points per account - Maximum 100 access points per bucket - QPS limits: 10-100 requests per second depending on operation type ### Billing Notes Access point creation and configuration operations are billed per request. Data read/write operations performed through access points are billed according to standard OSS pricing for requests, storage, and data transfer. Failed requests still count toward your usage and billing.