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

Artigo
12/12/2024

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 Web PubSub. 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. Rode as 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 de extremidade HTTP da instância do Serviço Azure SignalR
A maneira de autenticar com o ponto de extremidade 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: A URL do ponto de extremidade 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 cadeia 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	Description	Obrigatório	Default value	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 sua instância do Serviço SignalR do Azure está escutando.	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 seu 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 solicitações. Não diferencia maiúsculas de 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	Description	Obrigatório	Default value	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	Description	Obrigatório	Default value	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 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á:

type=azure
- O serviço usa DefaultAzureCredential:
```
Endpoint=xxx;AuthType=azure
```
type=azure.msi
- O serviço usa 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 ao sistema (ManagedIdentityCredential()):
```
Endpoint=xxx;AuthType=azure.msi;
```
type=azure.app

Ambos clientId e tenantId são necessários para usar um aplicativo Microsoft Entra com uma entidade de serviço.
- O serviço usa 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 usa 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

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.

Autenticar com uma identidade gerida

Você pode usar uma identidade gerenciada atribuída pelo sistema ou pelo usuário para autenticar com o 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 Girar 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 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 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 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 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 do ponto de extremidade correta para o cliente se conectar. Para obter mais informações sobre conexões de cliente, consulte Internos do Serviço 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 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>
```

Partilhar via

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

O que é uma cadeia de conexão

Qual é a aparência de uma cadeia de conexão

Usar AccessKey

Usar o Microsoft Entra ID

Como obter cadeias de conexão

Portal do Azure

CLI do Azure

Conecte-se com um aplicativo Microsoft Entra

Autenticar com uma identidade gerida

Usar o gerador de cadeia de conexão

Fornecer pontos de extremidade de cliente e servidor

Configurar uma cadeia de conexão em seu aplicativo

Configurar várias cadeias de conexão

Comentários

Recursos adicionais