Edit

Configure a custom domain for Azure Web PubSub Service

  • Article
  • 4 minutes to read

In addition to the default domain provided Azure Web PubSub Service, you can also add custom domains.

Prerequisites

  • Resource must be Premium tier
  • A custom certificate matching custom domain is stored in Azure Key Vault

Add a custom certificate

Before you can add a custom domain, you need add a matching custom certificate first. A custom certificate is a sub resource of your Azure Web PubSub Service. It references a certificate in your Azure Key Vault. For security and compliance reasons, Azure Web PubSub Service doesn't permanently store your certificate. Instead it fetches it from your Key Vault on the fly and keeps it in memory.

Step 1: Grant your Azure Web PubSub Service resource access to Key Vault

Azure Web PubSub Service uses Managed Identity to access your Key Vault. In order to authorize, it needs to be granted permissions.

  1. In the Azure portal, go to your Azure Web PubSub Service resource.

  2. In the menu pane, select Identity.

  3. Turn on either System assigned or User assigned identity. Click Save.

    Screenshot of enabling managed identity.

Depending on how you configure your Key Vault permission model, you may need to grant permissions at different places.

If you're using Key Vault built-in access policy as Key Vault permission model:

Screenshot of built-in access policy selected as Key Vault permission model.

  1. Go to your Key Vault resource.

  2. In the menu pane, select Access configuration. Click Go to access policies.

  3. Click Create. Select Secret Get permission and Certificate Get permission. Click Next.

    Screenshot of permissions selection in Key Vault.

  4. Search for the Azure Web PubSub Service resource name or the user assigned identity name. Click Next.

    Screenshot of principal selection in Key Vault.

  5. Skip Application (optional). Click Next.

  6. In Review + create, click Create.

Step 2: Create a custom certificate

  1. In the Azure portal, go to your Azure Web PubSub Service resource.

  2. In the menu pane, select Custom domain.

  3. Under Custom certificate, click Add.

    Screenshot of custom certificate management.

  4. Fill in a name for the custom certificate.

  5. Click Select from your Key Vault to choose a Key Vault certificate. After selection the following Key Vault Base URI, Key Vault Secret Name should be automatically filled. Alternatively you can also fill in these fields manually.

  6. Optionally, you can specify a Key Vault Secret Version if you want to pin the certificate to a specific version.

  7. Click Add.

    Screenshot of adding a custom certificate.

Azure Web PubSub Service will then fetch the certificate and validate its content. If everything is good, the Provisioning State will be Succeeded.

Screenshot of an added custom certificate.

Create a custom domain CNAME

To validate the ownership of your custom domain, you need to create a CNAME record for the custom domain and point it to the default domain of Azure Web PubSub Service.

For example, if your default domain is contoso.webpubsub.azure.com, and your custom domain is contoso.example.com, you need to create a CNAME record on example.com like:

contoso.example.com. 0 IN CNAME contoso.webpubsub.azure.com.

If you're using Azure DNS Zone, see manage DNS records for how to add a CNAME record.

Screenshot of adding a CNAME record in Azure DNS Zone.

If you're using other DNS providers, follow provider's guide to create a CNAME record.

Add a custom domain

A custom domain is another sub resource of your Azure Web PubSub Service. It contains all configurations for a custom domain.

  1. In the Azure portal, go to your Azure Web PubSub Service resource.

  2. In the menu pane, select Custom domain.

  3. Under Custom domain, click Add.

    Screenshot of custom domain management.

  4. Fill in a name for the custom domain. It's the sub resource name.

  5. Fill in the domain name. It's the full domain name of your custom domain, for example, contoso.com.

  6. Select a custom certificate that applies to this custom domain.

  7. Click Add.

    Screenshot of adding a custom domain.

Verify a custom domain

You can now access your Azure Web PubSub Service endpoint via the custom domain. To verify it, you can access the health API.

Here's an example using cURL:

PS C:\> curl.exe -v https://contoso.example.com/api/health
...
> GET /api/health HTTP/1.1
> Host: contoso.example.com

< HTTP/1.1 200 OK
...
PS C:\>

It should return 200 status code without any certificate error.

Key Vault in private network

If you have configured Private Endpoint to your Key Vault, Azure Web PubSub Service cannot access the Key Vault via public network. You need to set up a Shared Private Endpoint to let Azure Web PubSub Service access your Key Vault via private network.

After you create a Shared Private Endpoint, you can create a custom certificate as usual. You don't have to change the domain in Key Vault URI. For example, if your Key Vault base URI is https://contoso.vault.azure.net, you still use this URI to configure custom certificate.

You don't have to explicitly allow Azure Web PubSub Service IPs in Key Vault firewall settings. For more info, see Key Vault private link diagnostics.

Next steps