The following changes in Certificate Authority (CA) used to issue certificates for all Umbraco Cloud sites' for new and existing custom hostnames.

Certificates for new custom hostnames

From September 26, 2022, certificates are issued using 'Google Trust Services' instead of 'DigiCert', and Certificate validity will be decreased from 1 year to 90 days.

Certificates for existing custom hostnames

From October 31, 2022, certificate renewals will no longer use 'DigiCert' as the issuing CA. The renewed certificate will instead be issued by 'Google Trust Services', and certificate validity will be decreased from 1 year to 90 days.

No action is required unless you set a Certificate Authority Authorization (CAA) record on your domain.

From October 31, 2022, Certificate renewals will no longer use 'DigiCert' as the issuing CA. This means that you need to update your CAA record to allow 'Google Trust Services' issuing certificates for your domain.

The CAA record should be changed from:

example.com. IN CAA 0 issue "digicert.com"

to

example.com. IN CAA 0 issue "pki.goog"

To make rewrite rules on Umbraco Cloud as seamless as possible, we've installed the IIS Rewrite Module on all our Umbraco Cloud servers.

You need to use config transform to add rewrite rules.

The rewrite rules should be added to the <system.webServer><rewrite> module in your project's web.config file.

<!--
<rewrite>
    <rules></rules>
</rewrite>
-->

Best practices

When you are doing rewrite rules on Umbraco Cloud there are a few important things to keep in mind:

• Always make sure that you add a condition that negates the Umbraco Backoffice - /umbraco, otherwise, you will not be able to do deployments to/from the environment

• To be able to continue working locally with your Umbraco Cloud project, you also need to add a condition that negates localhost

Hiding the default umbraco.io URL

Once you've assigned a hostname to your Live environment, you may want to "hide" the project's default URL (e.g. example.euwest01.umbraco.io) for different reasons. Perhaps for SEO or to make it clear to your users that the site can be accessed using only the primary hostname.

One approach for this is to add a new rewrite rule to the <system.webServer><rewrite><rules> section in the web.config file. For example, the following rule will redirect all requests for the project example.euwest01.umbraco.io URL to the example.com URL (using HTTPS and including the www. prefix) and respond with a permanent redirect status.

<rule name="Redirect umbraco.io to primary hostname" stopProcessing="true">
  <match url=".*" />
  <conditions>
    <add input="{HTTP_HOST}" pattern="\.umbraco\.io$" />
    <add input="{HTTP_HOST}" pattern="^(dev-|stage-)(.*)?\.umbraco\.io$" ignoreCase="true" negate="true" />
    <add input="{REQUEST_URI}" pattern="^/umbraco" ignoreCase="true" negate="true" />
    <add input="{REQUEST_URI}" pattern="^/App_Plugins" ignoreCase="true" negate="true" />
    <add input="{REQUEST_URI}" pattern="^/sb" negate="true" /> <!-- Don't redirect Smidge Bundle -->
    <add input="{HTTP_COOKIE}" pattern="^(.+; )?UMB_UCONTEXT=([^;]*)(;.+)?$" negate="true" /> <!-- Ensure preview can render -->
	<add input="{HTTP_HOST}" pattern="^localhost(:[0-9]+)?$" negate="true" />
  </conditions>
  <action type="Redirect" url="https://www.example.com/{R:0}" redirectType="Permanent" />
</rule>

Running your site on HTTPS only

Once you've applied a certificate to your site, you can make sure that anybody visiting your site will always end up on HTTPS instead of the insecure HTTP.

To accomplish this, add a rewrite rule to the live environment's web.config in the <system.webServer><rewrite><rules> section.

For example, the following rule will redirect all requests for the site http://example.com URL to the secure https://example.com URL and respond with a permanent redirect status.

<rule name="Redirect HTTP to HTTPS" stopProcessing="true">
  <match url=".*" />
  <conditions>
    <add input="{HTTPS}" pattern="^OFF$" />
    <add input="{HTTP_HOST}" negate="true" pattern="^localhost(:[0-9]+)?$" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/\.well-known/acme-challenge/" />
  </conditions>
  <action type="Redirect" url="https://{HTTP_HOST}/{R:0}" redirectType="Permanent" />
</rule>

Adding a trailing slash to your URLs

It is possible to transform all of your URLs to use a trailing slash consistently for SEO.

To accomplish this, add a rewrite rule to the Live environment's web.config in the <system.webServer><rewrite><rules> section.

For example, the following rule will redirect all requests for https://example.com/page to https://example.com/page/, and respond with a permanent redirect status. This way you can ensure that you use the trailing slashes consistently on your site.

<rule name="Add trailing slash" stopProcessing="true">
  <match url="(.*[^/])$" />
  <conditions>
    <add input="{REQUEST_FILENAME}" negate="true" matchType="IsDirectory" />
    <add input="{REQUEST_FILENAME}" negate="true" matchType="IsFile" />
    <add input="{REQUEST_FILENAME}" negate="true" pattern="(.*?)\.[a-zA-Z0-9]{1,4}$" />
    <add input="{REQUEST_URI}" pattern="^/umbidlocallogin" negate="true" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/umbraco" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/DependencyHandler.axd" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/App_Plugins/" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/\.well-known/acme-challenge/" />
  </conditions>
  <action type="Redirect" url="{R:1}/" />
</rule>

Redirect from non-www to www

Another example would be to redirect from non-www to www:

<rule name="Redirect to www prefix" stopProcessing="true">
  <match url=".*" />
  <conditions>
    <add input="{HTTP_HOST}" negate="true" pattern="^www\." />
    <add input="{HTTP_HOST}" negate="true" pattern="^localhost(:[0-9]+)?$" />
    <add input="{HTTP_HOST}" negate="true" pattern="\.azurewebsites\.net$" />
    <add input="{HTTP_HOST}" negate="true" pattern="\.umbraco\.io$" />
  </conditions>
  <action type="Redirect" url="https://www.{HTTP_HOST}/{R:0}" />
</rule>

Custom Rewrite Rules for Umbraco Cloud

An example configuration to help ensure your custom rules integrate properly:

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <rewrite xdt:Transform="Insert">
        <rules>
          <!-- Add your custom rules here -->
        </rules>
      </rewrite>
    </system.webServer>
  </location>
</configuration>

Troubleshooting

Sometimes, you might experience an issue where a .azurewebsites.net link will appear instead of the custom hostname. In this case, a restart will usually fix the issue, however, it is not ideal that this appears at all.

The following redirect is a way to amend the issue where the .azurewebsites.net link appears instead of the hostname. It will redirect from the .azurewebsites.net link to the hostname of the website, should this link be called instead.

<rule name="Redirects azurewebsites.net to actual domain" stopProcessing="true">
  <match url=".*" />
  <conditions>
    <add input="{HTTP_HOST}" pattern="^(.*)?.azurewebsites.net$" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/umbraco" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/DependencyHandler.axd" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/App_Plugins" />
    <add input="{REQUEST_URI}" negate="true" pattern="localhost" />
  </conditions>
  <action type="Redirect" url="https://www.hostname.com/{R:0}" appendQueryString="true" redirectType="Permanent" />
</rule>

When you create an Umbraco Cloud project, the project URLs are based on the name of your project.

Let's say you have a project named Snoopy. The default hostnames will be:

• Umbraco Cloud Portal - www.s1.umbraco.io/project/snoopy

• Live site - snoopy.euwest01.umbraco.io

• Development environment - dev-snoopy.euwest01.umbraco.io

• Staging environment - stage-snoopy.euwest01.umbraco.io

The hostnames contain the region on which your project is hosted. Currently, there are four options available when choosing a region for your Umbraco project:

• West Europe (euwest01),

• East US (useast01),

• South UK (uksouth01), and

• Australian East (aueast01)

To access the backoffice, add /umbraco at the end of the Live, Development, or Staging URL.

Domains

To add and manage your hostnames on Umbraco Cloud, follow the steps below:

1. Go to your project on Umbraco Cloud.

2. Go to Configuration in the side menu.

3. Click on Hostnames in the menu.

4. Click Add new hostname to add a new hostname.

Ensure that the hostname you are binding to your Umbraco Cloud environment has a DNS entry that resolves to the Umbraco Cloud service. The DNS settings can either use a CNAME or an A & AAAA record:

• CNAME: Usually used for domains with "www" in the URL.

This is recommended to use, if possible, as the record is not changed as often as A & AAAA IPs are. When setting up a CNAME it needs to point to dns.umbraco.io.

• A & AAAA records: Are usually used for the Apex domain (without "www" in the URL).

It needs to be created at the root of your domain.

• A-records to either or both IPv4 addresses:

  • 162.159.140.127

  • 172.66.0.125

• AAAA records to either or both IPv6 addresses (to support IPv6 connectivity):

  • 2606:4700:7::7d

  • 2a06:98c1:58::7d

If you're using the Former A and AAAA records consider changing them to the new A & AAAA records above.

Check with your DNS host or hostname registrar regarding configuration details for your Hostnames.

To specify the hostname for each root node using a multisite setup, follow these steps:

1. Go to the Backoffice of the project.

2. Right-click the root content node.

3. Select Culture and Hostnames.

4. Click Add New Domain in the Culture and Hostnames window.

5. Enter your Domain name and select the Language from the drop-down list.

1. Click Save.

Once you've assigned a Hostname to your Umbraco Cloud environment, you may want to hide the default umbraco.io URL (e.g. snoopy.euwest01.umbraco.io). To do so, see the Rewrites on Cloud article.

Using special characters

Umbraco Cloud supports Internationalized Domain Names (IDN) allowing you to configure domain names including special characters.

When using an IDN direct access to the Umbraco backoffice from that domain is unavailable. If you have configured måneskin.dk as a domain, you cannot access the backoffice using måneskin.dk/umbraco. The backoffice will still be accessible using the default Cloud URL (maaneskin.euwest01.umbraco.io/umbraco), or from other domain names that do not include special characters.

Automatic Transport Layer Security (TLS)

All hostnames added to an Umbraco Cloud project's environment will get a TLS (HTTPS) certificate added, by default. The certificate is issued by Cloudflare and valid for 90 days after which it will be automatically renewed. Everything around certificates and renewals is handled for you and you only need to ensure the DNS records are configured according to our recommendations above.

Is your Domain hosted on your own Cloudflare account?

Cloudflare is a popular DNS provider, which offers a variety of different services to improve performance and security. We also use it for DNS and Hostnames on Umbraco Cloud.

When adding a hostname to your project hosted on Umbraco Cloud, using your own Cloudflare account the process is slightly different.

1. Set Proxy Status to DNS Only when creating a CNAME or A-record for your hostname in Cloudflare.

2. Change Proxy Status to Proxied once your hostname is Protected on the Hostname page for your Cloud project. Also, make sure the website is accessible through the hostname.

The above is primarily relevant when you need to use specific Cloudflare services like Page Rules, Workers, and so on.

Using Certificate Authority Authorization (CAA) for your domain?

CAA is a DNS resource record defined in RFC 6844 allowing domain owners to indicate which Certificate Authorities (CA) allow to issue certificates for them. If you use CAA records on your domain, you will either need to remove CAA entirely or add the following through your DNS provider:

example.com. IN CAA 0 issue "pki.goog"

This is necessary because Google Trust Services is the Certificate Authority for the certificates issued on Umbraco Cloud.

CAA records can be set on the subdomain, but it's not something that is commonly used. If there’s a CAA record at, e.g., app.example.com, you’ll need to remove or update it. If you want to use wildcards and allow certificates for any subdomain, the CAA record should look like this:

example.com. IN CAA 0 issuewild "pki.goog"

Upload certificates manually

On the Professional and Enterprise plans, you can manually add your certificate to your project and bind it to one of the configured hostnames.

Using your Web Application Firewall (WAF) on Umbraco Cloud

If you need to use WAF in front of your Umbraco Cloud website this section will highlight some of the common configurations needed.

In most cases, you need to ensure that the WAF and Umbraco Cloud are using the same certificate on the specific hostname. Custom certificates are a plan-specific feature on Umbraco Cloud, so make sure that you have access to upload certificates.

• Make sure the hostname is pointing to Umbraco Cloud (dns.umbraco.io).

• Certificate issued for the actual hostname. A custom certificate is required for a WAF hostname.

• Be on a plan that supports custom certificates.

When configuring the hostname and certificate on Umbraco Cloud it will be necessary to validate the hostname using a TXT record. This is needed because in most cases the WAF will hide that the website is running on Umbraco Cloud. This means that the usual domain ownership verification cannot be performed. This same approach can also be used to configure a hostname before updating the DNS for the hostname.

Adding a hostname on a Cloud project is possible before a DNS change. It can take up to approx. 14 days before it's removed. That means that you have 14 days to add a TXT record in your DNS settings.

Reach out to support and they will assist you with the details needed to be in the TXT record. We will first be able to see what you need to add to the TXT record when you have added the hostname.

When that is added it should work immediately.

Rewrites on Umbraco Cloud

Learn more about best practices for working with rewrite rules on Umbraco Cloud projects.

To manually upload your certificate on the Umbraco Cloud Portal and assign it to one of the hostnames you've added:

1. Go to your project on the Umbraco Cloud portal.

2. Click Settings -> Certificates. The Manual Certificates window opens.

Your certificates need to be:

1. In .pfx format.

2. Must use a password.

3. Cannot be expired.

4. Signature algorithm must be SHA256WithRSA, SHA1WithRSA or ECDSAWithSHA256

The .pfx file can only contain one certificate. Each certificate can then be bound to a hostname you have already added to your site. Make sure you use the hostname you will bind the certificate to as the Common Name (CN) when generating the certificate.

Add Manual certificate

1. Click Add New Certificate.

2. Select Choose file in the Certificate (.pfx file) field and upload your certificate from your local machine.

3. Enter the Password for your certificate.
4. Click Add.

Bind Certificate to a Hostname

1. Click Add new binding.

2. Choose your hostname from the Hostname dropdown.

3. Choose your newly uploaded certificate from the Certificate dropdown.

4. Click Add.

You've now successfully added your certificate to the Cloud project.

From Custom Certificate to Automatic TLS (HTTPS)

In some cases, you might want to switch from using your custom certificate to using the ones provided by the Umbraco Cloud service.

By removing your certificate from your Cloud project, the Umbraco Cloud service will automatically assign a new TLS (HTTPS) certificate to the hostname.

Read more

• Redirect from HTTP to HTTPS