Articles on: Getting Started

Custom Domains

Note: You must have a Dedicated infrastructure plan subscription or higher to access the Custom domain feature.

Domain customization allows you to use your domain instead of redirecting your consumers to the Cloud-IAM domain. It will help you maintain consistency and give a frictionless experience to your consumers.

In this article, we will assume that the domain my-custom.domain.tld will serve requests from the deployment

Custom domain

A CNAME entry must be created in the customer DNS registar with name my-custom.domain.tld that targets

Note: if you plan to create my-custom.domain.tld and my-custom is a DNS zone of domain.tld, then you'll need to create an ALIAS record instead of a CNAME. The ALIAS record must point to (be careful to add the trailing .)

In the end-user point of view my-custom.domain.tld becomes an alias of

The requests still go straight from the user's browser to the Cloud-IAM deployment without any additional server in the middle. Please note that the JWT token issuer (claim iss) will reflect your custom domain.

The requests are TLS encrypted end-to-end.

Once done, simply declare it through the Cloud-IAM console. This will trigger the certificate generation and installation in minutes.

Attach the custom domain to the deployment


Cloud-IAM takes the responsibility of generating a valid TLS certificate for my-custom.domain.tld (via Let'sEncrypt ❤️).
The generated certificates are Domain Validation.

Despite the type of validation does not impact the strength of security associated with the certificate, customers might want to use their own OV or EV certificates or simply manage the certificate lifecycle by their self.
Cloud-IAM support the upload of customer certificates in place of the generated certificates.

Note that in this case, it is the responsibility of the customer to renew the certificate before it expires.

If the customer wants to use their own certificate, they must provide them via the Cloud-IAM API.

$ DOMAIN=sub.domain.tld
$ DEPLOYMENT_ID=00000000-0000-0000-000000000000
$ TOKEN=$( ... | jq -r .access_token )
$ curl -X PUT -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
       "${DEPLOYMENT_ID}/custom-domains/${DOMAIN}" -d "{
  \"certPem\": \"-----BEGIN CERTIFICATE-----\nMIIEHDC...\n-----END CERTIFICATE-----\n\",
  \"chainPem\": \"-----BEGIN CERTIFICATE-----\nMIIEWDC...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIDuzCC...\n-----END CERTIFICATE-----\n\",
  \"fullChainPem\": \"-----BEGIN CERTIFICATE-----\nMIIEHDC...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIEWDC...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIDuzCC...\n-----END CERTIFICATE-----\n\", 
   \"privateKeyPem\": \"-----BEGIN PRIVATE KEY-----\nMIIEvQIBAD..\n-----END PRIVATE KEY-----\n", 
   \"privateKeyPassword\": \"00000000-00000000-00000000-00000000", 

certPem: contains the X509 certificate for the domain in a PEM format
chainPem: contains the list of X509 certificates of the Certification Authority (in the order intermediate CA, Root)
fullChainPem: contains the list of X509 certificates of the certificate of the domain and the Certification Authority (in the order domain certificate, intermediate CA, Root)
privateKeyPem: contains the private key of the domain certificate
privateKeyPassword: contains an optional password used to cipher the private key of the domain certificate. Leave null if the private key is not protected

How to setup a reverse-proxy
How to setup a CDN

Updated on: 10/05/2023

Was this article helpful?

Share your feedback


Thank you!