Help Center/ Object Storage Service/ API Reference/ Bucket APIs/ Custom Domain Names/ Configuring a Custom Domain Name for a Bucket
Updated on 2026-04-16 GMT+08:00
View PDF
Share

Configuring a Custom Domain Name for a Bucket

Functions

This API is used to configure a custom domain name for a bucket. Once configured, you can access the bucket through the domain name. You need to ensure that DNS can resolve the custom domain name to OBS. For more information about custom domain names, see Accessing a Bucket Using a User-Defined Domain Name.

Constraints

Table 1 Constraints

Item

Description

Bucket version

Only buckets whose version is 3.0 or later support user-defined domain names. To check the version of a bucket, go to OBS Console, click the bucket name and go to the Overview page, and find the version in the Basic Information area.

Number of domain names

By default, a bucket can have up to 100 user-defined domain names bound.

Functions
  • A user-defined domain name can be bound to only one bucket.
  • Chinese domain names are not supported.
  • The suffix of a user-defined domain name can contain 2 to 63 uppercase or lowercase letters.
  • As required by the MIIT, if the bucket which a user-defined domain name is bound to is in a Chinese mainland region, you must complete the ICP filing.
  • To access an OBS bucket over the Internet, typically use a user-defined domain name. For intranet access, it is recommended to use the bucket's default domain name (bucketName.obs.endpoint.myhuaweicloud.com).
NOTE:

If an acceleration domain name is also required, to prevent objects in OBS buckets from being directly downloaded upon access, you need to perform other required operations after the user-defined domain name and the acceleration domain name have been configured. For details, see With CDN Acceleration Enabled, Why Are the Objects in My OBS Bucket Directly Downloaded When I Access Them?

Authorization Information

To call this API, you must be the bucket owner or have the permission to configure a custom domain name for a bucket. You are advised to use IAM or bucket policies for authorization. For details about OBS authorization methods, see Differences Between OBS Permissions Control Methods.

  • If you use IAM for authorization, you need to use either role/policy-based authorization or identity policy-based authorization and configure the required permissions:
    • If you use role/policy-based authorization (IAM v3 APIs in the old IAM version), you need to grant the obs:bucket:PutBucketCustomDomainConfiguration permission. For details, see Creating a Custom IAM Policy.
    • If you use identity policy-based authorization (IAM v5 APIs in the new IAM version), you need to grant the obs:bucket:putBucketCustomDomainConfiguration permission, as shown in the following table. For details, see Creating a Custom IAM Identity Policy.

      Action

      Access Level

      Resource Type (*: Required)

      Condition Key

      Alias

      Dependencies

      obs:bucket:putBucketCustomDomainConfiguration

      Write

      bucket *

      -

      -

      -
      • obs:EpochTime
      • obs:SourceIp
      • obs:TlsVersion
      • obs:CustomDomain
  • If you use bucket policies for authorization, you need to grant the obs:bucket:PutBucketCustomDomainConfiguration permission. For details, see Creating a Custom Bucket Policy.

Request Syntax

The format of the request for binding a custom domain name and a server certificate is as follows: 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
 
PUT /?customdomain=domainname HTTP/1.1
User-Agent: curl/7.29.0
Host: bucketname.obs.region.myhuaweicloud.com 
Accept: */*
Date: date
Authorization: authorization string
Content-Length: length
Content-MD5: n58IG6hfM7vqI4K0vnWpog==

<CustomDomainConfiguration> 
    <Name>name</Name> 
    <CertificateId>certificateId</CertificateId> 
    <Certificate>certificate</Certificate> 
    <CertificateChain>certificateChain</CertificateChain> 
    <PrivateKey>privateKey</PrivateKey> 
</CustomDomainConfiguration>

Request Parameters

Table 2 URI parameters

Parameter

Mandatory

Type

Description

customdomain

Yes

String

Definition

Custom domain name of a bucket.

Constraints

A bucket can have a maximum of 30 domain names. One custom domain name can be used for only one bucket.

Range

The value is a string of 0 to 256 characters.

Default Value

N/A

Request Headers

Table 3 Request headers

Header

Type

Mandatory

Description

Content-MD5

String

No

Definition

This header is mandatory when you configure a custom domain name certificate to verify that the content of the request body is consistent with what was sent.

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864.

Example: n58IG6hfM7vqI4K0vnWpog==

Constraints

None

Range

None

Default Value

None

For details about other common headers, see Table 3.

Request Body

The request body parameters are optional. If the request body parameters are empty, the certificates bound to the same custom domain name will be overwritten.

Table 4 Request body parameters

Parameter

Mandatory

Type

Description

Name

No

String

Definition

Certificate name

Constraints

Only uppercase letters, lowercase letters, digits, underscores (_), hyphens (-), and periods (.) are allowed.

Range

The value can contain 3 to 63 characters.

Default Value

N/A

CertificateId

No

String

Definition

Certificate ID. If no certificate ID is specified, the system automatically generates a certificate ID.

Constraints

If you use the CCM service to host a certificate, the specified certificate ID must be the same as that on CCM. If you need to manage the certificates by yourself, do not set the certificate ID in the request.

Range

The value is a string of 16 characters consisting of letters and digits.

Default Value

An automatically generated random certificate ID that consists of 16 characters

Certificate

No

String

Definition

Certificate content, which can contain intermediate and root certificates.

Constraints

  • If CertificateChain contains a certificate chain, only the certificate itself will be extracted from Certificate.
  • Use escape characters \n or \r\n to replace line breaks.

Range

The value is a string of 0 to 65536 characters.

Default Value

N/A

CertificateChain

No

String

Definition

Certificate chain. The value can be passed through the Certificate field.

Constraints

Use escape characters \n or \r\n to replace line breaks.

Range

The value is a string of 0 to 8192 characters.

Default Value

N/A

PrivateKey

No

String

Definition

Private key of a certificate.

Constraints

  • An encrypted private key cannot be uploaded.
  • Use escape characters \n or \r\n to replace line breaks.

Range

The value is a string of 0 to 4096 characters.

Default Value

N/A

Response Syntax

1
2
3
4
5
6
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: request id
x-obs-id-2:  id
Date: date
Content-Length: 0

Response Headers

This response uses common headers. For details, see Table 1.

Response Body

The response of this API does not contain a response body.

Error Responses

No special error responses are returned. For details about error responses, see Table 2.

Sample Request 1: Binding a Custom Domain Name

Binding a custom domain name

1
2
3
4
5
6
7
 
PUT /?customdomain=obs.ccc.com HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com 
Accept: */*
Date: Mon, 14 Jan 2019 08:31:36 +0000
Authorization: OBS UDSIAMSTUBTEST000094:u2kJF4kENs6KlIDcAZpAKSKPtnc=
Content-Length: 0

Sample Response 1

1
2
3
4
5
6
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 000001697692CC5380E9D272E6D8F830
x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCSsfu2GXj9gScHhFnrrTPY2cFOEZuvta
Date: Wed, 13 Mar 2019 10:22:05 GMT
Content-Length: 0

Sample Request 2: Binding a Custom Domain Name

Binding a custom domain name and server certificate

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
 
PUT /?customdomain=obs.ccc.com HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com 
Accept: */*
Date: Mon, 14 Jan 2019 08:31:36 +0000
Authorization: OBS UDSIAMSTUBTEST000094:u2kJF4kENs6KlIDcAZpAKSKPtnc=
Content-Length: 314
Content-MD5: n58IG6hfM7vqI4K0vnWpog==

<CustomDomainConfiguration> 
    <Name>exampleCertName</Name> 
    <CertificateId>exampleCertificateId</CertificateId> 
    <Certificate>exampleCertificate</Certificate> 
    <CertificateChain>exampleCertificateChain</CertificateChain> 
    <PrivateKey>examplePrivateKey</PrivateKey> 
</CustomDomainConfiguration>

Sample Response 2

1
2
3
4
5
6
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 000001697692CC5380E9D272E6D8F830
x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCSsfu2GXj9gScHhFnrrTPY2cFOEZuvta
Date: Wed, 13 Mar 2019 10:22:05 GMT
Content-Length: 0

Using SDKs to Call APIs

You are advised to use OBS SDKs to call APIs. SDKs encapsulate APIs to simplify development. You can call SDK API functions to access OBS without manually calculating signatures.

Java: not supported

Python

C

Go

BrowserJS: not supported

.NET: not supported

Android: not supported

iOS: not supported

PHP: not supported

Node.js: not supported

References

Parent Topic: Custom Domain Names