Compartilhar via

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

  • Artigo

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.

Importante

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

Uma cadeia de conexão inclui as informações de autorização necessárias para que o seu aplicativo acesse o serviço Azure Web PubSub. A chave de acesso dentro da cadeia de conexão é semelhante a uma senha raiz para o serviço. Em ambientes de produção, sempre proteja 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 o Microsoft Entra ID e autorizar o acesso com o Microsoft Entra ID.

Evite distribuir chaves de acesso para outros usuários, fazer hard-coding com elas ou salvá-las em qualquer lugar em texto sem formatação que seja acessível a outras pessoas. Gire suas chaves se você acredita que elas podem ter sido comprometidas.

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:

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.

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

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

As cadeias de conexão brutas aparecem neste artigo apenas para fins de demonstração. Em ambientes de produção, sempre proteja 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 o Microsoft Entra ID e autorizar o acesso com o Microsoft Entra ID.

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__ConnectionString para 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>