Partilhar via

Cadeias de conexão no Serviço SignalR do Azure

Uma cadeia de conexão contém informações sobre como se conectar ao Serviço Azure SignalR. Neste artigo, você aprenderá as noções básicas de cadeias de conexão e como configurar uma em seu aplicativo.

Importante

As cadeias de conexão brutas aparecem neste artigo apenas para fins de demonstração.

Uma cadeia de conexão inclui as informações de autorização necessárias para seu aplicativo acessar o Serviço Azure SignalR. A chave de acesso dentro da cadeia de conexão é semelhante a uma senha de root para o seu serviço. Em ambientes de produção, proteja sempre as suas chaves de acesso. Use o Azure Key Vault para gerenciar e girar suas chaves com segurança e proteger sua cadeia de conexão usando a ID do Microsoft Entra e autorizar o acesso com a ID do Microsoft Entra.

Evite distribuir chaves de acesso para outros usuários, codificá-las ou salvá-las em qualquer lugar em texto simples acessível a outras pessoas. Rodeie as suas chaves se acreditar que podem ter sido comprometidas.

O que é uma cadeia de conexão

Quando um aplicativo precisa se conectar ao Serviço SignalR do Azure, ele precisa das seguintes informações:

  • O ponto final HTTP da instância do serviço SignalR do Azure
  • A forma de autenticação com o endpoint do serviço

Uma cadeia de conexão contém essas informações.

Qual é 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 seu valor. As chaves não diferenciam maiúsculas de minúsculas.

Uma cadeia de conexão típica pode se parecer 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: O URL do endereço final do recurso.
  • AccessKey=<access_key>: A chave para autenticar com o serviço. Quando você especifica uma chave de acesso na cadeia de conexão, o SDK do Serviço SignalR do Azure a usa para gerar um token que o serviço valida.
  • Version: A versão da string de conexão. O valor predefinido é 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 sua instância do Serviço Azure SignalR. Sim Não aplicável https://foo.service.signalr.net
Port A porta na qual a sua instância do Serviço SignalR do Azure está a escutar. 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 A URI do seu proxy reverso, como o Gateway de Aplicações do Azure ou a Gestão 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 solicitações. Não é sensível a maiúsculas e minúsculas. Não null Azure, azure.msi, azure.app

Usar AccessKey

O serviço usa o método de autenticação local quando AuthType é definido como null.

Chave Descrição Obrigatório Valor por defeito Valor de exemplo
AccessKey A cadeia de caracteres de chave, no formato Base64, para criar um token de acesso. Sim null ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/

Usar o Microsoft Entra ID

O serviço usa o método de autenticação Microsoft Entra quando AuthType definido como azure, azure.appou 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 Identificador Global Único (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 de cliente para uma instância de aplicativo do Azure. Não null /usr/local/cert/app.cert

O serviço usa um valor diferente TokenCredential para gerar tokens do Microsoft Entra, dependendo dos parâmetros que você dá:

Como obter cadeias de conexão

Você pode usar o portal do Azure ou a CLI do Azure para obter cadeias de conexão.

Portal do Azure

Abra seu recurso do Serviço Azure SignalR no portal do Azure. A guia Teclas 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>

Conecte-se com um aplicativo Microsoft Entra

Você pode usar um aplicativo Microsoft Entra para se conectar à sua instância do Serviço Azure SignalR. Se o aplicativo tiver a permissão certa para acessar o Serviço 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 seu aplicativo Microsoft Entra, incluindo ID do cliente, segredo do cliente e ID do locatário. A cadeia de conexão se parece com 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 autenticar usando um aplicativo Microsoft Entra, consulte Autorizar solicitações para recursos do SignalR com aplicativos Microsoft Entra.

Faça a autenticação com uma identidade gerida

Você pode usar uma identidade gerida atribuída pelo sistema ou pelo utilizador para autenticar no Serviço 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 Azure SignalR usa automaticamente a identidade do seu 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, consulte Autorizar solicitações para recursos do SignalR com identidades gerenciadas do Microsoft Entra.

Nota

É altamente recomendável que você use identidades gerenciadas para autenticar com o Serviço Azure SignalR, porque elas são mais seguras do que as chaves de acesso. Se você não usar chaves de acesso para autenticação, considere desativá-las completamente no portal do Azure (selecione Chaves de>acesso>Desabilitar).

Se decidir utilizar chaves de acesso, recomendamos que as rode regularmente. Para obter mais informações, consulte Alterar chaves de acesso para o Serviço Azure SignalR.

Usar o gerador de cadeia de conexão

A criação manual de cadeias de conexão pode ser complicada e propensa a erros. Para evitar erros, o Serviço Azure SignalR fornece um gerador de cadeia de conexão para ajudá-lo a gerar uma cadeia de conexão que inclui identidades do Microsoft Entra como clientId e tenantId. Para usar a ferramenta, abra sua instância do Serviço Azure SignalR no portal do Azure e selecione Cadeias de conexão no menu à esquerda.

Captura de tela que mostra o gerador de cadeia de conexão para o Serviço SignalR do Azure no portal do Azure.

Nesta página, você pode escolher entre os tipos de autenticação (chave de acesso, identidade gerenciada ou aplicativo 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á-lo e usá-lo em seu aplicativo.

Nota

As informações inseridas não são salvas depois que você sai da página. Você precisa copiar e salvar sua cadeia de conexão para usá-la em seu aplicativo.

Para obter mais informações sobre como os tokens de acesso são gerados e validados, consulte a seção Autenticar via token do Microsoft Entra na referência da API REST do plano de dados do Serviço Azure SignalR.

Fornecer endereços de cliente e servidor

Uma cadeia de conexão contém o ponto de extremidade HTTP para o servidor de aplicações se conectar ao Serviço Azure SignalR. O servidor devolve o endpoint HTTP aos clientes numa resposta de negociação, para que possam conectar-se ao serviço.

Em alguns aplicativos, pode haver um componente extra na frente do Serviço 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 conectar-se a um ponto final diferente do serviço 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 o URL correto do ponto de extremidade para o cliente se conectar. Para obter mais informações sobre conexões de cliente, consulte os detalhes do Serviço Azure SignalR.

Da mesma forma, se o servidor tentar fazer ligações de servidor ou chamar APIs REST para o serviço, o Serviço Azure SignalR também pode estar atrás de outro serviço, como o Azure Application Gateway. 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 em seu aplicativo

As cadeias de conexão brutas aparecem neste artigo apenas para fins de demonstração. Em ambientes de produção, proteja sempre as suas chaves de acesso. Use o Azure Key Vault para gerenciar e girar suas chaves com segurança e proteger sua cadeia de conexão usando a ID do Microsoft Entra e autorizar o acesso com a ID do Microsoft Entra.

Há duas maneiras de configurar uma cadeia de conexão em seu aplicativo.

Você pode definir a cadeia de conexão ao chamar a AddAzureSignalR() API:

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

Ou você pode ligar AddAzureSignalR() sem quaisquer argumentos. O SDK de serviço retorna a cadeia de conexão de uma configuração nomeada Azure:SignalR:ConnectionString em 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 das seguintes maneiras de configurar a cadeia de conexão:

  • Use um gerenciador de segredos .NET (dotnet user-secrets set Azure:SignalR:ConnectionString "<connection_string>").
  • Defina uma variável de ambiente chamada Azure__SignalR__ConnectionString para a cadeia de conexão. Os dois pontos precisam ser substituídos por um sublinhado duplo no provedor de configuração da 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 Cofre da Chave do Azure e a Configuração do Aplicativo. Consulte a documentação para saber como configurar um provedor de configuração para esses serviços.

Nota

Mesmo quando você está definindo diretamente uma cadeia de conexão usando código, não recomendamos que você codifice a cadeia de conexão no código-fonte. Em vez disso, leia a cadeia de conexão de um armazenamento secreto como o Key Vault e passe-a para AddAzureSignalR().

Configurar várias cadeias de conexão

O Serviço Azure SignalR permite que o servidor se conecte a vários pontos de extremidade de serviço ao mesmo tempo, para que 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, consulte Dimensionar o serviço SignalR com várias instâncias.

Há duas maneiras de configurar várias instâncias:

  • Através 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 poder distingui-los mais tarde.

  • Através da configuração:

    Você pode usar qualquer provedor de configuração suportado (por exemplo, gerenciador secreto, variáveis de ambiente ou cofre de chaves) para armazenar cadeias de conexão. Aqui está um exemplo que usa um gerenciador secreto:

    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>