Connection strings in Azure SignalR Service
A connection string contains information about how to connect to Azure SignalR Service. In this article, you learn the basics of connection strings and how to configure one in your application.
What a connection string is
When an application needs to connect to Azure SignalR Service, it needs the following information:
- The HTTP endpoint of the Azure SignalR Service instance
- The way to authenticate with the service endpoint
A connection string contains such information.
What a connection string looks like
A connection string consists of a series of key/value pairs separated by semicolons (;). The string uses an equal sign (=) to connect each key and its value. Keys aren't case sensitive.
A typical connection string might look like this example:
Endpoint=https://<resource_name>.signalr.azure.cn;AccessKey=<access_key>;Version=1.0;
The connection string contains:
Endpoint=https://<resource_name>.signalr.azure.cn
: The endpoint URL of the resource.AccessKey=<access_key>
: The key to authenticate with the service. When you specify an access key in the connection string, the Azure SignalR Service SDK uses it to generate a token that the service validates.Version
: The version of the connection string. The default value is1.0
.
The following table lists all the valid names for key/value pairs in the connection string.
Key | Description | Required | Default value | Example value |
---|---|---|---|---|
Endpoint |
The URL of your Azure SignalR Service instance. | Yes | Not applicable | https://foo.signalr.azure.cn |
Port |
The port that your Azure SignalR Service instance is listening on. | No | 80 or 443 , depending on the endpoint URI schema |
8080 |
Version |
The version of a connection string. | No | 1.0 |
1.0 |
ClientEndpoint |
The URI of your reverse proxy, such as Azure Application Gateway or Azure API Management. | No | null |
https://foo.bar |
AuthType |
The authentication type. By default, the service uses AccessKey to authorize requests. It's not case sensitive. |
No | null |
Azure , azure.msi , azure.app |
Use AccessKey
The service uses the local authentication method when AuthType
is set to null
.
Key | Description | Required | Default value | Example value |
---|---|---|---|---|
AccessKey |
The key string, in Base64 format, for building an access token. | Yes | null |
ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/ |
Use Microsoft Entra ID
The service uses the Microsoft Entra authentication method when AuthType
is set to azure
, azure.app
, or azure.msi
.
Key | Description | Required | Default value | Example value |
---|---|---|---|---|
ClientId |
A GUID of an Azure application or an Azure identity. | No | null |
00000000-0000-0000-0000-000000000000 |
TenantId |
A GUID of an organization in Microsoft Entra ID. | No | null |
00000000-0000-0000-0000-000000000000 |
ClientSecret |
The password of an Azure application instance. | No | null |
***********************.**************** |
ClientCertPath |
The absolute path of a client certificate file to an Azure application instance. | No | null |
/usr/local/cert/app.cert |
The service uses a different TokenCredential
value to generate Microsoft Entra tokens, depending on the parameters that you give:
type=azure
The service uses DefaultAzureCredential:
Endpoint=xxx;AuthType=azure
type=azure.msi
The service uses a user-assigned managed identity (ManagedIdentityCredential(clientId)) if the connection string uses
clientId
:Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>
The service uses a system-assigned managed identity (ManagedIdentityCredential()):
Endpoint=xxx;AuthType=azure.msi;
type=azure.app
Both
clientId
andtenantId
are required to use a Microsoft Entra application with a service principal.The service uses ClientSecretCredential(clientId, tenantId, clientSecret) if the connection string uses
clientSecret
:Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;clientSecret=<client_secret>>
The service uses ClientCertificateCredential(clientId, tenantId, clientCertPath) if the connection string uses
clientCertPath
:Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;TenantId=<tenant_id>;clientCertPath=</path/to/cert>
How to get connection strings
You can use the Azure portal or the Azure CLI to get connection strings.
Azure portal
Open your Azure SignalR Service resource in the Azure portal. The Keys tab shows two connection strings (primary and secondary) in the following format:
Endpoint=https://<resource_name>.signalr.azure.cn;AccessKey=<access_key>;Version=1.0;
Azure CLI
az signalr key list -g <resource_group> -n <resource_name>
Connect with a Microsoft Entra application
You can use a Microsoft Entra application to connect to your Azure SignalR Service instance. If the application has the right permission to access Azure SignalR Service, it doesn't need an access key.
To use Microsoft Entra authentication, you need to remove AccessKey
from the connection string and add AuthType=azure.app
. You also need to specify the credentials of your Microsoft Entra application, including client ID, client secret, and tenant ID. The connection string looks like this example:
Endpoint=https://<resource_name>.signalr.azure.cn;AuthType=azure.app;ClientId=<client_id>;ClientSecret=<client_secret>;TenantId=<tenant_id>;Version=1.0;
For more information about how to authenticate by using a Microsoft Entra application, see Authorize requests to SignalR resources with Microsoft Entra applications.
Authenticate with a managed identity
You can use a system-assigned or user-assigned managed identity to authenticate with Azure SignalR Service.
To use a system-assigned identity, add AuthType=azure.msi
to the connection string:
Endpoint=https://<resource_name>.signalr.azure.cn;AuthType=azure.msi;Version=1.0;
The Azure SignalR Service SDK automatically uses the identity of your app server.
To use a user-assigned identity, include the client ID of the managed identity in the connection string:
Endpoint=https://<resource_name>.signalr.azure.cn;AuthType=azure.msi;ClientId=<client_id>;Version=1.0;
For more information about how to configure managed identities, see Authorize requests to SignalR resources with Microsoft Entra managed identities.
Note
We highly recommend that you use managed identities to authenticate with Azure SignalR Service, because they're more secure than access keys. If you don't use access keys for authentication, consider completely disabling them in the Azure portal (select Keys > Access Key > Disable).
If you decide to use access keys, we recommend that you rotate them regularly. For more information, see Rotate access keys for Azure SignalR Service.
Use the connection string generator
Building connection strings manually can be cumbersome and error prone. To avoid mistakes, Azure SignalR Service provides a connection string generator to help you generate a connection string that includes Microsoft Entra identities like clientId
and tenantId
. To use the tool, open your Azure SignalR Service instance in Azure portal and select Connection strings from the left menu.
On this page, you can choose among authentication types (access key, managed identity, or Microsoft Entra application) and enter information like client endpoint, client ID, and client secret. Then the connection string is automatically generated. You can copy it and use it in your application.
Note
Information that you enter isn't saved after you leave the page. You need to copy and save your connection string to use it in your application.
For more information about how access tokens are generated and validated, see the Authenticate via Microsoft Entra token section in the Azure SignalR Service data plane REST API reference.
Provide client and server endpoints
A connection string contains the HTTP endpoint for the app server to connect to Azure SignalR Service. The server returns the HTTP endpoint to the clients in a negotiation response, so the client can connect to the service.
In some applications, there might be an extra component in front of Azure SignalR Service. All client connections need to go through that component first. For example, Azure Application Gateway is a common service that provides additional network security.
In such cases, the client needs to connect to an endpoint that's different from Azure SignalR Service. Instead of manually replacing the endpoint at the client side, you can add ClientEndpoint
to the connection string:
Endpoint=https://<resource_name>.signalr.azure.cn;AccessKey=<access_key>;ClientEndpoint=https://<url_to_app_gateway>;Version=1.0;
The app server returns a response to the client's negotiation request. The response contains the correct endpoint URL for the client to connect to. For more information about client connections, see Azure SignalR Service internals.
Similarly, if the server tries to make server connections or call REST APIs to the service, Azure SignalR Service might also be behind another service like Azure Application Gateway. In that case, you can use ServerEndpoint
to specify the actual endpoint for server connections and REST APIs:
Endpoint=https://<resource_name>.signalr.azure.cn;AccessKey=<access_key>;ServerEndpoint=https://<url_to_app_gateway>;Version=1.0;
Configure a connection string in your application
There are two ways to configure a connection string in your application.
You can set the connection string when calling the AddAzureSignalR()
API:
services.AddSignalR().AddAzureSignalR("<connection_string>");
Or you can call AddAzureSignalR()
without any arguments. The service SDK returns the connection string from a configuration named Azure:SignalR:ConnectionString
in your configuration provider.
In a local development environment, the configuration is stored in a file (appsettings.json or secrets.json) or in environment variables. You can use one of the following ways to configure connection string:
- Use a .NET secret manager (
dotnet user-secrets set Azure:SignalR:ConnectionString "<connection_string>"
). - Set an environment variable named
Azure__SignalR__ConnectionString
to the connection string. The colons need to be replaced with a double underscore in the environment variable configuration provider.
In a production environment, you can use other Azure services to manage configurations and secrets, like Azure Key Vault and App Configuration. See their documentation to learn how to set up a configuration provider for those services.
Note
Even when you're directly setting a connection string by using code, we don't recommend that you hard-code the connection string in source code. Instead, read the connection string from a secret store like Key Vault and pass it to AddAzureSignalR()
.
Configure multiple connection strings
Azure SignalR Service allows the server to connect to multiple service endpoints at the same time, so it can handle more connections that are beyond a service instance's limit. When one service instance is down, you can use the other service instances as backup. For more information about how to use multiple instances, see Scale SignalR Service with multiple instances.
There are two ways to configure multiple instances:
Through code:
services.AddSignalR().AddAzureSignalR(options => { options.Endpoints = new ServiceEndpoint[] { new ServiceEndpoint("<connection_string_1>", name: "name_a"), new ServiceEndpoint("<connection_string_2>", name: "name_b", type: EndpointType.Primary), new ServiceEndpoint("<connection_string_3>", name: "name_c", type: EndpointType.Secondary), }; });
You can assign a name and type to each service endpoint so you can distinguish them later.
Through configuration:
You can use any supported configuration provider (for example, secret manager, environment variables, or key vault) to store connection strings. Here's an example that uses a secret manager:
dotnet user-secrets set Azure:SignalR:ConnectionString:name_a <connection_string_1> dotnet user-secrets set Azure:SignalR:ConnectionString:name_b:primary <connection_string_2> dotnet user-secrets set Azure:SignalR:ConnectionString:name_c:secondary <connection_string_3>
You can assign a name and type to each endpoint by using a different configuration name in the following format:
Azure:SignalR:ConnectionString:<name>:<type>