Chapter 6. Custom Domain

To complete the branding of your Developer Portal, you’ll probably want to have it appear under your own corporate domain name at a location like https://developer.mydomain.com or https://api.mydomain.com. The most popular option among 3scale customers is developer.mydomain.com.

The 3scale SaaS platform manages the SSL certificate, issued by the Let’s Encrpyt certificate authority, for the custom developer portal domain.

Follow the steps below to change the URL of your Developer Portal to one under your own company domain name.

6.1. Prerequisites

  • You must be subscribed to a paid 3scale plan
  • You must have a Red Hat account with a valid 3scale entitlement

If you need help with your Red Hat account, contact Red Hat customer service

6.2. Step 1: Add a CNAME entry to your DNS setup

Within your DNS, add a CNAME record pointing your domain name to autossl.3scale.net. For example, a domain developer.mydomain.com pointing to autossl.3scale.net may look like:

developer.mydomain.com.  CNAME  autossl.3scale.net.

Normally you would want to make the change to your custom domain before you allow public access to your Developer Portal. If you already have public users, bear in mind that it’s not possible to define a redirect from mydomain.3scale.net to your custom domain, so you’ll need to inform your users about the domain change.

It’s best to implement the CNAME in advance. In the rare case that this isn’t possible – such as if you have an existing site in public use at that domain – please contact Red Hat support to determine the best way to synchronize a switchover.

It may take some time for the changes with your DNS to propagate. Validate that your CNAME record has been configured correctly. You may use the following commands to validate CNAME configuration:

dig cname developer.mydomain.com

or

nslookup developer.mydomain.com

6.3. Step 2 (Optional): Add a CAA Record to Your DNS Setup

If you are using Certificate Authority Authorization (CAA), you must allow the Let’s Encrypt certificate authority to issue certificates for your domain by adding a CAA record for the letsencrypt.org address on the root domain. For example, a domain mydomain.com pointing to letsencrypt.org may look like:

mydomain.com.  CAA 0 issue "letsencrypt.org"

Depending on your DNS provider, you may need to add the 0 issue "letsencrypt.org" flag, tag, and value to the list of certificate authorities in the CAA record for your root domain. Refer to your DNS provider for instructions on how to configure CAA records.

6.4. Step 3: Contact Red Hat support

Once you have added a CNAME entry and, optionally, added a CAA record to your DNS setup, you must open a Red Hat support case to request the Developer Portal domain change, specifying the following:

  • Select the "Red Hat 3scale API Management Platform" product
  • In the case description, include the following:

    • The Admin Portal domain of your 3scale account, for example: mydomain-admin.3scale.net
    • The custom domain for the Developer Portal that you would like to use, for example: developer.mydomain.com

Once you have submitted the ticket, Red Hat support will validate the DNS setup and either provide confirmation once the change is applied, or respond appropriately.

6.5. Step 4: Review Your Developer Portal

Once you receive confirmation from Red Hat support regarding your domain change, review and test your Developer Portal. Ensure any non-relative links to your custom domain are updated.