PutCname - Map custom domain to OSS bucket - Object Storage Service

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

API	Action	Description
PutCname	oss:PutCname	Maps a custom domain name to a bucket.
	yundun-cert:DescribeSSLCertificatePrivateKey	When mapping a custom domain name to a bucket, if a certificate is attached, these three permissions are required.
	yundun-cert:DescribeSSLCertificatePublicKeyDetail
	yundun-cert:CreateSSLCertificate

Request syntax

POST /?cname&comp=add HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: GMT Date
Authorization: SignatureValue
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
  </Cname>
</BucketCnameConfiguration>

Request headers

All request headers in a PutCname request are common request headers. For more information, see Common request headers.

Request elements

Element	Type	Required	Example	Description
BucketCnameConfiguration	Container	Yes	N/A	Container for the CNAME record. Parent nodes: none Child nodes: Cname
Cname	Container	Yes	N/A	Container for the CNAME information. Parent nodes: BucketCnameConfiguration Child nodes: Domain
Domain	String	Yes	example.com	The custom domain name to bind. Parent nodes: Cname Child nodes: none
CertificateConfiguration	Container	No	N/A	Container for the certificate configuration. Parent nodes: Cname Child nodes: CertId, Certificate, PrivateKey, PreviousCertId, Force, and DeleteCertificate
CertId	String	No	493****-cn-hangzhou	The certificate ID. Parent nodes: CertificateConfiguration Child nodes: none
Certificate	String	No	-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----	The public key of the certificate. Parent nodes: CertificateConfiguration Child nodes: none
PrivateKey	String	No	-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----	The private key of the certificate. Parent nodes: CertificateConfiguration Child nodes: none
PreviousCertId	String	No	493****-cn-hangzhou	The current certificate ID. Unless Force is set to true, OSS verifies that this value matches the existing certificate ID before overwriting. Important If PreviousCertId is not specified when you bind a certificate, you must set Force to true. Parent nodes: CertificateConfiguration Child nodes: none
Force	String	No	true	Whether to overwrite the existing certificate. Valid values: true: Overwrite the certificate. false: Do not overwrite the certificate. Parent nodes: CertificateConfiguration Child nodes: none
DeleteCertificate	String	No	true	Whether to delete the certificate. Valid values: true: Delete the certificate. false: Do not delete the certificate. Parent nodes: CertificateConfiguration Child nodes: none

Response headers

This operation returns only Common Response Headers.

Examples

Sample requests

Map a domain name

POST /?cname&comp=add HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 24 Sep 2015 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
  </Cname>
</BucketCnameConfiguration>

Bind a certificate to the domain name

POST /?cname&comp=add HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 24 Sep 2015 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
    <CertificateConfiguration>
      <CertId>493****-cn-hangzhou</CertId>
      <Certificate>-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----</Certificate>
      <PrivateKey>-----BEGIN CERTIFICATE----- MIIDhDCCAmwCCQCFs8ixARsyrDANBgkqhkiG9w0BAQsFADCBgzELMAkGA1UEBhMC **** -----END CERTIFICATE-----</PrivateKey>
      <PreviousCertId>493****-cn-hangzhou</PreviousCertId>
      <Force>true</Force>
    </CertificateConfiguration>
  </Cname>
</BucketCnameConfiguration>

Unbind a certificate from the domain name

To unbind the certificate from the domain name, set DeleteCertificate to true.

POST /?cname&comp=add HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Type: application/xml
Content-Length: 186
Date: Thu, 24 Sep 2015 15:39:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<BucketCnameConfiguration>
  <Cname>
    <Domain>example.com</Domain>
      <CertificateConfiguration>
      <DeleteCertificate>True</DeleteCertificate>
    </CertificateConfiguration>
  </Cname>
</BucketCnameConfiguration>

Sample success responses

content-length: 0
x-oss-console-auth: success
server: AliyunOSS
x-oss-server-time: 980
connection: keep-alive
x-oss-request-id: 5C1B138A109F4E405B2D
date: Wed, 15 Sep 2021 03:33:37 GMT

OSS SDKs

You can call PutCname using the following OSS SDKs:

ossutil

For information about the ossutil command that corresponds to the PutCname operation, see put-cname.

Error codes

Error code	HTTP status code	Description
InvalidArgument	400	The CNAME record format is invalid. Check the error fields in the returned XML body for details.
NeedVerifyDomainOwnership	403	Domain name ownership is not verified. To verify domain ownership: Call CreateCnameToken to create a CNAME token for domain ownership verification. Note By default, a CNAME token expires within 72 hours after it is created. If a new CNAME token is created within the validity period of the existing token, the existing CNAME token is returned. Add a TXT record with your domain name provider. For example, to verify `example.com`, add a TXT record with host `_dnsauth.example` and set the record value to the CNAME token from Step 1. Keep default settings for other parameters. See the "Manually add a CNAME record" section in Map custom domain names. Note The TXT record may take several minutes to propagate. Call PutCname to map the custom domain name.
CnameDenied	403	The domain name is in use.
CnameIsForbidden	403	The domain name is reserved by OSS and cannot be mapped.
CnameIsRisk	403	The domain name is flagged as high-risk and cannot be mapped.
NoSuchCnameInRecord	404	The domain name does not have an ICP license. Apply for an ICP filing through What is Domains?.
CnameAlreadyExists	409	Possible causes: The domain name is mapped to another bucket in the current account. The CnameType in the error response is CNAME_OSS. The domain name is used for image processing. The CnameType in the error response is CNAME_IMG. Remove the existing mapping first. See the "CnameAlreadyExists" section in HTTP 409 status code.