Object Storage Service:Access OSS through a custom domain name

• For standard access: Map a domain name to a public endpoint

• For cross-region or long-distance acceleration: Map a domain name to an acceleration endpoint

Step 1: Map the domain to the bucket

1. Go to the Buckets page, click the name of your target bucket, then, in the left navigation pane, click Bucket Settings > Domain Names.

2. Click Map Custom Domain Name and enter the domain you want to map, such as oss-example.cn. The system automatically checks if the domain meets the mapping requirements.

   

3. After the check passes, map the domain to the bucket.

   Direct mapping

   If the domain belongs to your current Alibaba Cloud account, map it directly. Click Confirm to map the domain to the bucket.

   

   Verify domain ownership and map

   If the domain belongs to another Alibaba Cloud account or is managed by a different DNS provider, you must first verify domain ownership before mapping it. The following steps show the complete process for verifying ownership and mapping a domain that belongs to another Alibaba Cloud account.

   1. Log on to the Alibaba Cloud DNS console with the account that owns the domain. In the Actions column for the target domain, click Settings.

   2. Click Add Record. Fill in the record information as described below and leave the other settings at their default values.

      • Record Type: Select TXT.

      • Hostname: Enter the hostname displayed in the OSS console, such as _dnsauth. If you are mapping a subdomain, such as image.oss-example.cn, add the subdomain prefix to the hostname. For example, _dnsauth.image.

      • Record Values: Enter the record value displayed in the OSS console, such as 21a0****************************.

   3. Click OK. In the Change Resource Record Confirmation dialog box that appears, click OK again.

   4. Return to the OSS console and click Verify Domain Name Ownership. This maps the domain to the bucket. DNS records may take some time to take effect. If you see an error, wait a few minutes and try again.

   Note

   TXT record can only be used to verify domain ownership. Delete it after the verification is successful. It does not affect subsequent use.

Step 2: Configure a CNAME record to point to the public endpoint

After you map the domain to the bucket, the custom domain is not yet active. You must configure a CNAME record to point the custom domain to the CNAME domain name (recommended) or public endpoint to activate it.

Step 3: Verify access through the custom domain name

After completing the domain mapping and DNS configuration, choose a verification method based on your bucket's access control list (ACL) settings.

Step 1: Map the domain to the bucket

1. Go to the Buckets page, click the name of your target bucket, then, in the left navigation pane, click Bucket Settings > Domain Names.

2. Click Map Custom Domain Name and enter the domain you want to map, such as oss-example.cn. The system automatically checks if the domain meets the mapping requirements.

   

3. After the check passes, map the domain to the bucket.

   Direct mapping

   If the domain belongs to your current Alibaba Cloud account, map it directly. Click Confirm to map the domain to the bucket.

   

   Verify domain ownership and map

   If the domain belongs to another Alibaba Cloud account or is managed by a different DNS provider, you must first verify domain ownership before mapping it. The following steps show the complete process for verifying ownership and mapping a domain that belongs to another Alibaba Cloud account.

   1. Log on to the Alibaba Cloud DNS console with the account that owns the domain. In the Actions column for the target domain, click Settings.

   2. Click Add Record. Fill in the record information as described below and leave the other settings at their default values.

      • Record Type: Select TXT.

      • Hostname: Enter the hostname displayed in the OSS console, such as _dnsauth. If you are mapping a subdomain, such as image.oss-example.cn, add the subdomain prefix to the hostname. For example, _dnsauth.image.

      • Record Values: Enter the record value displayed in the OSS console, such as 21a0****************************.

   3. Click OK. In the Change Resource Record Confirmation dialog box that appears, click OK again.

   4. Return to the OSS console and click Verify Domain Name Ownership. This maps the domain to the bucket. DNS records may take some time to take effect. If you see an error, wait a few minutes and try again.

   Note

   TXT record can only be used to verify domain ownership. Delete it after the verification is successful. It does not affect subsequent use.

Step 2: Enable Transfer Acceleration

1. Go to the Buckets page, click the name of your target bucket, and then in the left navigation pane, click Bucket Settings > Transfer Acceleration

2. Enable Transfer Acceleration. In the dialog box that appears, carefully read the notice, and then click OK.

3. Copy the Acceleration Endpoint.

Step 3: Configure a CNAME record to point to the acceleration endpoint

The following steps show how to configure a CNAME record by using Alibaba Cloud DNS.

1. Log on to the Alibaba Cloud DNS console with the account that owns the domain. In the Actions column for the target domain, click Settings.

2. Click Add Record. Fill in the record information as described below and leave the other settings at their default values.

   Note

   If a CNAME record already exists, click Edit in the Actions column for the record and change the Record Value to the Acceleration Endpoint.

   • Record Type, select CNAME.

   • Hostname: If you are mapping an apex domain (root domain), enter @. If you are mapping a subdomain, such as image.oss-example.cn, enter the subdomain prefix, for example, image.

   • Record Values, Enter the Acceleration Endpoint.

3. Click OK. In the Change Resource Record Confirmation dialog box that appears, click OK again to complete the DNS configuration.

Step 4: Verify access through the custom domain name

After completing the domain mapping and DNS configuration, choose a verification method based on your bucket's access control list (ACL) settings.

Best practices

• Secure transfer: Enable HTTPS

  Configure an SSL certificate for your custom domain to enforce HTTPS access. The HTTPS protocol uses TLS/SSL to encrypt data in transit, which prevents data from being intercepted or tampered with. This also prevents browsers from displaying "Not Secure" warnings and enhances user trust and brand image.

• Cross-origin access: Configure CORS rules

  When a front-end application, such as one deployed at https://web.example.cn, needs to access OSS resources at a different domain, such as https://oss.example.cn, you must configure CORS rules. These rules allow cross-origin requests from the application's domain. CORS uses HTTP headers to control cross-origin access permissions, ensuring that your application can access OSS resources while blocking unauthorized requests.

• Zero-downtime cutover: Switch domains without downtime

  When you need to switch from a bucket endpoint to a mapped custom domain, use the following phased strategy to avoid service interruptions.

  1. Preparation phase: Map the custom domain to the bucket and configure the CNAME record. In a test environment, use a hosts file or a test domain to fully verify the functionality and performance of the new custom domain configuration. Ensure all features work as expected.

  2. Canary release phase (Recommended during off-peak hours): Gradually switch a portion of your traffic to the custom domain. This phased approach minimizes the risk associated with the switch.

  3. Verification phase: Closely monitor access logs and error rates. Analyze key metrics such as response time and success rate to ensure service stability.

  4. Full release phase: After thorough verification, migrate all traffic to the custom domain to complete the domain migration.

  5. Rollback playbook: If any issues occur, immediately roll back to the bucket endpoint, analyze the root cause, and redeploy.

• Performance and security: Isolate usage with subdomains

  Assign different subdomains for different business purposes, such as static.example.com for static web resources and images.example.com for image resources. This domain isolation strategy helps optimize browser concurrent connections (bypassing single-domain limits), configure independent caching policies, and implement fine-grained permission control and security policies. This improves access speed and enhances overall security.

• Feature extension: Host a static website

  To host a complete static website (including HTML, CSS, and JS files) on OSS, configure static website hosting after mapping your custom domain. This enables basic website functionalities such as a default homepage and a 404 error page.

• Performance optimization: Configure CDN acceleration

  For use cases that require distributing static resources to users worldwide, we recommend configuring the CDN acceleration service on top of your custom domain. This caches content on globally distributed edge nodes, resulting in lower access latency, higher concurrency, and a better user experience.

Risk mitigation

• Bandwidth theft protection: Configure Referer-based hotlink protection

  To prevent other websites from using your resources, such as images and videos, and incurring unnecessary traffic costs, use a hotlink protection policy to prevent data transmission abuse By using a whitelist to restrict access sources, costs can be controlled and resources can be protected from abuse effectively.

• Behavioral audit and troubleshooting: Enable access logs

  Enable Real-time Log Query for OSS to record detailed information about all access requests, including access time, source IP, request type, and response status. This facilitates security audits, performance analysis, troubleshooting, and business operations decisions.

What should I do if I receive a NeedVerifyDomainOwnership error when mapping a domain via the API?

This error indicates that you have not verified ownership of the domain. Verify domain ownership by performing the following steps:

1. Call the CreateCnameToken operation to create the CnameToken required for domain ownership verification.

   Note

   By default, a CnameToken expires 72 hours after it is created. If you attempt to create a token again before it expires, the existing CnameToken is returned.

2. Follow the instructions in this document to configure a TXT record with your DNS provider to complete domain ownership verification.

3. Call the PutCname operation to map the custom domain name.

What should I do if I receive a 502 or 504 error when accessing resources through an acceleration endpoint?

This issue is typically caused by the normal operation of the automatic path switching mechanism of OSS Transfer Acceleration. To adapt to network fluctuations and link quality changes during long-distance transfers, the service dynamically selects the optimal transmission path. During a path switch, a small number of requests may be interrupted, resulting in a 502 or 504 error. This cannot be completely avoided. We recommend implementing an exponential backoff retry logic in your client-side code to improve the success rate.

How do I troubleshoot network errors such as resolution failures or connection timeouts?

If you receive a response from OSS, obtain the Request ID and use the OSS self-service diagnostic tool to diagnose the issue.

If the request is interrupted before reaching the OSS server, meaning the Request ID is empty, follow these steps to troubleshoot:

• Connection refused: This error usually indicates that the client and OSS are in the same region but the port is blocked, or an internal endpoint is used for cross-region access. Check and use the correct Public Endpoint for access. Also, use the ping and telnet commands to check for client-side firewall settings or network connectivity restrictions.

• ConnectionTimeOut: This is usually caused by a poor network environment or a short timeout setting. Increase the connection timeout and read timeout values in your SDK and enable the retry mechanism. For large file transfers, use multipart upload and resumable upload to improve transfer stability. If it is a network link issue, consider using a CDN or the OSS Transfer Acceleration service.

• Socket timeout or Socket closed: This indicates that the connection to OSS timed out or was closed unexpectedly. Increase the socket timeout in your SDK configuration (for example, the ClientConfiguration.setSocketTimeout method in the Java SDK).

• Connection reset: The connection was reset for various reasons, such as an incorrect endpoint configuration or the bucket being restricted for security reasons. Troubleshoot in the following order:

  1. Use ping or the Alibaba Cloud Kunlun diagnostic tool to check if the client's network connectivity is normal.

  2. Confirm that the endpoint configured in your code is correct and includes the proper protocol prefix (http:// or https://).

  3. Confirm that the bucket has not been placed in the OSS sandbox due to security attacks or policy violations, which would restrict access.

  4. If the problem persists, use a tool like Wireshark to capture network packets and then contact Technical Support for further investigation.

What should I do if OSS upload or download speeds are very slow?

The client's local network bandwidth, network link quality, and transfer policy configuration mainly affect the transfer speed of OSS.

• General troubleshooting: First, confirm that your current bandwidth usage has not reached the bucket's bandwidth limit. Second, use the MTR tool for network link analysis to check for packet loss, high latency, or routing anomalies. For cross-region or long-distance transfers, we highly recommend enable and use transfer acceleration to optimize the network path.

• Tool optimization: We recommend using the command line interface ossutil 2.0 for transferring large files or a large number of files. Use its probe command to check the current network status.

• SDK optimization: For large files, you must use the multipart upload and resumable upload features. Configure the part size (part_size) and the number of concurrent threads (num_threads) appropriately. When the network condition is good, increase the part size to reduce the number of requests. Additionally, disable CRC64 validation when initializing the SDK client (for example, set enable_crc=False in Python) and add Content-MD5 to the request header for data integrity checks. This can improve transfer performance while ensuring data security.

How do I control whether a file is previewed or downloaded when accessed through a custom domain?

The Content-Disposition HTTP response header determines whether a file is previewed or downloaded. When you access a file using an OSS bucket endpoint, OSS forces the addition of the Content-Disposition: attachment header for security. However, when you access a file through a custom domain, OSS does not add this header, making the behavior controllable.

• To enable preview: Ensure that the Content-Disposition: attachment header is not set in the object's metadata and that the object's Content-Type (MIME type) correctly matches the file format. For file formats that are not natively supported by browsers, extend preview capabilities in the following ways:

  • For office files such as .doc, .ppt, and .pdf files, integrate the Online document preview with WebOffice service.

  • For special video formats such as .mov, use the video transcoding service to convert them to a web-compatible format for preview.

  • Install a browser extension for the corresponding file type.

• To force download: Manually set the object's Content-Disposition metadata to attachment. The browser will then skip the preview attempt and directly download the file.

• Note

  The <video> or <audio> HTML tags will prioritize playing the media and may ignore the attachment download directive.

What should I do if the domain mapping fails with a message that the domain is already mapped to another bucket?

If a domain is already mapped to another bucket, use one of the following two solutions:

• Use a new subdomain for your current business. If the domain oss-example.cn is already mapped to another bucket, use a new subdomain like static.oss-example.cn for the mapping. This lets you isolate services at the domain level.

• Unmap the domain from the original bucket and then map it to the target bucket. Follow these steps to unmap a domain:

  1. If you have enabled CDN acceleration, you must first modify the origin server information in the CDN service so that the accelerated domain no longer points to the OSS bucket endpoint. This prevents CDN back-to-origin failures. For instructions, see Configure an origin server.

  2. Go to the Buckets page, click the name of the bucket that the domain is currently mapped to, and then in the left navigation pane, click Bucket Settings > Domain Names.

  3. In the domain list, find the target domain and click Unmap in the Actions column. In the dialog box that appears, click OK to unmap the domain.

Why does access fail when "Domain B is CNAME'd to Domain A, and Domain A is mapped to OSS"?

This fails because OSS strictly validates the Host field in the HTTP request header. The Host header must exactly match the domain that is actually mapped in the bucket (Domain A). When a user accesses Domain B, the Host header is "Domain B," which does not match the mapped domain, causing the validation to fail. Therefore, you must directly map the public-facing domain (Domain B) to the bucket instead of using a CNAME chain between domains.

Why is the custom domain not working or still pointing to an old address after configuration?

This is possibly due to DNS caching delays on your local machine and at your internet service provider. The issue typically resolves after waiting about 10 minutes and trying again.

To improve resolution efficiency, DNS nodes at various levels cache domain resolution results for a period determined by the TTL (Time-to-Live) value. After you change a CNAME record, outdated caches may continue to direct requests to the old address until the TTL expires. Try clearing your local DNS cache or wait for the cache to refresh automatically before trying again. The commands to clear the local DNS cache for different operating systems are as follows:

ipconfig /flushdns

 sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

 sudo systemd-resolve --flush-caches

How can I access OSS files with a long-lived URL that does not require a signature?

Create long-lived, signature-free URLs in two ways:

• Set the file to public-read: The object will be accessible to anyone without restriction. To prevent extra costs from unauthorized use of your resources, be sure to configure a hotlink protection policy in OSS to restrict access sources.

• Accelerate access to OSS through CDN: Keep the OSS object permission as Private and enable the private bucket back-to-origin feature in your CDN to provide public read access. A CDN offers better access performance and caching capabilities. To prevent resource theft, you need to configure hotlink protection rules at the CDN level.

After mapping a custom domain, can I still use the old file URLs?

Yes. Mapping a custom domain name does not affect access through the original OSS bucket endpoint. Both methods can coexist. To get the old file URLs, see Use a presigned URL to download a file.

After mapping a custom domain to an OSS bucket, can it only be accessed via a public endpoint? Is it also possible to use it for internal (private) network access?

A custom domain mapped to an OSS bucket is exclusively for public network access and cannot be used for internal (private) access.

The custom domain feature in OSS operates by creating a CNAME record with your DNS provider. This record maps your domain to the public endpoint of an OSS bucket (such as examplebucket.oss-cn-hangzhou.aliyuncs.com). This mechanism is specifically designed to enable public access to OSS resources via your own domain.

In contrast, internal network access must use an Alibaba Cloud internal endpoint (such as oss-cn-hangzhou-internal.aliyuncs.com). This private access is restricted to Alibaba Cloud resources (such as ECS and Function Compute) located within the same region and VPC as the bucket. Since internal endpoints are not resolvable by public DNS and cannot be the target of a CNAME record, a custom domain cannot be used for internal access.

Why are my HTTP requests being automatically redirected to HTTPS when using a custom domain?

This happens because the force redirect to HTTPS feature is enabled for your custom domain. This setting automatically redirects all incoming HTTP requests to their HTTPS equivalent.

While OSS itself does not natively support forced redirection, this behavior is enabled at the CDN level. When you use Alibaba Cloud CDN with your custom domain and an HTTPS certificate, you can activate the force redirect (HTTP → HTTPS) option in the CDN console. This instructs the CDN to return a 301 or 302 response to any HTTP request, prompting the browser to resend the request over HTTPS.

To permit both HTTP and HTTPS access, navigate to the Alibaba Cloud CDN console, select the relevant domain, and change the Redirect Type to Default. For detailed instructions, see Configure URL redirection.