Partager via

Chaînes de connexion dans Azure SignalR Service

  • Article

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.

Clé Description Obligatoire Valeur par défaut Exemple de valeur
Endpoint URL de votre instance Azure SignalR Service. Oui Non applicable https://foo.service.signalr.net
Port Port sur lequel votre instance Azure SignalR Service écoute. Non 80 ou 443, en fonction du schéma de l’URI de point de terminaison 8080
Version Version de la chaîne de connexion. Non 1.0 1.0
ClientEndpoint URI de votre proxy inverse, comme Azure Application Gateway ou Azure API Management. Non null https://foo.bar
AuthType Type d’authentification. Par défaut, le service utilise AccessKey pour autoriser les requêtes. Il ne respecte pas la casse. Non null Azure, azure.msi, azure.app

Utiliser AccessKey

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

Clé Description Obligatoire Valeur par défaut Exemple de valeur
AccessKey Chaîne de clé au format Base64 pour générer un jeton d’accès. Oui null ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/

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.

Clé Description Obligatoire Valeur par défaut Exemple de valeur
ClientId GUID d’une application Azure ou d’une identité Azure. Non null 00000000-0000-0000-0000-000000000000
TenantId GUID d’une organisation dans Microsoft Entra ID. Non null 00000000-0000-0000-0000-000000000000
ClientSecret Mot de passe d’une instance d’application Azure. Non null ***********************.****************
ClientCertPath Chemin absolu d’un fichier de certificat client vers une instance d’application Azure. Non null /usr/local/cert/app.cert

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 :

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.

Remarque

Nous vous recommandons vivement d’utiliser les identités managées pour vous authentifier auprès d’Azure SignalR Service, car elles sont plus sécurisées que les clés d’accès. Si vous n’utilisez pas de clés d’accès pour l’authentification, pensez à les désactiver complètement dans le portail Azure (sélectionnez Clés > Clé d’accès > Désactiver).

Si vous décidez d’utiliser des clés d’accès, nous vous recommandons de les régénérer régulièrement. Pour plus d’informations, consultez Régénérer les clés d’accès pour Azure SignalR Service.

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.

Capture d’écran représentant le générateur de chaînes de connexion pour Azure SignalR Service dans le portail Azure.

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.

Remarque

Les informations que vous saisissez ne sont pas enregistrées lorsque vous quittez la page. Vous devez copier et enregistrer votre chaîne de connexion pour 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

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.

Remarque

Même lorsque vous définissez directement une chaîne de connexion par programmation, nous vous déconseillons de coder en dur la chaîne de connexion dans le code source. Préférez lire la chaîne de connexion à partir d’un magasin de secrets, comme Key Vault, et transmettez-la à AddAzureSignalR().

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>