Custom Domains

Last modified: January 22, 2024

1 Introduction

Mendix Cloud supports adding custom domains such as https://myapp.mycompany.com/ to your environments. Because Mendix Cloud only allows HTTPS connections, you have to provide a custom domain certificate (an SSL/TLS certificate). This how-to walks through the process.

This how-to explains how to do the following:

  • Generate a certificate request for your custom domain
  • Upload a custom domain certificate to Mendix Cloud
  • Renew a custom domain certificate
  • Configure a custom domain for your environment

2 Prerequisites

2.1 General Prerequisites

Before starting this how-to, you need to have the following prerequisites:

  • Basic knowledge of DNS (Domain Name System)
  • Basic knowledge of SSL/TLS certificates:
    • What is an SSL/TLS certificate and what it is used for?
    • What is an intermediate certificate chain and what it is used for?
    • What is an SSL/TLS private key and what it is used for?
    • What is a certificate request and what it is used for?
  • Basic knowledge of certificate authorities (such as GeoTrust, Thawte, Verisign, RapidSSL, GoDaddy, Comodo)
  • A licensed node that you have transport rights to

2.2 Create and Configure a CNAME Record

Before configuring your custom domain in Mendix Cloud, you need to configure a DNS record for your custom domain with your domain registrar or DNS provider.

Create a CNAME (Canonical Name) record and point it to [YOUR-CUSTOM-DOMAIN].cname.mendix.net.. For example, if your custom domain is myapp.mycompany.com, create a CNAME record pointing to myapp.mycompany.com.cname.mendix.net. so that Mendix can direct your custom domain to your Mendix app.

3 Managing Custom Domains in Mendix Cloud

Custom domain certificates (or just “certificates”) are managed at the application level; in contrast, custom domains are managed per environment.

You can have more than one certificate for an application. For example, when your certificate expires, you can upload a new certificate next to your old certificate.

You can choose which certificate to use when you configure a custom domain for an environment (test, acceptance, or production).

To manage custom domains, follow these steps:

  1. Go to the Developer Portal.

  2. Open the Environments page for your app.

  3. Switch to the Custom Domains tab.

If you already have a signed SSL/TLS certificate, skip to Uploading Your Own Custom Domain Certificate, below.

4 Obtaining a New Signed Certificate

If you do not have an SSL/TLS certificate, you can order one from a certificate authority (such as GeoTrust, Thawte, Verisign, RapidSSL, GoDaddy, or Comodo). To get a signed SSL/TLS certificate from a certificate authority, you need to provide a certificate signing request (CSR). A private SSL/TLS key and a CSR tied to that key can be created in Mendix Cloud for you.

4.1 Generating a Certificate Request for your Custom Domain

To create a CSR and an RSA (Rivest–Shamir–Adleman) encryption key, follow these steps:

  1. Click New in the Custom Domains tab.

  2. Click Create a Certificate Request.

  3. Fill in the required fields.

  4. Click Generate.

    An SSL/TLS private key and a certificate request is generated. The certificate request will be shown in PEM (Privacy-Enhanced Mail) format.

You can now go to your certificate authority to get a signed SSL/TLS certificate.

4.2 Uploading a Signed Certificate

Once you have a signed SSL/TLS certificate, you can upload it by following these steps:

  1. In the Custom Domains tab, select the custom domain certificate that you want to upload.

  2. Click Upload Signed Certificate.

  3. Add a Description of your certificate.

  4. Paste the signed TLS Certificate (in PEM format).

  5. Paste an Intermediate Certificate Chain. This is optional, but highly recommended. The intermediate certificate chain is provided by your certificate authority.

You can now configure your custom domain. See Configuring a Custom Domain, below.

5 Uploading Your Own Custom Domain Certificate

To upload a custom domain certificate, you need to have the following things prepared:

  • An SSL/TLS certificate that is self-signed or signed by your certificate authority
  • An intermediate certificate chain provided by your certificate authority
  • An SSL/TLS private key

To upload the custom domain certificate, follow these steps:

  1. Click New in the Custom Domains tab.

  2. Click Upload Certificate, Chain and Key.

  3. Type a Description for the certificate.

  4. Paste the signed TLS Certificate.

  5. Paste the TLS Private Key.

  6. Paste an Intermediate Certificate Chain. This is optional, but most browsers require it. The intermediate certificate chain is provided by your certificate authority.

  7. Click Save to save your new custom domain certificate. It will be uploaded to Mendix Cloud automatically.

You can now configure your custom domain. For details, see Configuring a Custom Domain, below.

You can add as many certificates as you need. Each certificate will be listed with the description you gave it. Make sure to give them meaningful names so that you can identify them easily.

List of certificates

6 Renewing a Custom Domain Certificate

Custom domain certificates have an expiry date. There are two methods for renewing a custom domain certificate that is about to expire:

  • Create a new custom domain certificate (recommended)

  • Update an existing custom domain certificate

You can handle an expiring domain certificate by replacing it with a new one. You can do this in one of two ways:

You can now select the new certificate for your custom domain (for more information, see Configuring a Custom Domain), below.

6.2 Method 2: Renewing by Updating an Existing Custom Domain Certificate

You can also edit an existing custom domain certificate.

Edit a certificate

7 Configuring a Custom Domain

Once a custom domain certificate has been uploaded, you can configure a custom domain for one of your application environments.

To configure a custom domain for your application environment, follow these steps:

  1. Go to your app’s Environments page.

  2. Click Details ( ) on the environment you want to configure.

    The Details icon
  3. Go to the Network tab.

  4. In the Custom Domains section, you can manage your custom domains.

  5. Click Add to create a new custom domain (or Edit to edit an existing one).

  6. Type the Domain name.

  7. Select a Certificate from the drop-down list of uploaded certificates.

  8. Click Save to save your custom domain. It will be configured for your application environment automatically.

8 Frequently Asked Questions

8.1 Can You Create a *.mycompany.com Wildcard Certificate?

Yes. However, when you create the certificate request via Mendix Cloud, you will only be able to use the wildcard certificate for the environments of a single app. This is because the private key is stored securely and is not accessible to you or Mendix Support, so you will not be able to reuse it in other apps.

If you have your own custom domain certificate, you can upload it to all of your apps and use it for all the environments of all of your apps.

You can select the same wildcard certificate per environment by using it with different subdomains. For example, test.mycompany.com, accp.mycompany.com, and app.mycompany.com.

8.2 How Do You Construct an Intermediate Certificate Chain Properly?

Your certificate is signed by the certificate authority (CA). They sign your certificate with their intermediate certificate, rather than directly with the root certificate. Their intermediate certificate is signed with their own root certificate.

To reach the root certificate, you must link your certificate via the intermediate certificate chain, which is usually just one intermediate certificate. Occasionally, a CA requires more than one intermediate certificate. You do not need to provide the root certificate, because every web browser has it in its trusted keystore.

8.3 How Do You Get my SAML Metadata or CommunityCommons.GetApplicationUrl to Use the Custom URL?

For certain use cases, it is important for the Mendix runtime to know the public URL of your applications. This is most commonly needed when your app generates links back to itself. To tell the runtime where it lives, set the ApplicationRootUrl custom runtime setting. To set the custom runtime setting, follow the instructions in the Custom Runtime Settings section of Environment Details.

8.4 Can You Configure Multiple Custom Domains for the Same Application?

Yes, you can configure multiple custom domains for the same application. Please note that this can only be done by uploading multiple own custom domain certificates. You can only generate one certificate signing request for one custom domain for your application.

9 Read More