Condividi tramite

Stringhe di connessione in Servizio Azure SignalR

  • Articolo

Un stringa di connessione contiene informazioni su come connettersi a Servizio Azure SignalR. In questo articolo vengono fornite informazioni di base sulle stringa di connessione e su come configurare una nell'applicazione.

Che cos'è un stringa di connessione

Quando un'applicazione deve connettersi a Servizio Azure SignalR, sono necessarie le informazioni seguenti:

  • Endpoint HTTP dell'istanza di Servizio Azure SignalR
  • Modalità di autenticazione con l'endpoint di servizio

Un stringa di connessione contiene tali informazioni.

Aspetto di un stringa di connessione

Un stringa di connessione è costituito da una serie di coppie chiave/valore separate da punti e virgola (;). La stringa usa un segno di uguale (=) per connettere ogni chiave e il relativo valore. Le chiavi non fanno distinzione tra maiuscole e minuscole.

Un stringa di connessione tipico potrebbe essere simile all'esempio seguente:

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

Il stringa di connessione contiene:

  • Endpoint=https://<resource_name>.service.signalr.net: URL dell'endpoint della risorsa.
  • AccessKey=<access_key>: chiave da autenticare con il servizio. Quando si specifica una chiave di accesso nella stringa di connessione, l'SDK di Servizio Azure SignalR lo usa per generare un token convalidato dal servizio.
  • Version: versione del stringa di connessione. Il valore predefinito è 1.0.

Nella tabella seguente sono elencati tutti i nomi validi per le coppie chiave/valore nella stringa di connessione.

Chiave Descrizione Richiesto Default value Valore di esempio
Endpoint URL dell'istanza di Servizio Azure SignalR. Sì Non applicabile https://foo.service.signalr.net
Port Porta su cui è in ascolto l'istanza Servizio Azure SignalR. No 80 o 443, a seconda dello schema URI dell'endpoint 8080
Version Versione di un stringa di connessione. No 1.0 1.0
ClientEndpoint URI del proxy inverso, ad esempio app Azure lication Gateway o Azure Gestione API. No null https://foo.bar
AuthType Il tipo di autenticazione. Per impostazione predefinita, il servizio usa AccessKey per autorizzare le richieste. Non viene fatta distinzione tra maiuscole e minuscole. No null Azure, azure.msi, azure.app

Usare AccessKey

Il servizio usa il metodo di autenticazione locale quando AuthType è impostato su null.

Chiave Descrizione Richiesto Default value Valore di esempio
AccessKey Stringa di chiave, in formato Base64, per la compilazione di un token di accesso. Sì null ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/

Usare Microsoft Entra ID

Il servizio usa il metodo di autenticazione Microsoft Entra quando AuthType è impostato su azure, azure.appo azure.msi.

Chiave Descrizione Richiesto Default value Valore di esempio
ClientId GUID di un'applicazione Azure o di un'identità di Azure. No null 00000000-0000-0000-0000-000000000000
TenantId GUID di un'organizzazione in Microsoft Entra ID. No null 00000000-0000-0000-0000-000000000000
ClientSecret Password di un'istanza dell'applicazione Azure. No null ***********************.****************
ClientCertPath Percorso assoluto di un file di certificato client in un'istanza dell'applicazione Azure. No null /usr/local/cert/app.cert

Il servizio usa un valore diverso TokenCredential per generare token Microsoft Entra, a seconda dei parametri specificati:

Come ottenere stringa di connessione

È possibile usare il portale di Azure o l'interfaccia della riga di comando di Azure per ottenere stringa di connessione.

Azure portal

Aprire la risorsa Servizio Azure SignalR nel portale di Azure. La scheda Chiavi mostra due stringa di connessione (primario e secondario) nel formato seguente:

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

Interfaccia della riga di comando di Azure

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

Connettersi con un'applicazione Microsoft Entra

È possibile usare un'applicazione Microsoft Entra per connettersi all'istanza di Servizio Azure SignalR. Se l'applicazione dispone del diritto di accesso Servizio Azure SignalR, non è necessaria una chiave di accesso.

Per usare l'autenticazione di Microsoft Entra, è necessario rimuovere AccessKey dal stringa di connessione e aggiungere AuthType=azure.app. È anche necessario specificare le credenziali dell'applicazione Microsoft Entra, inclusi l'ID client, il segreto client e l'ID tenant. L'stringa di connessione è simile all'esempio seguente:

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

Per altre informazioni su come eseguire l'autenticazione tramite un'applicazione Microsoft Entra, vedere Autorizzare le richieste alle risorse SignalR con le applicazioni Microsoft Entra.

Eseguire l'autenticazione con un'identità gestita

È possibile usare un'identità gestita assegnata dal sistema o assegnata dall'utente per l'autenticazione con Servizio Azure SignalR.

Per usare un'identità assegnata dal sistema, aggiungere AuthType=azure.msi alla stringa di connessione:

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

L'SDK di Servizio Azure SignalR usa automaticamente l'identità del server app.

Per usare un'identità assegnata dall'utente, includere l'ID client dell'identità gestita nel stringa di connessione:

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

Per altre informazioni su come configurare le identità gestite, vedere Autorizzare le richieste alle risorse SignalR con identità gestite di Microsoft Entra.

Nota

È consigliabile usare le identità gestite per l'autenticazione con Servizio Azure SignalR, perché sono più sicure rispetto alle chiavi di accesso. Se non si usano le chiavi di accesso per l'autenticazione, è consigliabile disabilitarle completamente nella portale di Azure (selezionare Chiavi>di scelta chiave>di scelta Disabilita).

Se si decide di usare le chiavi di accesso, è consigliabile ruotarle regolarmente. Per altre informazioni, vedere Ruotare le chiavi di accesso per Servizio Azure SignalR.

Usare il generatore di stringa di connessione

La compilazione di stringa di connessione manualmente può essere complessa e soggetta a errori. Per evitare errori, Servizio Azure SignalR fornisce un generatore di stringa di connessione per generare un stringa di connessione che include identità di Microsoft Entra come clientId e tenantId. Per usare lo strumento, aprire l'istanza di Servizio Azure SignalR in portale di Azure e selezionare Stringhe di connessione dal menu a sinistra.

Screenshot che mostra il generatore di stringa di connessione per Servizio Azure SignalR nel portale di Azure.

In questa pagina è possibile scegliere tra tipi di autenticazione (chiave di accesso, identità gestita o applicazione Microsoft Entra) e immettere informazioni come endpoint client, ID client e segreto client. Viene quindi generato automaticamente il stringa di connessione. È possibile copiarlo e usarlo nell'applicazione.

Nota

Le informazioni immesse non vengono salvate dopo aver lasciato la pagina. È necessario copiare e salvare il stringa di connessione per usarlo nell'applicazione.

Per altre informazioni su come vengono generati e convalidati i token di accesso, vedere la sezione Eseguire l'autenticazione tramite token Microsoft Entra nella guida di riferimento all'API REST del piano dati di Servizio Azure SignalR.

Fornire endpoint client e server

Un stringa di connessione contiene l'endpoint HTTP per il server app a cui connettersi Servizio Azure SignalR. Il server restituisce l'endpoint HTTP ai client in una risposta di negoziazione, in modo che il client possa connettersi al servizio.

In alcune applicazioni potrebbe esserci un componente aggiuntivo davanti a Servizio Azure SignalR. Tutte le connessioni client devono prima passare attraverso tale componente. Ad esempio, app Azure lication Gateway è un servizio comune che fornisce sicurezza di rete aggiuntiva.

In questi casi, il client deve connettersi a un endpoint diverso da Servizio Azure SignalR. Anziché sostituire manualmente l'endpoint sul lato client, è possibile aggiungere ClientEndpoint al stringa di connessione:

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

Il server app restituisce una risposta alla richiesta di negoziazione del client. La risposta contiene l'URL dell'endpoint corretto a cui il client deve connettersi. Per altre informazioni sulle connessioni client, vedere Servizio Azure SignalR internals.

Analogamente, se il server tenta di stabilire connessioni al server o chiamare LE API REST al servizio, Servizio Azure SignalR potrebbe anche essere dietro un altro servizio come app Azure lication Gateway. In tal caso, è possibile usare ServerEndpoint per specificare l'endpoint effettivo per le connessioni server e le API REST:

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

Configurare un stringa di connessione nell'applicazione

Esistono due modi per configurare un stringa di connessione nell'applicazione.

È possibile impostare il stringa di connessione quando si chiama l'APIAddAzureSignalR():

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

In alternativa, è possibile chiamare AddAzureSignalR() senza argomenti. L'SDK del servizio restituisce il stringa di connessione da una configurazione denominata Azure:SignalR:ConnectionString nel provider di configurazione.

In un ambiente di sviluppo locale, la configurazione viene archiviata in un file (appsettings.json o secrets.json) o in variabili di ambiente. È possibile usare uno dei modi seguenti per configurare stringa di connessione:

  • Usare un gestore di segreti .NET (dotnet user-secrets set Azure:SignalR:ConnectionString "<connection_string>").
  • Impostare una variabile di ambiente denominata Azure__SignalR__ConnectionString sul stringa di connessione. I due punti devono essere sostituiti con un doppio carattere di sottolineatura nel provider di configurazione delle variabili di ambiente.

In un ambiente di produzione è possibile usare altri servizi di Azure per gestire configurazioni e segreti, ad esempio Azure Key Vault e Configurazione app. Vedere la documentazione per informazioni su come configurare un provider di configurazione per tali servizi.

Nota

Anche quando si imposta direttamente un stringa di connessione usando codice, non è consigliabile impostare come hardcoded il stringa di connessione nel codice sorgente. Leggere invece il stringa di connessione da un archivio segreto come Key Vault e passarlo a AddAzureSignalR().

Configurare più stringa di connessione

Servizio Azure SignalR consente al server di connettersi contemporaneamente a più endpoint di servizio, in modo da poter gestire più connessioni che superano il limite di un'istanza del servizio. Quando un'istanza del servizio è inattiva, è possibile usare le altre istanze del servizio come backup. Per altre informazioni su come usare più istanze, vedere Ridimensionare Servizio SignalR con più istanze.

Esistono due modi per configurare più istanze:

  • Tramite il codice:

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

    È possibile assegnare un nome e un tipo a ogni endpoint di servizio in modo da poterli distinguere in un secondo momento.

  • Tramite la configurazione:

    È possibile usare qualsiasi provider di configurazione supportato( ad esempio, secret manager, variabili di ambiente o insieme di credenziali delle chiavi) per archiviare stringa di connessione. Ecco un esempio che usa un gestore dei segreti:

    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>

    È possibile assegnare un nome e un tipo a ogni endpoint usando un nome di configurazione diverso nel formato seguente:

    Azure:SignalR:ConnectionString:<name>:<type>