Parametry połączenia w usłudze Azure SignalR Service

Artykuł
12/12/2024

Parametry połączenia zawiera informacje o sposobie nawiązywania połączenia z usługą Azure SignalR Service. W tym artykule poznasz podstawy parametry połączenia i sposób konfigurowania go w aplikacji.

Ważne

Nieprzetworzone parametry połączenia są wyświetlane tylko w tym artykule w celach demonstracyjnych.

Parametry połączenia zawiera informacje o autoryzacji wymagane przez aplikację w celu uzyskania dostępu do usługi Azure Web PubSub. Klucz dostępu wewnątrz parametry połączenia jest podobny do hasła głównego usługi. W środowiskach produkcyjnych zawsze chroń klucze dostępu. Usługa Azure Key Vault umożliwia bezpieczne zarządzanie kluczami i obracanie ich oraz zabezpieczanie parametry połączenia przy użyciu identyfikatora Entra firmy Microsoft.

Unikaj dystrybuowania kluczy dostępu do innych użytkowników, kodowania ich lub zapisywania ich w dowolnym miejscu w postaci zwykłego tekstu, który jest dostępny dla innych użytkowników. Obracanie kluczy, jeśli uważasz, że mogły one zostać naruszone.

Czym jest parametry połączenia

Gdy aplikacja musi nawiązać połączenie z usługą Azure SignalR Service, potrzebuje następujących informacji:

Punkt końcowy HTTP wystąpienia usługi Azure SignalR Service
Sposób uwierzytelniania za pomocą punktu końcowego usługi

Parametry połączenia zawiera takie informacje.

Jak wygląda parametry połączenia

Parametry połączenia składa się z serii par klucz/wartość oddzielonych średnikami (;). Ciąg używa znaku równości (=), aby połączyć każdy klucz i jego wartość. Klucze nie są uwzględniane wielkości liter.

Typowy parametry połączenia może wyglądać następująco:

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

Parametry połączenia zawiera:

Endpoint=https://<resource_name>.service.signalr.net: adres URL punktu końcowego zasobu.
AccessKey=<access_key>: klucz do uwierzytelniania w usłudze. Po określeniu klucza dostępu w parametry połączenia zestaw SDK usługi Azure SignalR Service używa go do wygenerowania tokenu weryfikowanego przez usługę.
Version: wersja parametry połączenia. Domyślna wartość to 1.0.

W poniższej tabeli wymieniono wszystkie prawidłowe nazwy par klucz/wartość w parametry połączenia.

Key	opis	Wymagania	Domyślna wartość	Przykładowa wartość
`Endpoint`	Adres URL wystąpienia usługi Azure SignalR Service.	Tak	Nie dotyczy	`https://foo.service.signalr.net`
`Port`	Port, na który nasłuchuje wystąpienie usługi Azure SignalR Service.	Nie.	`80` lub `443`, w zależności od schematu identyfikatora URI punktu końcowego	`8080`
`Version`	Wersja parametry połączenia.	Nie.	`1.0`	`1.0`
`ClientEndpoint`	Identyfikator URI zwrotnego serwera proxy, taki jak aplikacja systemu Azure Gateway lub Azure API Management.	Nie.	`null`	`https://foo.bar`
`AuthType`	Typ uwierzytelniania. Domyślnie usługa używa `AccessKey` polecenia do autoryzowania żądań. Nie uwzględnia wielkości liter.	Nie.	`null`	`Azure`, , `azure.msiazure.app`

Korzystanie z AccessKey

Usługa używa lokalnej metody uwierzytelniania, gdy AuthType jest ustawiona na null.

Key	opis	Wymagania	Domyślna wartość	Przykładowa wartość
`AccessKey`	Ciąg klucza w formacie Base64 do tworzenia tokenu dostępu.	Tak	`null`	`ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/`

Korzystanie z identyfikatora Entra firmy Microsoft

Usługa używa metody uwierzytelniania Entra firmy Microsoft, gdy AuthType jest ustawiona na azure, azure.applub azure.msi.

Key	opis	Wymagania	Domyślna wartość	Przykładowa wartość
`ClientId`	Identyfikator GUID aplikacji platformy Azure lub tożsamości platformy Azure.	Nie.	`null`	`00000000-0000-0000-0000-000000000000`
`TenantId`	Identyfikator GUID organizacji w usłudze Microsoft Entra ID.	Nie.	`null`	`00000000-0000-0000-0000-000000000000`
`ClientSecret`	Hasło wystąpienia aplikacji platformy Azure.	Nie.	`null`	`*********************.**************`
`ClientCertPath`	Ścieżka bezwzględna pliku certyfikatu klienta do wystąpienia aplikacji platformy Azure.	Nie.	`null`	`/usr/local/cert/app.cert`

Usługa używa innej TokenCredential wartości do generowania tokenów firmy Microsoft Entra w zależności od parametrów, które podajesz:

type=azure
- Usługa używa wartości DefaultAzureCredential:
```
Endpoint=xxx;AuthType=azure
```
type=azure.msi
- Usługa używa tożsamości zarządzanej przypisanej przez użytkownika (ManagedIdentityCredential(clientId)), jeśli parametry połączenia używa elementu clientId:
```
Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>
```
- Usługa używa przypisanej przez system tożsamości zarządzanej (ManagedIdentityCredential()):
```
Endpoint=xxx;AuthType=azure.msi;
```
type=azure.app

Zarówno clientId , jak i tenantId są wymagane do korzystania z aplikacji Microsoft Entra z jednostką usługi.
- Usługa używa parametru ClientSecretCredential(clientId, tenantId, clientSecret), jeśli parametry połączenia używa polecenia clientSecret:
```
Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;clientSecret=<client_secret>>
```
- Usługa używa elementu ClientCertificateCredential(clientId, tenantId, clientCertPath), jeśli parametry połączenia używa polecenia clientCertPath:
```
Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;TenantId=<tenant_id>;clientCertPath=</path/to/cert>
```

Jak uzyskać parametry połączenia

Aby uzyskać parametry połączenia, możesz użyć witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure.

Azure Portal

Otwórz zasób usługi Azure SignalR Service w witrynie Azure Portal. Karta Klucze zawiera dwa parametry połączenia (podstawowy i pomocniczy) w następującym formacie:

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

Interfejs wiersza polecenia platformy Azure

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

Nawiązywanie połączenia z aplikacją Firmy Microsoft Entra

Aby nawiązać połączenie z wystąpieniem usługi Azure SignalR Service, możesz użyć aplikacji Firmy Microsoft Entra. Jeśli aplikacja ma odpowiednie uprawnienia dostępu do usługi Azure SignalR Service, nie potrzebuje klucza dostępu.

Aby użyć uwierzytelniania firmy Microsoft Entra, musisz usunąć AccessKey element z parametry połączenia i dodać element AuthType=azure.app. Należy również określić poświadczenia aplikacji Microsoft Entra, w tym identyfikator klienta, wpis tajny klienta i identyfikator dzierżawy. Parametry połączenia wygląda następująco:

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

Aby uzyskać więcej informacji na temat uwierzytelniania przy użyciu aplikacji Firmy Microsoft Entra, zobacz Autoryzowanie żądań do zasobów usługi SignalR za pomocą aplikacji Firmy Microsoft Entra.

Uwierzytelnianie przy użyciu tożsamości zarządzanej

Do uwierzytelniania w usłudze Azure SignalR Service można użyć przypisanej przez system lub przypisanej przez użytkownika tożsamości zarządzanej.

Aby użyć tożsamości przypisanej przez system, dodaj AuthType=azure.msi do parametry połączenia:

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

Zestaw SDK usługi Azure SignalR Service automatycznie używa tożsamości serwera aplikacji.

Aby użyć tożsamości przypisanej przez użytkownika, dołącz identyfikator klienta tożsamości zarządzanej w parametry połączenia:

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

Aby uzyskać więcej informacji na temat konfigurowania tożsamości zarządzanych, zobacz Autoryzowanie żądań do zasobów usługi SignalR przy użyciu tożsamości zarządzanych przez firmę Microsoft Entra.

Uwaga

Zdecydowanie zalecamy używanie tożsamości zarządzanych do uwierzytelniania za pomocą usługi Azure SignalR Service, ponieważ są one bezpieczniejsze niż klucze dostępu. Jeśli nie używasz kluczy dostępu do uwierzytelniania, rozważ całkowite wyłączenie ich w witrynie Azure Portal (wybierz opcję Wyłącz klucz>dostępu kluczy).>

Jeśli zdecydujesz się używać kluczy dostępu, zalecamy regularne obracanie ich. Aby uzyskać więcej informacji, zobacz Rotacja kluczy dostępu dla usługi Azure SignalR Service.

Korzystanie z generatora parametry połączenia

Ręczne tworzenie parametry połączenia może być uciążliwe i podatne na błędy. Aby uniknąć błędów, usługa Azure SignalR Service udostępnia generator parametry połączenia, który pomaga wygenerować parametry połączenia, który obejmuje tożsamości firmy Microsoft, takie jak clientId i tenantId. Aby użyć narzędzia, otwórz wystąpienie usługi Azure SignalR Service w witrynie Azure Portal i wybierz pozycję Parametry połączenia z menu po lewej stronie.

Zrzut ekranu przedstawiający generator parametry połączenia dla usługi Azure SignalR Service w witrynie Azure Portal.

Na tej stronie można wybrać typy uwierzytelniania (klucz dostępu, tożsamość zarządzana lub aplikacja Microsoft Entra) i wprowadzić informacje, takie jak punkt końcowy klienta, identyfikator klienta i klucz tajny klienta. Następnie parametry połączenia jest generowany automatycznie. Możesz go skopiować i użyć w aplikacji.

Uwaga

Wprowadzone informacje nie są zapisywane po opuszczeniu strony. Musisz skopiować i zapisać parametry połączenia, aby używać go w aplikacji.

Aby uzyskać więcej informacji na temat sposobu generowania i weryfikowania tokenów dostępu, zobacz sekcję Uwierzytelnianie za pośrednictwem tokenu entra firmy Microsoft w dokumentacji interfejsu API REST płaszczyzny danych usługi Azure SignalR Service.

Zapewnianie punktów końcowych klienta i serwera

Parametry połączenia zawiera punkt końcowy HTTP serwera aplikacji w celu nawiązania połączenia z usługą Azure SignalR Service. Serwer zwraca punkt końcowy HTTP do klientów w odpowiedzi na negocjacje, aby klient mógł nawiązać połączenie z usługą.

W niektórych aplikacjach może istnieć dodatkowy składnik przed usługą Azure SignalR Service. Wszystkie połączenia klienckie muszą najpierw przejść przez ten składnik. Na przykład usługa aplikacja systemu Azure Gateway jest wspólną usługą, która zapewnia dodatkowe zabezpieczenia sieci.

W takich przypadkach klient musi nawiązać połączenie z punktem końcowym, który różni się od usługi Azure SignalR Service. Zamiast ręcznie zastępować punkt końcowy po stronie klienta, możesz dodać ClientEndpoint go do parametry połączenia:

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

Serwer aplikacji zwraca odpowiedź na żądanie negocjacji klienta. Odpowiedź zawiera prawidłowy adres URL punktu końcowego, z którym klient ma nawiązać połączenie. Aby uzyskać więcej informacji na temat połączeń klienckich, zobacz Azure SignalR Service internals (Wewnętrzne elementy usługi Azure SignalR Service).

Podobnie, jeśli serwer próbuje nawiązać połączenia z serwerem lub wywołać interfejsy API REST do usługi, usługa Azure SignalR Service może również znajdować się za inną usługą, na przykład aplikacja systemu Azure Gateway. W takim przypadku można ServerEndpoint określić rzeczywisty punkt końcowy dla połączeń serwera i interfejsów API REST:

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

Konfigurowanie parametry połączenia w aplikacji

Nieprzetworzone parametry połączenia są wyświetlane tylko w tym artykule w celach demonstracyjnych. W środowiskach produkcyjnych zawsze chroń klucze dostępu. Usługa Azure Key Vault umożliwia bezpieczne zarządzanie kluczami i obracanie ich oraz zabezpieczanie parametry połączenia przy użyciu identyfikatora Entra firmy Microsoft.

Istnieją dwa sposoby konfigurowania parametry połączenia w aplikacji.

Podczas wywoływania interfejsu AddAzureSignalR() API można ustawić parametry połączenia:

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

Możesz też wywołać AddAzureSignalR() metodę bez żadnych argumentów. Zestaw SDK usługi zwraca parametry połączenia z konfiguracji o nazwie Azure:SignalR:ConnectionString w dostawcy konfiguracji.

W lokalnym środowisku projektowym konfiguracja jest przechowywana w pliku (appsettings.json lub secrets.json) lub w zmiennych środowiskowych. Aby skonfigurować parametry połączenia, możesz użyć jednego z następujących sposobów:

Użyj menedżera wpisów tajnych platformy .NET (dotnet user-secrets set Azure:SignalR:ConnectionString "<connection_string>").
Ustaw zmienną środowiskową o nazwie Azure__SignalR__ConnectionString na parametry połączenia. Dwukropki muszą zostać zastąpione podwójnym podkreśleniem u dostawcy konfiguracji zmiennej środowiskowej.

W środowisku produkcyjnym możesz użyć innych usług platformy Azure do zarządzania konfiguracjami i wpisami tajnymi, takimi jak Azure Key Vault i App Configuration. Zapoznaj się z ich dokumentacją, aby dowiedzieć się, jak skonfigurować dostawcę konfiguracji dla tych usług.

Uwaga

Nawet jeśli bezpośrednio ustawiasz parametry połączenia przy użyciu kodu, nie zalecamy kodowania parametry połączenia w kodzie źródłowym. Zamiast tego odczytaj parametry połączenia z magazynu wpisów tajnych, takiego jak Key Vault, i przekaż go do AddAzureSignalR().

Konfigurowanie wielu parametry połączenia

Usługa Azure SignalR Service umożliwia serwerowi łączenie się z wieloma punktami końcowymi usługi w tym samym czasie, dzięki czemu może obsługiwać więcej połączeń, które wykraczają poza limit wystąpienia usługi. Gdy jedno wystąpienie usługi nie działa, możesz użyć innych wystąpień usługi jako kopii zapasowej. Aby uzyskać więcej informacji na temat używania wielu wystąpień, zobacz Skalowanie usługi SignalR Service z wieloma wystąpieniami.

Istnieją dwa sposoby konfigurowania wielu wystąpień:

Za pomocą kodu:

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

Możesz przypisać nazwę i typ do każdego punktu końcowego usługi, aby później je odróżnić.

Za pośrednictwem konfiguracji:

Do przechowywania parametry połączenia można użyć dowolnego obsługiwanego dostawcy konfiguracji (na przykład menedżera wpisów tajnych, zmiennych środowiskowych lub magazynu kluczy). Oto przykład, który używa menedżera wpisów tajnych:
```
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>
```
Nazwę i typ można przypisać do każdego punktu końcowego, używając innej nazwy konfiguracji w następującym formacie:
```
Azure:SignalR:ConnectionString:<name>:<type>
```

Udostępnij za pośrednictwem

Parametry połączenia w usłudze Azure SignalR Service

Czym jest parametry połączenia

Jak wygląda parametry połączenia

Korzystanie z AccessKey

Korzystanie z identyfikatora Entra firmy Microsoft

Jak uzyskać parametry połączenia

Azure Portal

Interfejs wiersza polecenia platformy Azure

Nawiązywanie połączenia z aplikacją Firmy Microsoft Entra

Uwierzytelnianie przy użyciu tożsamości zarządzanej

Korzystanie z generatora parametry połączenia

Zapewnianie punktów końcowych klienta i serwera

Konfigurowanie parametry połączenia w aplikacji

Konfigurowanie wielu parametry połączenia

Opinia

Dodatkowe zasoby