Cadenas de conexión en Azure SignalR Service

Artículo
08/09/2024

Una cadena de conexión contiene información sobre cómo conectarse a Azure SignalR Service. En este artículo aprenderá los conceptos básicos de la cadena de conexión y cómo configurarla en la aplicación.

Importante

Las cadenas de conexión sin procesar solo aparecen en este artículo con fines de demostración.

Una cadena de conexión incluye la información de autorización necesaria para que la aplicación acceda al servicio Azure Web PubSub. La clave de acceso dentro de la cadena de conexión es similar a una contraseña raíz para el servicio. En entornos de producción, proteja siempre las claves de acceso. Use Azure Key Vault para administrar y rotar las claves de forma segura y proteger la cadena de conexión mediante Microsoft Entra ID y Autorizar el acceso con Microsoft Entra ID.

Evite distribuirlas a otros usuarios, codificarlas de forma rígida o guardarlas en un archivo de texto sin formato al que puedan acceder otros usuarios. Rote sus claves si cree que se han puesto en peligro.

¿Qué es una cadena de conexión?

Cuando una aplicación necesita conectarse a Azure SignalR Service, necesitará la siguiente información:

El punto de conexión HTTP de la instancia de Azure SignalR Service
La forma de autenticarse con el punto de conexión de servicio

Una cadena de conexión contiene dicha información.

El aspecto que tiene la cadena de conexión

Una cadena de conexión consta de una serie de pares clave-valor separados por punto y coma (;). La cadena usa un signo igual (=) para conectar cada clave y su valor. Las claves no distinguen entre mayúsculas y minúsculas.

Una cadena de conexión típica podría tener un aspecto similar al de este ejemplo:

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;Version=1.0;

La cadena de conexión contiene:

Endpoint=https://<resource_name>.service.signalr.net: la dirección URL del punto de conexión del recurso.
AccessKey=<access_key>: clave para autenticarse con el servicio. Al especificar una clave de acceso en la cadena de conexión, el SDK de Azure SignalR Service lo usa para generar un token que valida el servicio.
Version: versión de la cadena de conexión. El valor predeterminado es 1.0.

En la tabla siguiente se enumeran todos los nombres válidos para los pares clave-valor de la cadena de conexión.

Clave	Descripción	Obligatorio	Valor predeterminado	Valor de ejemplo
`Endpoint`	Dirección URL de la instancia de Azure SignalR Service.	Sí	No aplicable	`https://foo.service.signalr.net`
`Port`	Puerto en el que escucha la instancia de Azure SignalR Service.	No	`80` o `443`, según el esquema de URI del punto de conexión	`8080`
`Version`	Versión de una cadena de conexión.	No	`1.0`	`1.0`
`ClientEndpoint`	El URI del proxy inverso, como Azure Application Gateway o Azure API Management.	No	`null`	`https://foo.bar`
`AuthType`	El tipo de autenticación. De forma predeterminada, el servicio usa `AccessKey` para autorizar solicitudes. No distingue mayúsculas de minúsculas.	No	`null`	`Azure`, `azure.msi`, `azure.app`

Uso de AccessKey

El servicio usa el método de autenticación local cuando AuthType se establece en null.

Clave	Descripción	Obligatorio	Valor predeterminado	Valor de ejemplo
`AccessKey`	La cadena de clave en formato Base64 para crear el uso del token de acceso.	Sí	`null`	`ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/`

Uso de Microsoft Entra ID

El servicio usa el método de autenticación Microsoft Entra cuando AuthType se establece en azure, azure.app o azure.msi.

Clave	Descripción	Obligatorio	Valor predeterminado	Valor de ejemplo
`ClientId`	GUID de una aplicación de Azure o una identidad de Azure.	No	`null`	`00000000-0000-0000-0000-000000000000`
`TenantId`	GUID de una organización en Microsoft Entra ID.	No	`null`	`00000000-0000-0000-0000-000000000000`
`ClientSecret`	Contraseña de una instancia de aplicación de Azure.	No	`null`	`*********************.**************`
`ClientCertPath`	Ruta de acceso absoluta de un archivo de certificado de cliente a una instancia de aplicación de Azure.	No	`null`	`/usr/local/cert/app.cert`

El servicio usa un valor TokenCredential diferente para generar tokens de Microsoft Entra, en función de los parámetros que proporcione:

type=azure
- El servicio usa DefaultAzureCredential:
```
Endpoint=xxx;AuthType=azure
```
type=azure.msi
- El servicio usa una identidad administrada asignada por el usuario (ManagedIdentityCredential(clientId)) si la cadena de conexión usa clientId:
```
Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>
```
- El servicio usa una identidad administrada asignada por el sistema (ManagedIdentityCredential()):
```
Endpoint=xxx;AuthType=azure.msi;
```
type=azure.app

Tanto clientId como tenantId son necesarios para usar una aplicación de Microsoft Entra con una entidad de servicio.
- El servicio usa ClientSecretCredential(clientId, tenantId, clientSecret) si la cadena de conexión usa clientSecret:
```
Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;clientSecret=<client_secret>>
```
- El servicio usa ClientCertificateCredential(clientId, tenantId, clientCertPath) si la cadena de conexión usa clientCertPath:
```
Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;TenantId=<tenant_id>;clientCertPath=</path/to/cert>
```

Obtención de cadenas de conexión

Puede usar Azure Portal o la CLI de Azure para obtener cadenas de conexión.

Azure portal

Abra el recurso de Azure SignalR Service en Azure Portal. La pestaña Claves muestra dos cadenas de conexión (principal y secundaria) en el formato siguiente:

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;Version=1.0;

CLI de Azure

az signalr key list -g <resource_group> -n <resource_name>

Conexión con una aplicación de Microsoft Entra

Puede usar una aplicación de Microsoft Entra para conectarse a la instancia de Azure SignalR Service. Si la aplicación tiene el permiso adecuado para acceder a Azure SignalR Service, no necesita una clave de acceso.

Para usar la autenticación de Microsoft Entra, debe quitar AccessKey de la cadena de conexión y agregar AuthType=azure.app. También debe especificar las credenciales de la aplicación de Microsoft Entra, incluido el identificador de cliente, el secreto de cliente y el identificador de inquilino. La cadena de conexión tiene el siguiente aspecto:

Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.app;ClientId=<client_id>;ClientSecret=<client_secret>;TenantId=<tenant_id>;Version=1.0;

Para obtener más información sobre cómo autenticarse mediante una aplicación de Microsoft Entra, consulte Autorización de solicitudes a recursos de SignalR con aplicaciones de Microsoft Entra.

Autenticación con una identidad administrada

Puede usar una identidad administrada asignada por el sistema o asignada por el usuario para autenticarse con Azure SignalR Service.

Para usar una identidad asignada por el sistema, agregue AuthType=azure.msi a la cadena de conexión:

Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.msi;Version=1.0;

El SDK de Azure SignalR Service usa automáticamente la identidad del servidor de aplicaciones.

Para usar una identidad asignada por el usuario, incluya el identificador de cliente de la identidad administrada en la cadena de conexión:

Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.msi;ClientId=<client_id>;Version=1.0;

Para obtener más información sobre cómo configurar identidades administradas, consulte Autorización de solicitudes a recursos de SignalR con identidades administradas de Microsoft Entra.

Nota:

Se recomienda encarecidamente usar identidades administradas para autenticarse con Azure SignalR Service, ya que son más seguras que las claves de acceso. Si no usa claves de acceso para la autenticación, considere la posibilidad de deshabilitarlas completamente en Azure Portal (seleccione claves Claves>Clave de acceso>Deshabilitar).

Si decide usar las claves de acceso, se recomienda rotarlas con regularidad. Para más información, consulte Rotación de claves de acceso para Azure SignalR Service.

Uso del generador de cadenas de conexión

La creación manual de cadenas de conexión puede ser complicada y propensa a errores. Para evitar errores, Azure SignalR Service proporciona un generador de cadenas de conexión para ayudarle a generar una cadena de conexión que incluya identidades de Microsoft Entra, como clientId y tenantId. Para usar la herramienta, abra la instancia de Azure SignalR Service en Azure Portal y seleccione Cadenas de conexión en el menú izquierdo.

Captura de pantalla que muestra el generador de cadenas de conexión para Azure SignalR Service en Azure Portal.

En esta página, puede elegir entre los tipos de autenticación (clave de acceso, identidad administrada o aplicación de Microsoft Entra) y escribir información como el punto de conexión de cliente, el identificador de cliente y el secreto de cliente. A continuación, se genera automáticamente la cadena de conexión. Puede copiarlo y usarlo en la aplicación.

Nota:

La información que escriba no se guarda después de salir de la página. Debe copiar y guardar la cadena de conexión para usarla en la aplicación.

Para obtener más información sobre cómo se generan y validan los tokens de acceso, consulte la sección Autenticación mediante token de Microsoft Entra en la referencia de la API de REST del plano de datos de Azure SignalR Service.

Proporcionar puntos de conexión de cliente y servidor

Una cadena de conexión contiene el punto de conexión HTTP para que el servidor de aplicaciones se conecte a Azure SignalR Service. El servidor devuelve el punto de conexión HTTP a los clientes en una respuesta de negociación, por lo que el cliente puede conectarse al servicio.

En algunas aplicaciones, puede haber un componente adicional delante de Azure SignalR Service. Todas las conexiones de cliente deben pasar por ese componente en primer lugar. Por ejemplo, Azure Application Gateway es un servicio común que proporciona seguridad de red adicional.

En tales casos, el cliente debe conectarse a un punto de conexión diferente de Azure SignalR Service. En lugar de reemplazar manualmente el punto de conexión en el lado cliente, puede agregar ClientEndpoint a la cadena de conexión:

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;ClientEndpoint=https://<url_to_app_gateway>;Version=1.0;

El servidor de aplicaciones devuelve una respuesta a la solicitud de negociación del cliente. La respuesta contiene la dirección URL correcta del punto de conexión al que se va a conectar el cliente. Para más información sobre las conexiones de cliente, consulte Funcionamiento interno de Azure SignalR Service.

Del mismo modo, si el servidor intenta realizar conexiones de servidor o llamar a las API de REST al servicio, Azure SignalR Service también puede estar detrás de otro servicio como Azure Application Gateway. En ese caso puede usar ServerEndpoint para especificar el punto de conexión real para las conexiones de servidor y las API de REST:

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;ServerEndpoint=https://<url_to_app_gateway>;Version=1.0;

Configuración de la cadena de conexión en la aplicación

Las cadenas de conexión sin procesar solo aparecen en este artículo con fines de demostración. En entornos de producción, proteja siempre las claves de acceso. Use Azure Key Vault para administrar y rotar las claves de forma segura y proteger la cadena de conexión mediante Microsoft Entra ID y Autorizar el acceso con Microsoft Entra ID.

Hay dos maneras de configurar la cadena de conexión en la aplicación.

Puede establecer la cadena de conexión al llamar a la API AddAzureSignalR():

services.AddSignalR().AddAzureSignalR("<connection_string>");

O bien, puede llamar a AddAzureSignalR() sin ningún argumento. El SDK de servicio devuelve la cadena de conexión de una configuración denominada Azure:SignalR:ConnectionString en el proveedor de configuración.

En un entorno de desarrollo local, la configuración se almacena en un archivo (appsettings.json o secrets.json) o en variables de entorno. Puede usar una de las siguientes maneras de configurar la cadena de conexión:

Use un administrador de secretos de .NET (dotnet user-secrets set Azure:SignalR:ConnectionString "<connection_string>").
Establezca una variable de entorno denominada Azure__SignalR__ConnectionString en la cadena de conexión. Los dos puntos deben reemplazarse por un carácter de subrayado doble en el proveedor de configuración de variables de entorno.

En un entorno de producción, puede usar otros servicios de Azure para administrar configuraciones y secretos, como Azure Key Vault y App Configuration. Consulte su documentación para obtener información sobre cómo configurar el proveedor de configuración para esos servicios.

Nota:

Incluso cuando se establece directamente una cadena de conexión mediante código, no se recomienda codificar de forma rígida la cadena de conexión en el código fuente. En su lugar, lea la cadena de conexión de un almacén de secretos como Key Vault y pásela a AddAzureSignalR().

Configuración de varias cadenas de conexión

Azure SignalR Service permite que el servidor se conecte a varios puntos de conexión de servicio al mismo tiempo, por lo que puede controlar conexiones que están más allá del límite de una instancia de servicio. Cuando una instancia de servicio está inactiva, puede usar las demás instancias de servicio como copia de seguridad. Para más información sobre cómo usar varias instancias, consulte Escalado de SignalR Service con varias instancias.

Hay dos maneras de configurar varias instancias:

Mediante código:

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),
        };
    });

Puede asignar un nombre y un tipo a cada punto de conexión de servicio para poder distinguirlos más adelante.

Mediante la configuración:

Puede usar cualquier proveedor de configuración compatible (por ejemplo, administrador de secretos, variables de entorno o almacén de claves) para almacenar cadenas de conexión. Este es un ejemplo que usa un administrador de secretos:
```
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>
```
Puede asignar un nombre y un tipo a cada punto de conexión mediante un nombre de configuración diferente en el formato siguiente:
```
Azure:SignalR:ConnectionString:<name>:<type>
```

Compartir a través de

Cadenas de conexión en Azure SignalR Service

¿Qué es una cadena de conexión?

El aspecto que tiene la cadena de conexión

Uso de AccessKey

Uso de Microsoft Entra ID

Obtención de cadenas de conexión

Azure portal

CLI de Azure

Conexión con una aplicación de Microsoft Entra

Autenticación con una identidad administrada

Uso del generador de cadenas de conexión

Proporcionar puntos de conexión de cliente y servidor

Configuración de la cadena de conexión en la aplicación

Configuración de varias cadenas de conexión

Comentarios

Recursos adicionales