Map custom domain names - Object Storage Service - Alibaba Cloud Documentation Center

After you upload objects to a bucket, Object Storage Service (OSS) automatically generates URLs for the uploaded objects. You can use these URLs to access the objects. If you want to access the objects by using custom domain names, map the custom domain names to the buckets in which the objects are stored and add CNAME records for the custom domain names.

Prerequisites

A custom domain name is registered. For more information, see Register a domain name on Alibaba Cloud.
An Internet Content Provider (ICP) filing is completed for the custom domain name that you want to map to a bucket in the Chinese mainland.
For more information about how to apply for an ICP filing, see What is an ICP filing?

Limits

Custom domain names cannot contain Chinese characters.
OSS does not impose limits on the number of custom domain names that can be mapped to buckets per Alibaba Cloud account.
Each custom domain name can be mapped to only one bucket. Each bucket can be mapped to up to 100 custom domain names.
If you map a custom domain name to a bucket in the OSS console, the domain name cannot contain wildcard characters. If Alibaba Cloud CDN is enabled to accelerate access to OSS resources, you can map a custom domain name that contains wildcard characters to the bucket. However, the custom domain name does not appear in the OSS console.

Usage notes

You can map a custom domain name to a bucket to meet the requirements in the following scenarios:

You want to make sure that the image objects in a bucket that is created in a region in the Chinese mainland after September 23, 2019 can be previewed but not downloaded when you access the objects by using a browser.
You want to make sure that the web pages of a static website that is hosted in an OSS bucket can be accessed but not downloaded.

Rules for using custom domain names

For example, a public-read object named exampleobject.jpg is stored in the root directory of the bucket named examplebucket in the China (Hangzhou) region. The custom domain name www.example.com is mapped to the bucket. The URLs that are used to access the object are different before and after the custom domain name is mapped to the bucket.

Before the custom domain name is mapped to the bucket
You can use the following URL that contains the default domain name of the bucket to access the exampleobject.jpg object: https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject.jpg.
After the custom domain name is mapped to the bucket
You can use the following URL that contains the custom domain name mapped to the bucket to access the exampleobject.jpg object: https://www.example.com/exampleobject.jpg.
Note
After you map a custom domain name to a bucket, you can preview an image object in the bucket when you access the image object. If the image object cannot be previewed but is downloaded as an attachment, the browser may not support the preview of images in specific formats. To resolve this issue, you must install a plug-in that allows you to preview images in specific formats in a browser.

Use the OSS console

Map a custom domain name to a bucket.
1. Log on to the OSS console.
2. In the left-side navigation pane, click Buckets. On the Buckets page, find and click the desired bucket.
3. In the left-side navigation pane, choose Bucket Settings > Domain Name Management.
4. On the Domain Management page, click Map Custom Domain Name.
5. In the Map Custom Domain Name panel, enter the domain name that you want to map to the bucket in the Domain Name field.
  Domain names that contain wildcard characters are not supported. For example, *.example.com is not supported.
  If a message that indicates a domain name conflict appears, the custom domain name is mapped to another bucket. To resolve this issue, you can map another domain name to the bucket or verify the ownership of the custom domain name to forcibly map the domain name to the bucket. If you verify the ownership of the domain name to forcibly map the domain name to the bucket, the mapping between the domain name and the previous bucket is removed.

Add a CNAME record.

If the custom domain name is managed by your Alibaba Cloud account, perform the following steps to automatically add a CNAME record:
1. In the Map Custom Domain Name panel, turn on Add CNAME Record Automatically.
  Important
  - If the custom domain name has an existing CNAME record, the existing record is overwritten by the new CNAME record.
  - If a root domain name that you want to map to a bucket has an existing CNAME record, you can map a subdomain name of the root domain name to the bucket.
2. Click Submit.

If the custom domain name is not managed by your Alibaba Cloud account, manually add a CNAME record.

If the custom domain name is not hosted by Alibaba Cloud, you must add a CNAME record to the Domain Name System (DNS) of your DNS provider.

The following steps describe how to manually add a CNAME record for a custom domain name that is hosted by Alibaba Cloud but not managed by your Alibaba Cloud account:

Log on to the Alibaba Cloud DNS console.
On the Domain Name Resolution page, click DNS Settings in the Actions column of the custom domain name.

On the DNS Settings page, click Add DNS Record. In the Add DNS Record panel, configure the parameters. The following table describes the parameters.

Parameter	Description
Record Type	The type of the record that you want to add. Select CNAME from the Record Type drop-down list.
Hostname	The host record based on the prefix of the custom domain name. To add a root domain, such as `aliyun.com`, enter @. To add a subdomain name, enter the prefix of the subdomain name. For example, if the custom domain name is `help.aliyun.com`, enter help. To map all subdomain names to the public domain name of the bucket, enter *.
DNS Request Source	The DNS line that is used to resolve the custom domain name. To allow the system to select the optimal line, we recommend that you select Default for this parameter.
Record Value	The public domain name of the bucket. The domain name of a bucket is in the `BucketName.Endpoint` format. For example, the public endpoint of the China (Hangzhou) region is `oss-cn-hangzhou.aliyuncs.com`. If you create a bucket named examplebucket in the China (Hangzhou) region, the domain name of the bucket is `examplebucket.oss-cn-hangzhou.aliyuncs.com`.
TTL Period	The interval at which the record is updated. Retain the default value. Note A delay exists before the TTL period takes effect.

Click OK.
A new CNAME record immediately takes effect. A modified CNAME record requires up to 72 hours to take effect.

Use the custom domain name to access OSS resources.
After you map a custom domain name to a bucket, you can use the URLs of the objects in the bucket to access the objects over HTTP. The URLs of objects in the bucket are in the following format: http://YourDomainName/ObjectName. If you want to use the URLs of objects in the bucket to access the objects over HTTPS, you must host your SSL certificate in OSS. For more information, see Host SSL certificates.
For example, you create a bucket named examplebucket in the China (Hangzhou) region, store an object named exampleobject.jpg in the bucket, map the custom domain name example.com to the bucket, and host the SSL certificate. In this case, you can access the exampleobject.jpg object by using the following URL: https://example.com/exampleobject.jpg.

Check whether the CNAME record takes effect

You can run the ping or lookup command to check whether a specific CNAME is in effect. If the request is redirected to *.oss-cn-*.aliyuncs.com, the CNAME is in effect.

Verify the ownership of a custom domain name

If the custom domain name that you want to map to a bucket is not managed by your Alibaba Cloud account or is registered with another vendor, you must verify the ownership of the domain name to map the domain name to the bucket.

Click Obtain TXT.
Note
OSS randomly generates a token for the domain name, which includes the following fields: Domain Name, Host Record, and Value. Record the token information.
Add a TXT record to your DNS records. Enter the recorded values of the Host Record and Record Value parameters in Step 1 and retain the default settings of other parameters.
For more information about how to add a CNAME record, see the steps on how to manually add a CNAME record in this topic.
In the Map Custom Domain Name panel, read and select I have added the TXT record. Continue submission..
If your configurations are valid, OSS maps the custom domain name to the bucket.

Remove a custom domain name mapping

If you no longer use a custom domain name, you can remove the mapping between the custom domain name and the bucket.

If Alibaba Cloud CDN is enabled for the custom domain name mapped to a bucket, you must modify the origin of Alibaba Cloud CDN. This way, the custom domain name no longer points to the OSS domain name. For more information, see Configure an origin server.
In the left-side navigation pane, choose Bucket Settings > Domain Name Management.
Click Manage Mapping Configurations in the Actions column of the custom domain name for which you want to remove the mapping.
In the Manage Mapping Configurations panel, click Unbind. In the message that appears, click OK.

FAQ

Can I map a subdomain that is connected to Web Application Firewall (WAF) and has content to an OSS bucket?

Yes, you can map a subdomain that is connected to WAF and has content to an OSS bucket. For example, if help.aliyun.com is connected to WAF, you can map the subdomain name to an OSS bucket.

References

If you want to improve upload and download performance, you can map an acceleration endpoint to a bucket. For more information, see Map an acceleration endpoint.
If you want to access resources in OSS buckets by visiting a static website, configure static website hosting for the buckets. For more information, see Configure static website hosting and Tutorial: Use a custom domain name to configure static website hosting.
If you want to use HTTPS to access a custom domain name, you must upload your SSL certificate in the OSS console. For more information, see Host SSL certificates.