Edit

Configure a custom domain for Azure Web PubSub Service

  • Article

In addition to the default domain provided by the Azure Web PubSub Service, you can also add a custom domain. A custom domain is a domain name that you own and manage. You can use a custom domain to access your Azure Web PubSub Service resource. For example, you can use contoso.example.com instead of contoso.webpubsub.azure.com to access your Azure Web PubSub Service resource.

Prerequisites

  • An Azure account with an active subscription. If you don't have an Azure account, you can create an account for free.
  • An Azure Web PubSub service (must be Premium tier).
  • An Azure Key Vault resource.
  • A custom certificate matching custom domain that is stored in Azure Key Vault.

Add a custom certificate

Before you can add a custom domain, you need to add a matching custom certificate first. A custom certificate is a 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. You can select System assigned or User assigned identity. If you want to use User assigned identity, you need to create one first.

    1. To add a System assigned identity

      1. Select On.
      2. Select Yes to confirm.
      3. Select Save.

      Screenshot of enabling system assigned managed identity.

    2. To add a User assigned identity;

      1. Select Add user assigned managed identity.
      2. Select an existing identity.
      3. Select Add.

      Screenshot of enabling user assigned managed identity.

  4. Select Save.

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.

  3. Select Vault access policy.

  4. Select Go to access policies.

  5. Select Create.

  6. Select Secret Get permission.

  7. Select Certificate Get permission.

  8. Select Next.

    Screenshot of permissions selection in Key Vault.

  9. Search for the Azure Web PubSub Service resource name.

  10. Select Next.

    Screenshot of principal selection in Key Vault.

  11. Select Next on the Application tab.

  12. Select 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. In the Custom certificate section, select Add.

    Screenshot of custom certificate management.

  4. Fill in a name for the custom certificate.

  5. Select Select from your Key Vault to choose a Key Vault certificate. After selection the following Key Vault Base URI, the Key Vault Secret Name will be automatically filled in. 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. Select Add.

    Screenshot of adding a custom certificate.

Azure Web PubSub Service fetches the certificate and validates its contents. When it succeeds, the certificate's 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 to learn 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, select Add.

    Screenshot of custom domain management.

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

  5. Enter 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. Select 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:\>

The health API should return 200 status code without any certificate error.

Key Vault in private network

If you've configured a Private Endpoint to your Key Vault, Azure Web PubSub Service can't 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.

Certificate rotation

If you don't specify a secret version when creating custom certificate, Azure Web PubSub Service periodically checks latest version in Key Vault. When a new version is observed, it's automatically applied. The delay is usually within 1 hour.

Alternatively, you can also pin custom certificate to a specific secret version in Key Vault. When you need to apply a new certificate, you can edit the secret version and then update custom certificate proactively.

Next steps