Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
In addition to the default domain provided with Azure SignalR Service, you can also add a custom Domain Name System (DNS) domain to your service. In this article, you learn how to add a custom domain to your Azure SignalR Service resource.
- A custom domain registered through Azure App Service or a non-Microsoft registrar.
- An Azure account with an active subscription. If you don't have one, you can create one for trial.
- An Azure resource group.
- An Azure SignalR Service resource.
- An Azure Key Vault instance.
- A custom domain TLS/SSL certificate stored in your Key Vault instance. For more information, see Get started with Key Vault certificates.
- An Azure DNS zone (optional).
Before you can add a custom domain, you need to add a custom TLS/SSL certificate. Your Azure SignalR Service resource accesses the certificate stored in your key vault through a managed identity.
Note
The custom domains feature is a Premium tier feature. You can upgrade Standard tier resources to Premium tier without downtime.
You can use either a system-assigned or user-assigned managed identity. This article demonstrates how to use a system-assigned managed identity.
In the Azure portal, go to your Azure SignalR Service resource.
On the left pane, select Identity.
On the System assigned table, set Status to On.
Select Save. When you're prompted to enable system-assigned managed identity, select Yes.
After the identity is created, the object (principal) ID appears. Azure SignalR Service uses the object ID of the system-assigned managed identity to access the key vault. The name of the managed identity is the same as the name of the Azure SignalR Service instance. In the next section, you search for the principal (managed identity) by using the name or object ID.
Azure SignalR Service uses a managed identity to access your key vault. You must give the managed identity permission to access your key vault.
The steps to grant permission depend on whether you selected Vault access policy or Azure role-based access control as your key vault permission model.
If you're using Vault access policy as your key vault permission model, follow this procedure to add a new access policy.
Go to your key vault resource.
On the left pane, select Access policies.
Select Create.
On the Permissions tab:
- Under Secret permissions, select Get.
- Under Certificate permissions, select Get.
Select Next to go to the Principal tab.
Enter the object ID of the managed identity in the search box.
Select the managed identity from the search results.
Select the Review + create tab.
On the Review + create tab, select Create.
The managed identity for your Azure SignalR Service instance is listed in the access policies table.
To add the custom certificate to your Azure SignalR Service resource, follow these steps:
In the Azure portal, go to your Azure SignalR Service resource.
On the left pane, select Custom domain.
Under Custom certificate, select Add.
Enter a name of the custom certificate.
To choose a Key Vault certificate, choose Select from your Key Vault. After you make your selection, Key Vault Base URI and Key Vault Secret Name fill automatically. Alternatively, fill in the fields manually.
Optionally, you can specify a value for Key Vault Secret Version if you want to pin the certificate to a specific version.
Select Add.
Azure SignalR Service fetches the certificate and validates its content. When it succeeds, Provisioning State shows Succeeded for the certificate.
You must create a CNAME record for your custom domain in an Azure DNS zone or with your non-Microsoft registrar service. The CNAME record creates an alias from your custom domain to the default domain of Azure SignalR Service. Azure SignalR Service uses the record to validate the ownership of your custom domain.
For example, if your default domain is contoso.signalr.azure.cn, and your custom domain is contoso.example.com, you need to create a CNAME record on example.com.
After you create the CNAME record, you can perform a DNS lookup to see the CNAME information. In the example, the output from the linux dig (DNS lookup) command looks similar to this output:
contoso.example.com. 0 IN CNAME contoso.signalr.azure.cn.
If you're using an Azure DNS zone, see Manage DNS records to learn how to add a CNAME record.
If you're using other DNS providers, follow the provider's guide to create a CNAME record.
Now add the custom domain to your Azure SignalR Service resource.
In the Azure portal, go to your Azure SignalR Service resource.
On the left pane, select Custom domain.
Under Custom domain, select Add.
Enter a name for the custom domain.
Enter the full domain name of your custom domain. For example, use contoso.com.
Select a custom certificate that applies to this custom domain.
Select Add.
To verify the custom domain, you can use the health API. The health API is a public endpoint that returns the health status of your Azure SignalR Service instance. The health API is available at https://<your custom domain>/api/health.
Here's an example that uses 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
It should return the 200 status code without any certificate error.
If you configured a private endpoint to your key vault, Azure SignalR Service can't access your key vault via a public network. You can give Azure SignalR Service access to your key vault through a private network by creating a shared private endpoint.
After you create a shared private endpoint, add a custom certificate. For more information, see Add a custom certificate to Azure SignalR Service resource.
Important
You don't have to change the domain in your key vault URI. For example, if your key vault base URI is https://contoso.vault.azure.cn, you use this URI to configure a custom certificate.
You don't have to explicitly allow Azure SignalR Service IP addresses in your key vault firewall settings. For more information, see Key Vault private link diagnostics.
If you don't specify a secret version when you create a custom certificate, Azure SignalR Service periodically checks the latest version in Key Vault. When a new version is observed, it's automatically applied. The delay is usually within one hour.
Alternatively, you can pin a 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 the custom certificate proactively.
If you don't plan to use the resources you created in this article, you can delete the resource group.
Caution
Deleting the resource group deletes all resources contained within it. If resources outside the scope of this article exist in the specified resource group, they're also deleted.