Cadeias de conexão no Serviço do Azure SignalR
Uma cadeia de conexão contém informações sobre como se conectar ao Serviço do Azure SignalR. Neste artigo, você aprenderá os conceitos básicos da cadeia de conexão e como configurar uma em seu aplicativo.
O que é uma cadeia de conexão
Quando um aplicativo precisar se conectar ao Serviço do Azure SignalR, ele precisará das seguintes informações:
- O ponto de extremidade HTTP da instância do Serviço do Azure SignalR
- A forma de autenticação no ponto de extremidade de serviço
Uma cadeia de conexão contém essas informações.
A aparência de uma cadeia de conexão
Uma cadeia de conexão consiste em uma série de pares chave/valor separados por ponto e vírgula (;). A cadeia de caracteres usa um sinal de igual (=) para conectar cada chave e o respectivo valor. As chave não diferenciam maiúsculas de minúsculas.
Uma cadeia de conexão típica pode ser parecida com este exemplo:
Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;Version=1.0;
A cadeia de conexão contém:
Endpoint=https://<resource_name>.service.signalr.net: a URL do ponto de extremidade do recurso.AccessKey=<access_key>: a chave para autenticação no serviço de pesquisa. Quando você especifica uma chave de acesso na cadeia de conexão, o SDK do Serviço do Azure SignalR a usa para gerar um token validado pelo serviço.Version: a versão da cadeia de conexão. O valor padrão é1.0.
A tabela a seguir lista todos os nomes válidos para pares chave/valor na cadeia de conexão.
| Chave | Descrição | Obrigatório | Valor padrão | Valor de exemplo |
|---|---|---|---|---|
Endpoint |
A URL da instância do Serviço do Azure SignalR. | Sim | Não Aplicável | https://foo.service.signalr.net |
Port |
A porta que a instância do Serviço do Azure SignalR escuta. | Não | 80 ou 443, dependendo do esquema de URI do ponto de extremidade |
8080 |
Version |
A versão de uma cadeia de conexão. | Não | 1.0 |
1.0 |
ClientEndpoint |
O URI do proxy reverso, como o Gateway de Aplicativo do Azure ou o Gerenciamento de API do Azure. | Não | null |
https://foo.bar |
AuthType |
O tipo de autenticação. Por padrão, o serviço usa AccessKey para autorizar as solicitações. Não diferencia maiúsculas de minúsculas. |
Não | null |
Azure, azure.msi, azure.app |
Usar o AccessKey
O serviço usa o método de autenticação local quando AuthType é definido como null.
| Chave | Descrição | Obrigatório | Valor padrão | Valor de exemplo |
|---|---|---|---|---|
AccessKey |
A cadeia de caracteres da chave, em formato Base64, para criar um token de acesso. | Sim | null |
ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/ |
Usar a ID do Microsoft Entra
O serviço usa o método de autenticação do Microsoft Entra quando AuthType é definido como azure, azure.app ou azure.msi.
| Chave | Descrição | Obrigatório | Valor padrão | Valor de exemplo |
|---|---|---|---|---|
ClientId |
Um GUID de um aplicativo do Azure ou uma identidade do Azure. | Não | null |
00000000-0000-0000-0000-000000000000 |
TenantId |
Um GUID de uma organização no Microsoft Entra ID. | Não | null |
00000000-0000-0000-0000-000000000000 |
ClientSecret |
A senha de uma instância de aplicativo do Azure. | Não | null |
***********************.**************** |
ClientCertPath |
O caminho absoluto de um arquivo de certificado do cliente para uma instância de aplicativo do Azure. | Não | null |
/usr/local/cert/app.cert |
O serviço usa um valor diferente de TokenCredential para gerar tokens do Microsoft Entra, dependendo dos parâmetros que você fornece:
type=azureO serviço usa DefaultAzureCredential:
Endpoint=xxx;AuthType=azure
type=azure.msiO serviço usará uma identidade gerenciada atribuída pelo usuário (ManagedIdentityCredential(clientId)) se a cadeia de conexão usar
clientId:Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>O serviço usa uma identidade gerenciada atribuída pelo sistema (ManagedIdentityCredential()):
Endpoint=xxx;AuthType=azure.msi;
type=azure.appclientIdetenantIdsão necessários para o uso de um aplicativo do Microsoft Entra com uma entidade de serviço.O serviço usará ClientSecretCredential(clientId, tenantId, clientSecret) se a cadeia de conexão usar
clientSecret:Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;clientSecret=<client_secret>>O serviço usará ClientCertificateCredential(clientId, tenantId, clientCertPath) se a cadeia de conexão usar
clientCertPath:Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;TenantId=<tenant_id>;clientCertPath=</path/to/cert>
Como obter cadeias de conexão
Use o portal do Azure ou a CLI do Azure para obter cadeias de conexão.
Portal do Azure
Abra o recurso do Serviço do Azure SignalR no portal do Azure. A guia Chaves mostra duas cadeias de conexão (primária e secundária) no seguinte formato:
Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;Version=1.0;
CLI do Azure
az signalr key list -g <resource_group> -n <resource_name>
Conectar-se a um aplicativo do Microsoft Entra
Você pode usar um aplicativo do Microsoft Entra para se conectar à instância do Serviço do Azure SignalR. Se o aplicativo tiver a permissão correta para acessar o Serviço do Azure SignalR, ele não precisará de uma chave de acesso.
Para usar a autenticação do Microsoft Entra, você precisa remover AccessKey da cadeia de conexão e adicionar AuthType=azure.app. Você também precisa especificar as credenciais do aplicativo do Microsoft Entra, incluindo a ID do cliente, o segredo do cliente e a ID do locatário. A cadeia de conexão é semelhante a este exemplo:
Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.app;ClientId=<client_id>;ClientSecret=<client_secret>;TenantId=<tenant_id>;Version=1.0;
Para obter mais informações sobre como se autenticar usando um aplicativo do Microsoft Entra, confira Autorizar solicitações para recursos do SignalR com aplicativos do Microsoft Entra.
Autenticar com uma identidade gerenciada
Você pode usar uma identidade gerenciada atribuída pelo sistema ou atribuída pelo usuário para se autenticar no Serviço do Azure SignalR.
Para usar uma identidade atribuída pelo sistema, adicione AuthType=azure.msi à cadeia de conexão:
Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.msi;Version=1.0;
O SDK do Serviço do Azure SignalR usa automaticamente a identidade do servidor de aplicativos.
Para usar uma identidade atribuída pelo usuário, inclua a ID do cliente da identidade gerenciada na cadeia de conexão:
Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.msi;ClientId=<client_id>;Version=1.0;
Para obter mais informações sobre como configurar identidades gerenciadas, confira Autorizar solicitações para recursos do SignalR com identidades gerenciadas do Microsoft Entra.
Observação
Recomendamos fortemente que você use identidades gerenciadas para se autenticar no Serviço do Azure SignalR, pois elas são mais seguras do que as chaves de acesso. Se você não usar chaves de acesso para autenticação, considere a possibilidade de desabilitá-las por completo no portal do Azure (selecione Chaves>Chave de Acesso>Desabilitar).
Se você decidir usar chaves de acesso, recomendamos que você as gire regularmente. Para obter mais informações, confira Girar chaves de acesso para o Serviço do Azure SignalR.
Usar o gerador da cadeia de conexão
Criar cadeias de conexão manualmente pode ser complicado e propenso a erros. Para evitar erros, o Serviço do Azure SignalR fornece um gerador de cadeia de conexão para ajudar você a gerar uma cadeia de conexão que inclui identidades do Microsoft Entra como clientId e tenantId. Para usar a ferramenta, abra a instância do Serviço do Azure SignalR no portal do Azure e selecione Cadeias de conexão no menu à esquerda.
Nessa página, você pode escolher entre os tipos de autenticação (chave de acesso, identidade gerenciada ou aplicativo do Microsoft Entra) e inserir informações como ponto de extremidade do cliente, ID do cliente e segredo do cliente. Em seguida, a cadeia de conexão é gerada automaticamente. Você pode copiá-la e usá-la no seu aplicativo.
Observação
As informações inseridas não são salvas depois que você sai da página. Você precisa copiar e salvar a cadeia de conexão para usá-la no aplicativo.
Para obter mais informações sobre como os tokens de acesso são gerados e validados, confira a seção Autenticação por meio do token do Microsoft Entra na referência da API REST do plano de dados do Serviço do Azure SignalR.
Fornecer pontos de extremidade de cliente e servidor
Uma cadeia de conexão contém o ponto de extremidade HTTP para o servidor de aplicativos se conectar ao Serviço do Azure SignalR. O servidor retorna o ponto de extremidade HTTP para os clientes em uma resposta de negociação, para que o cliente possa se conectar ao serviço.
Em alguns aplicativos, pode haver um componente extra na frente do Serviço do Azure SignalR. Todas as conexões de cliente precisam passar por esse componente primeiro. Por exemplo, o Gateway de Aplicativo do Azure é um serviço comum que fornece segurança de rede adicional.
Nesses casos, o cliente precisa se conectar a um ponto de extremidade diferente do Serviço do Azure SignalR. Em vez de substituir manualmente o ponto de extremidade no lado do cliente, você pode adicionar ClientEndpoint à cadeia de conexão:
Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;ClientEndpoint=https://<url_to_app_gateway>;Version=1.0;
O servidor de aplicativos retorna uma resposta à solicitação de negociação do cliente. A resposta contém a URL de ponto de extremidade correta para o cliente se conectar. Para obter mais informações sobre as conexões de cliente, confira Elementos internos do Serviço do Azure SignalR.
Da mesma forma, se o servidor tentar fazer conexões de servidor ou chamar APIs REST para o serviço, o Serviço do Azure SignalR também poderá estar protegido por outro serviço, como o Gateway de Aplicativo do Azure. Nesse caso, você pode usar ServerEndpoint para especificar o ponto de extremidade real para conexões de servidor e APIs REST:
Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;ServerEndpoint=https://<url_to_app_gateway>;Version=1.0;
Configurar uma cadeia de conexão no aplicativo
Há duas maneiras de configurar uma cadeia de conexão no aplicativo.
Você pode definir a cadeia de conexão ao chamar a API AddAzureSignalR():
services.AddSignalR().AddAzureSignalR("<connection_string>");
Ou, então, chamar AddAzureSignalR() sem nenhum argumento. O SDK do serviço retorna a cadeia de conexão de uma configuração chamada Azure:SignalR:ConnectionString no seu provedor de configuração.
Em um ambiente de desenvolvimento local, a configuração é armazenada em um arquivo (appsettings.json ou secrets.json) ou em variáveis de ambiente. Você pode usar uma destas duas maneiras para configurar a cadeia de conexão:
- Usar um gerenciador de segredos do .NET (
dotnet user-secrets set Azure:SignalR:ConnectionString "<connection_string>"). - Definir uma variável de ambiente chamada
Azure__SignalR__ConnectionStringpara a cadeia de conexão. Os dois-pontos precisam ser substituídos por um sublinhado duplo no provedor de configuração de variável de ambiente.
Em um ambiente de produção, você pode usar outros serviços do Azure para gerenciar configurações e segredos, como o Azure Key Vault e Configuração de Aplicativos. Confira a documentação deles para saber como configurar um provedor de configuração para esses serviços.
Observação
Mesmo quando você estiver definindo uma cadeia de conexão diretamente por meio de um código, não recomendamos embutir a cadeia de conexão no código-fonte. Em vez disso, leia a cadeia de conexão em um repositório de segredos como o Key Vault e transmita-a para AddAzureSignalR().
Configurar várias cadeias de conexão
O Serviço do Azure SignalR permite que o servidor se conecte a vários pontos de extremidade de serviço ao mesmo tempo, para que ele possa lidar com mais conexões que estão além do limite de uma instância de serviço. Quando uma instância de serviço está inativa, você pode usar as outras instâncias de serviço como backup. Para obter mais informações sobre como usar várias instâncias, confira Escalar o Serviço do SignalR com várias instâncias.
Há duas maneiras de configurar várias instâncias:
Por meio do 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), }; });Você pode atribuir um nome e um tipo a cada ponto de extremidade de serviço para que possa diferenciá-los mais tarde.
Por meio da configuração:
Você pode usar qualquer provedor de configuração com suporte (por exemplo, gerenciador de segredos, variáveis de ambiente ou cofre de chaves) para armazenar cadeias de conexão. Aqui está um exemplo que usa um gerenciador de segredos:
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>Você pode atribuir um nome e um tipo a cada ponto de extremidade usando um nome de configuração diferente no seguinte formato:
Azure:SignalR:ConnectionString:<name>:<type>