Serve Source Configuration on Custom Domains

This guide covers the steps to use your own domain instead of the RudderStack domains for fetching the source configuration response.

Setup overview

When the RudderStack SDK is loaded, it uses the source write key to fetch the required source configuration from RudderStack. For this reason, the distribution settings in this scenario are slightly different as you need to explicitly allowlist the Authorization header to make sure it is sent along with each request.

The SDK makes a GET request to the https://api.rudderstack.com/sourceConfig URL to fetch the source configuration and uses the write key as the authorization header.

Create a new distribution by following these steps:

1. Log in to your AWS console.
2. Click Services and go to Network & Content Delivery > CloudFront.
3. Click Create a CloudFront distribution.

The following table gives a high-level overview of the required cache policy, origin request policy, and response headers policy for fetching the source configuration response:

Step 1: Configure distribution

The following sections highlight the required distribution settings.

Origin

Default cache behavior settings

Cache key and origin requests

Select Cache policy and origin request policy (recommended) and configure the following settings:

Cache policy settings

Create a cache policy with the following settings:

Origin request policy settings

Create a new origin request policy with the following settings:

For non-AWS setups, you may also need to add the Authorization header to the origin request policy.

Additional distribution settings

The following table summarizes the settings:

Step 2: Deploy distribution

Click Create distribution and wait for CloudFront to be deployed:

Add CNAME Record to DNS

Once your distribution is deployed, create a CNAME record for the subdomain you wish to use along with the distribution URL.

Step 3: Fetch source configuration

To use a custom URL to fetch the source configuration, add it as an option when loading the SDK.

An example of how to use a custom URL to fetch the JavaScript SDK source configuration is shown below:

rudderanalytics.load(
  SOURCE_WRITE_KEY,
  DATA_PLANE_URL, {
    configUrl: "https://<YOUR_CUSTOM_DOMAIN>",
  }
)

Use custom SSL certificates

To use a custom domain for your use case, you can request or import an SSL certificate with your CDN provider. Note that this is an optional setting.

To use the AWS Certificate Manager with CloudFront, choose the relevant ACM/IAM certificate in the Custom SSL certificate field:

You can choose your subdomain or use a wildcard domain *.yourdomain.com to set up multiple subdomains.

The AWS Certificate Manager will guide you through the verification by email or DNS TXT records. You will be able to choose your own domain for SSL certificates once verified.

Custom request header for GCP external load balancer

If you’re setting up a custom domain using the GCP External HTTPS Load Balancer, make sure to add a custom request header in your backend service configuration:

Questions? Contact us by email or on Slack