Freigeben über

Verbindungszeichenfolgen in Azure SignalR Service

  • Artikel

Eine Verbindungszeichenfolge enthält Informationen über die Art der Verbindung zu Azure SignalR Service. In diesem Artikel erfahren Sie mehr über die Grundlagen von Verbindungszeichenfolgen und deren Konfiguration in Ihrer Anwendung.

Was ist eine Verbindungszeichenfolge?

Wenn eine Anwendung eine Verbindung mit Azure SignalR Service herstellen muss, benötigt sie die folgenden Informationen:

  • Den HTTP-Endpunkt der Azure SignalR Service-Instanz
  • Die Art der Authentifizierung beim Dienstendpunkt

Die Verbindungszeichenfolge enthält derartige Informationen.

Format einer Verbindungszeichenfolge

Eine Verbindungszeichenfolge besteht aus einer Reihe von Schlüssel-Wert-Paaren, die durch Semikolons (;) getrennt sind. Die Zeichenfolge verwendet ein Gleichheitszeichen (=), um jeden Schlüssel mit dessen Wert zu verbinden. Bei Schlüsseln wird nicht zwischen Groß- und Kleinschreibung unterschieden.

Eine typische Verbindungszeichenfolge kann beispielsweise wie folgt aussehen:

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

Die Verbindungszeichenfolge enthält:

  • Endpoint=https://<resource_name>.service.signalr.net: Die Endpunkt-URL der Ressource
  • AccessKey=<access_key>: Den Schlüssel zur Authentifizierung beim Dienst. Wenn Sie einen Zugriffsschlüssel in der Verbindungszeichenfolge angeben, verwendet das Azure SignalR Service-SDK ihn, um ein Token zu generieren, das der Dienst überprüft.
  • Version: Die Version der Verbindungszeichenfolge. Der Standardwert ist 1.0.

In der folgenden Tabelle sind alle gültigen Namen für Schlüssel-Wert-Paare in der Verbindungszeichenfolge aufgeführt:

Schlüssel BESCHREIBUNG Erforderlich Standardwert Beispielswert
Endpoint Die URL Ihrer Azure SignalR Service-Instanz Ja Nicht zutreffend https://foo.service.signalr.net
Port Der Port, dem Ihre Azure SignalR Service-Instanz lauscht No 80 oder 443, je nach Endpunkt-URI-Schema 8080
Version Die Version einer Verbindungszeichenfolge No 1.0 1.0
ClientEndpoint Der URI Ihres Reverseproxys, z. B. Azure Application Gateway oder Azure API Management No null https://foo.bar
AuthType Der Authentifizierungstyp. Standardmäßig verwendet der Dienst AccessKey zum Autorisieren von Anforderungen. Die Groß-/Kleinschreibung wird hier nicht beachtet. No null Azure, azure.msi, azure.app

Verwenden von AccessKey

Der Dienst verwendet die lokale Authentifizierungsmethode, wenn AuthType auf null festgelegt ist.

Schlüssel BESCHREIBUNG Erforderlich Standardwert Beispielswert
AccessKey Die Schlüsselzeichenfolge im Base64-Format zum Erstellen eines Zugriffstokens Ja null ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/

Verwenden Sie Microsoft Entra ID

Der Dienst verwendet die Microsoft Entra-Authentifizierungsmethode, wenn AuthType auf azure, azure.appoder azure.msi festgelegt ist.

Schlüssel BESCHREIBUNG Erforderlich Standardwert Beispielswert
ClientId Eine GUID einer Azure-Anwendung oder einer Azure-Identität No null 00000000-0000-0000-0000-000000000000
TenantId Eine GUID einer Organisation in Microsoft Entra ID No null 00000000-0000-0000-0000-000000000000
ClientSecret Das Kennwort einer Azure-Anwendungsinstanz No null ***********************.****************
ClientCertPath Der absolute Pfad einer Clientzertifikatdatei zu einer Azure-Anwendungsinstanz No null /usr/local/cert/app.cert

Der Dienst verwendet einen anderen TokenCredential-Wert, um Microsoft Entra-Token zu generieren, abhängig von den angegebenen Parametern:

Abrufen von Verbindungszeichenfolgen

Sie können das Azure-Portal oder die Azure CLI verwenden, um Verbindungszeichenfolgen abzurufen.

Azure-Portal

Öffnen Sie Ihre Azure SignalR Service-Ressource im Azure-Portal. Auf der Registerkarte Schlüssel werden zwei Verbindungszeichenfolgen (primär und sekundär) im folgenden Format angezeigt:

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

Azure CLI

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

Herstellen einer Verbindung mit einer Microsoft Entra-Anwendung

Sie können eine Microsoft Entra-Anwendung verwenden, um eine Verbindung mit Ihrer Azure SignalR Service-Instanz herzustellen. Wenn die Anwendung über die richtige Berechtigung zum Zugriff auf Azure SignalR Service verfügt, ist kein Zugriffsschlüssel erforderlich.

Um die Microsoft Entra-Authentifizierung zu verwenden, müssen Sie AccessKey aus der Verbindungszeichenfolge entfernen und AuthType=azure.app hinzufügen. Zudem müssen Sie die Anmeldeinformationen Ihrer Microsoft Entra-Anwendung angeben, einschließlich der Client-ID, des geheimen Clientschlüssels und der Mandanten-ID. Die Verbindungszeichenfolge sieht wie im folgenden Beispiel aus:

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

Weitere Informationen zum Authentifizieren mithilfe einer Microsoft Entra-Anwendung finden Sie unter Autorisieren von Anforderungen an SignalR-Ressourcen mit Microsoft Entra-Anwendungen.

Authentifizieren mit einer verwalteten Identität

Für die Authentifizierung bei Azure SignalR Service kann eine systemseitig oder benutzerseitig zugewiesene verwaltete Identität verwendet werden.

Um eine systemseitig zugewiesene Identität zu verwenden, fügen Sie der Verbindungszeichenfolge AuthType=azure.msi hinzu:

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

Das Azure SignalR Service-SDK verwendet automatisch die Identität Ihres App-Servers.

Um eine benutzerseitig zugewiesene Identität zu verwenden, schließen Sie die Client-ID der verwalteten Identität in die Verbindungszeichenfolge ein:

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

Weitere Informationen zum Konfigurieren verwalteter Identitäten finden Sie unter Autorisieren von Anforderungen an SignalR-Ressourcen mit von Microsoft Entra verwalteten Identitäten.

Hinweis

Es wird dringend empfohlen, verwaltete Identitäten zur Authentifizierung bei Azure SignalR Service zu verwenden, da sie sicherer als Zugriffsschlüssel sind. Wenn Sie keine Zugriffsschlüssel für die Authentifizierung verwenden, sollten Sie sie im Azure-Portal vollständig deaktivieren (wählen Sie Schlüssel>Zugriffsschlüssel>Deaktivieren aus).

Wenn Sie sich für die Verwendung von Zugriffsschlüsseln entscheiden, empfehlen wir, diese regelmäßig zu rotieren. Weitere Informationen finden Sie unter Rotieren von Zugriffsschlüsseln für Azure SignalR Service.

Verwenden des Verbindungszeichenfolgen-Generators

Das manuelle Erstellen von Verbindungszeichenfolgen kann mühsam und fehleranfällig sein. Um Fehler zu vermeiden, stellt Azure SignalR Service einen Verbindungszeichenfolgen-Generator bereit, mit dem Sie eine Verbindungszeichenfolge generieren können, die Microsoft Entra-Identitäten wie clientId und tenantId enthält. Um das Tool zu verwenden, öffnen Sie Ihre Azure SignalR Service-Instanz im Azure-Portal, und wählen Sie im linken Menü Verbindungszeichenfolgen aus.

Screenshot des Verbindungszeichenfolgen-Generators für Azure SignalR Service im Azure-Portal

Auf dieser Seite können Sie zwischen Authentifizierungstypen (Zugriffsschlüssel, verwaltete Identität oder Microsoft Entra-Anwendung) auswählen und Informationen wie Clientendpunkt, Client-ID und geheimen Clientschlüssel eingeben. Anschließend wird die Verbindungszeichenfolge automatisch generiert. Sie können sie kopieren und in Ihrer Anwendung verwenden.

Hinweis

Informationen, die Sie eingeben, werden nach dem Verlassen der Seite nicht gespeichert. Sie müssen Ihre Verbindungszeichenfolge kopieren und speichern, um sie in Ihrer Anwendung zu verwenden.

Weitere Informationen dazu, wie Zugriffstoken generiert und überprüft werden, finden Sie im Abschnitt Authentifizieren über das Microsoft Entra-Token in der REST-API-Referenz zu Azure SignalR Service.

Bereitstellen von Client- und Serverendpunkten

Die Verbindungszeichenfolge enthält den HTTP-Endpunkt für den App-Server, um eine Verbindung mit Azure SignalR Service herzustellen. Der Server gibt den HTTP-Endpunkt an die Clients in einer Aushandlungsantwort zurück, damit der Client eine Verbindung mit dem Dienst herstellen kann.

In einigen Anwendungen gibt es möglicherweise eine zusätzliche Komponente vor Azure SignalR Service. Alle Clientverbindungen müssen zuerst diese Komponente durchlaufen. Beispielsweise ist Azure Application Gateway ein häufig genutzter Dienst, der zusätzliche Netzwerksicherheit bietet.

In solchen Fällen muss der Client eine Verbindung mit einem Endpunkt herstellen, der sich von Azure SignalR Service unterscheidet. Anstatt den Endpunkt manuell auf der Clientseite zu ersetzen, können Sie der Verbindungszeichenfolge ClientEndpoint hinzufügen:

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

Der App-Server gibt eine Antwort auf die Aushandlungsanforderung des Clients zurück. Die Antwort enthält die richtige Endpunkt-URL für den Client, mit dem eine Verbindung hergestellt werden soll. Weitere Informationen zu Clientverbindungen finden Sie unter Ausführliche Informationen zu Azure SignalR Service.

Wenn der Server versucht, Serververbindungen durchzuführen oder REST-APIs im Dienst aufzurufen, liegt Azure SignalR Service möglicherweise auch hinter einem anderen Dienst wie Azure Application Gateway. In diesem Fall können Sie ServerEndpoint verwenden, um den tatsächlichen Endpunkt für Serververbindungen und REST-APIs anzugeben:

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

Konfigurieren einer Verbindungszeichenfolge in Ihrer Anwendung

Es gibt zwei Möglichkeiten, eine Verbindungszeichenfolge in Ihrer Anwendung zu konfigurieren.

Sie können die Verbindungszeichenfolge beim Aufrufen der AddAzureSignalR()-API festlegen:

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

Alternativ können Sie AddAzureSignalR() ohne Argumente aufrufen. Das Dienst-SDK gibt die Verbindungszeichenfolge aus einer Konfiguration mit dem Namen Azure:SignalR:ConnectionString in Ihrem Konfigurationsanbieter zurück.

In einer lokalen Entwicklungsumgebung wird die Konfiguration in einer Datei (appsettings.json oder secrets.json) oder in Umgebungsvariablen gespeichert. Sie können eine der folgenden Möglichkeiten zum Konfigurieren der Verbindungszeichenfolge verwenden:

  • Verwenden eines .NET-Geheimnis-Managers (dotnet user-secrets set Azure:SignalR:ConnectionString "<connection_string>")
  • Legen Sie eine Umgebungsvariable namens Azure__SignalR__ConnectionString auf die Verbindungszeichenfolge fest. Die Doppelpunkte müssen durch einen doppelten Unterstrich im Umgebungsvariablen-Konfigurationsanbieter ersetzt werden.

In einer Produktionsumgebung können Sie andere Azure-Dienste wie Azure Key Vault und App Configuration verwenden, um Konfigurationen und Geheimnisse zu verwalten. Informationen zum Einrichten des Konfigurationsanbieters für diese Dienste finden Sie in der jeweiligen Dokumentation.

Hinweis

Auch wenn Sie eine Verbindungszeichenfolge direkt mithilfe von Code festlegen, wird davon abgeraten, die Verbindungszeichenfolge im Quellcode hartzucodieren. Lesen Sie stattdessen die Verbindungszeichenfolge aus einem Geheimnisspeicher wie Key Vault, und übergeben Sie sie an AddAzureSignalR().

Konfigurieren mehrerer Verbindungszeichenfolgen

Mit Azure SignalR Service kann der Server auch gleichzeitig eine Verbindung mit mehreren Dienstendpunkten herstellen, sodass er mehr Verbindungen verarbeiten kann als für eine Dienstinstanz maximal möglich sind. Wenn eine Dienstinstanz ausfällt, können Sie die anderen Dienstinstanzen als Sicherung verwenden. Weitere Informationen zur Verwendung mehrerer Instanzen finden Sie unter Skalieren von SignalR Service mit mehreren Instanzen.

Es gibt zwei Möglichkeiten, mehrere Instanzen zu konfigurieren:

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

    Sie können jedem Dienstendpunkt einen Namen und Typ zuweisen, um sie später unterscheiden zu können.

  • Durch Konfiguration:

    Sie können jeden unterstützten Konfigurationsanbieter (z. B. Geheimnis-Manager, Umgebungsvariablen oder Schlüsseltresor) verwenden, um Verbindungszeichenfolgen zu speichern. Hier ist ein Beispiel, das einen Geheimnis-Manager verwendet:

    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>

    Sie können jedem Endpunkt auch Namen und Typ zuweisen, indem Sie einen anderen Konfigurationsnamen im folgenden Format verwenden:

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