Chaînes de connexion dans Azure SignalR Service

Une chaîne de connexion contient des informations sur le mode de connexion à Azure SignalR Service. Dans cet article, vous allez découvrir les principes fondamentaux de la chaîne de connexion et comment en configurer une dans votre application.

Définition d’une chaîne de connexion

Si une application doit se connecter à Azure SignalR Service, elle aura besoin des informations suivantes :

• Le point de terminaison HTTP de l’instance Azure SignalR Service
• Le mode d’authentification auprès du point de terminaison de service

Une chaîne de connexion contient ces informations.

À quoi ressemble une chaîne de connexion

Une chaîne de connexion se compose d’une série de paires clé-valeur séparées par un point-virgule (;). La chaîne utilise un signe égal (=) pour connecter chaque clé avec sa valeur. Les clés ne respectent pas la casse.

Une chaîne de connexion classique peut ressembler à l’exemple suivant :

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

La chaîne de connexion comporte :

• Endpoint=https://<resource_name>.service.signalr.net, qui est l’URL de point de terminaison de la ressource.
• AccessKey=<access_key>, qui est la clé permettant de s’authentifier auprès du service. Lorsque vous spécifiez une clé d’accès dans la chaîne de connexion, le kit de développement logiciel (SDK) Azure SignalR Service l’utilise pour générer un jeton que le service valide.
• Version, qui est la version de la chaîne de connexion. La valeur par défaut est 1.0.

Le tableau suivant répertorie tous les noms valides pour les paires clé/valeur dans la chaîne de connexion.

Utiliser AccessKey

Le service utilise la méthode d’authentification locale lorsqu’AuthType est défini sur null.

Utiliser Microsoft Entra ID

Le service utilise la méthode d’authentification Microsoft Entra lorsqu’AuthType est défini sur azure, azure.app ou azure.msi.

Le service utilise une valeur TokenCredential différente pour générer les jetons Microsoft Entra, en fonction des paramètres que vous définissez :

• type=azure

  • Le service utilise DefaultAzureCredential :

    Endpoint=xxx;AuthType=azure
    

• type=azure.msi

  • Le service utilise une identité managée affectée par l’utilisateur [ManagedIdentityCredential(clientId)] si la chaîne de connexion utilise clientId :

    Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>
    

  • Le service utilise une identité managée affectée par le système [ManagedIdentityCredential()] :

    Endpoint=xxx;AuthType=azure.msi;
    

• type=azure.app

  clientId et tenantId sont nécessaires pour utiliser une application Microsoft Entra avec un principal de service.

  • Le service utilise ClientSecretCredential(clientId, tenantId, clientSecret) si la chaîne de connexion utilise clientSecret :

    Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;clientSecret=<client_secret>>
    

  • Le service utilise ClientCertificateCredential(clientId, tenantId, clientCertPath) si la chaîne de connexion utilise clientCertPath :

    Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;TenantId=<tenant_id>;clientCertPath=</path/to/cert>
    

Obtenir les chaînes de connexion

Vous pouvez utiliser le portail Azure ou Azure CLI pour obtenir les chaînes de connexion.

Portail Azure

Dans le portail Azure, accédez à votre ressource Azure SignalR Service. Dans l’onglet Clés, deux chaînes de connexion (primaire et secondaire) s’affichent au format suivant :

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

Azure CLI

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

Se connecter avec une application Microsoft Entra

Vous pouvez utiliser une application Microsoft Entra pour vous connecter à l’instance Azure SignalR Service. Si l’application dispose de l’autorisation appropriée pour accéder à Azure SignalR Service, aucune clé d’accès n’est nécessaire.

Pour utiliser l’authentification Microsoft Entra, vous devez supprimer AccessKey de la chaîne de connexion, puis ajouter AuthType=azure.app. Vous devez également spécifier les informations d’identification de votre application Microsoft Entra, y compris l’ID client, la clé secrète client et l’ID locataire. La chaîne de connexion ressemble à cet exemple :

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

Pour plus d’informations sur l’authentification avec une application Microsoft Entra, consultez Autoriser les requêtes adressées aux ressources SignalR avec les applications Microsoft Entra.

Authentifier avec une identité managée

Vous pouvez utiliser une identité managée affectée par le système ou par l’utilisateur pour vous authentifier auprès d’Azure SignalR Service.

Pour utiliser une identité affectée par le système, ajoutez AuthType=azure.msi à la chaîne de connexion :

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

Le SDK d’Azure SignalR Service utilise automatiquement l’identité du serveur d’applications.

Pour utiliser une identité affectée par l’utilisateur, ajoutez l’ID client de l’identité managée à la chaîne de connexion :

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

Pour plus d’informations sur la configuration des identités managées, consultez Autoriser les requêtes adressées aux ressources SignalR avec les identités managées Microsoft Entra.

Utiliser le générateur de chaînes de connexion

La création manuelle de chaînes de connexion peut être fastidieuse et sujette aux erreurs. Pour éviter de telles erreurs, Azure SignalR Service fournit un générateur de chaînes de connexion qui vous aide à générer une chaîne de connexion et inclut les identités Microsoft Entra, comme clientId et tenantId. Pour utiliser l’outil, ouvrez votre instance Azure SignalR Service dans le portail Azure et sélectionnez Chaînes de connexion dans le menu de gauche.

Dans cette page, vous pouvez choisir l’un des types d’authentification (clé d’accès, identité managée ou application Microsoft Entra) et saisir diverses informations, comme le point de terminaison client, l’ID client et la clé secrète client. Ensuite, la chaîne de connexion est automatiquement générée. Vous pouvez la copier et l’utiliser dans votre application.

Pour plus d’informations sur la génération et la validation des jetons d’accès, consultez la section S’authentifier par jeton Microsoft Entra dans la référence de l’API REST du plan de données Azure SignalR Service.

Points de terminaison client et serveur

Une chaîne de connexion contient le point de terminaison HTTP permettant au serveur d’applications de se connecter à Azure SignalR Service. Le serveur retourne le point de terminaison HTTP aux clients dans une réponse de négociation, pour que le client puisse se connecter au service.

Dans certaines applications, un composant supplémentaire peut exister en amont d’Azure SignalR Service. Toutes les connexions client doivent d’abord passer par ce composant. Par exemple, Azure Application Gateway est un service commun qui offre une sécurité réseau supplémentaire.

Dans ce cas, le client doit se connecter à un point de terminaison différent de celui d’Azure SignalR Service. Au lieu de remplacer manuellement le point de terminaison côté client, vous pouvez ajouter ClientEndpoint à la chaîne de connexion :

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

Le serveur d’applications retourne une réponse à la requête de négociation du client. La réponse contient l’URL de point de terminaison permettant au client de se connecter. Pour plus d’informations sur les connexions client, consultez Éléments internes d’Azure SignalR Service.

De même, lorsque le serveur souhaite établir des connexions serveur ou appeler des API REST pour le service, Azure SignalR Service peut aussi se trouver en aval d’un autre service, comme Azure Application Gateway. Dans ce cas, vous pouvez utiliser ServerEndpoint pour spécifier le point de terminaison des connexions au serveur et des API REST :

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

Configurer une chaîne de connexion dans l’application

Des chaînes de connexion brutes sont utilisées dans cet article à des fins de démonstration uniquement. Dans les environnements de production, protégez toujours vos clés d’accès. Utilisez Azure Key Vault pour gérer et permuter vos clés de façon sécurisée, sécuriser votre chaîne de connexion en utilisant Microsoft Entra ID, et autoriser l’accès avec Microsoft Entra ID.

Pour configurer une chaîne de connexion dans l’application, deux options s’offrent à vous.

Vous pouvez définir la chaîne de connexion lors de l’appel de l’API AddAzureSignalR() :

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

Vous pouvez également appeler AddAzureSignalR() sans argument. Le SDK du service retourne la chaîne de connexion à partir d’une configuration nommée Azure:SignalR:ConnectionString dans le fournisseur de configuration.

Dans un environnement de développement local, la configuration est stockée dans un fichier (appsettings.json ou secrets.json) ou dans des variables d’environnement. Pour configurer la chaîne de connexion, utilisez l’une des deux méthodes suivantes :

• Utiliser le gestionnaire de secrets .NET (dotnet user-secrets set Azure:SignalR:ConnectionString "<connection_string>").
• Définir une variable d’environnement nommée Azure__SignalR__ConnectionString dans la chaîne de connexion. Les deux-points doivent être remplacés par un double trait de soulignement dans le fournisseur de configuration des variables d’environnement.

Dans un environnement de production, vous pouvez utiliser d’autres services Azure pour gérer les configurations et les secrets, comme Azure Key Vault ou App Configuration. Pour savoir comment configurer un fournisseur de configuration pour ces services, consultez la documentation dédiée.

Configurer plusieurs chaînes de connexion

Azure SignalR Service permet également au serveur de se connecter simultanément à plusieurs points de terminaison de service. De cette façon, il peut gérer les connexions qui dépassent la limite d’une instance de service. Si une instance de service est arrêtée, vous pouvez utiliser d’autres instances de service, comme celles de sauvegarde. Pour plus d’informations sur l’utilisation de plusieurs instances, consultez Mettre à l’échelle SignalR Service avec plusieurs instances.

Pour configurer plusieurs instances, deux options s’offrent à vous :

• Par programmation :

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

  Vous pouvez affecter un nom et un type à chaque point de terminaison de service afin de pouvoir les distinguer ultérieurement.

• Par configuration :

  Vous pouvez utiliser n’importe quelle configuration prise en charge (gestionnaire de clés secrètes, variables d’environnement, coffre de clés, etc.) pour stocker les chaînes de connexion. Voici un exemple qui utilise un gestionnaire de clés secrètes :

  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>
  

  Vous pouvez également affecter un nom et un type à chaque point de terminaison en utilisant un nom de configuration différent au format suivant :

  Azure:SignalR:ConnectionString:<name>:<type>