Chaîne de connexion dans Azure SignalR Service

  • Article
  • 8 minutes de lecture

La chaîne de connexion est un élément important qui contient des informations expliquant comment se connecter au service SignalR. Dans cet article, vous allez découvrir les principes fondamentaux de la chaîne de connexion et voir comment la configurer dans votre application.

Qu’est-ce qu’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 de service SignalR
  • Comment s’authentifier auprès du point de terminaison de service

La chaîne de connexion contient des informations expliquant comment s’authentifier.

À quoi ressemble la chaîne de connexion

Une chaîne de connexion se compose d’une série de paires clé/valeur séparées par des points-virgules (;) et nous utilisons un signe égal (=) pour connecter chaque clé et sa valeur. Les clés ne respectent pas la casse.

Par exemple, une chaîne de connexion classique peut ressembler à ceci :

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

Dans la chaîne de connexion, vous verrez deux informations principales :

  • 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. Quand la clé d’accès est spécifiée dans la chaîne de connexion, le SDK du service SignalR l’utilise pour générer un jeton qui peut être validé par le service.

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

key Description Obligatoire Valeur par défaut Valeur d'exemple
Point de terminaison URI de votre instance ASRS. O N/A https://foo.service.signalr.net
Port Port sur lequel votre instance ASRS écoute. N 80/443, en fonction du schéma d’URI du point de terminaison 8080
Version Version de la chaîne de connexion donnée. N 1.0 1.0
ClientEndpoint URI de votre proxy inverse, comme App Gateway ou API Management N null https://foo.bar
AuthType Le type d’authentification ; nous allons utiliser AccessKey pour autoriser les requêtes par défaut. Insensible à la casse N null azure, azure.msi, azure.app

Utiliser AccessKey

La méthode d’authentification locale est utilisée lorsque AuthType est défini sur Null.

key Description Obligatoire Valeur par défaut Valeur d'exemple
AccessKey Chaîne de clé au format base64 pour générer l’utilisation des jetons d’accès. O null ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/

Utiliser Azure Active Directory

La méthode d’authentification Azure AD sera utilisée quand AuthType est défini sur azure, azure.app ou azure.msi.

key Description Obligatoire Valeur par défaut Valeur d'exemple
ClientId Un guid représente une application Azure ou une identité Azure. N null 00000000-0000-0000-0000-000000000000
TenantId Dans Azure Active Directory, un GUID représente une organisation. N null 00000000-0000-0000-0000-000000000000
ClientSecret Mot de passe d’une instance d’application Azure. N null ***********************.****************
ClientCertPath Chemin absolu d’un fichier de certificat vers une instance d’application Azure. N null /usr/local/cert/app.cert

Différentes valeurs de TokenCredential seront utilisées pour générer des jetons Azure AD en respectant les paramètres que vous avez donnés.

Comment obtenir mes chaînes de connexion

À partir du portail Azure

Ouvrez votre ressource de service SignalR dans le portail Azure et accédez à l’onglet Keys.

Vous verrez deux chaînes de connexion (primaire et secondaire) au format suivant :

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

À partir d’Azure CLI

Vous pouvez également utiliser Azure CLI pour récupérer la chaîne de connexion :

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

Pour utiliser l’application Azure AD

Vous pouvez utiliser l’application Azure AD pour vous connecter au service SignalR. Tant que l’application dispose de l’autorisation appropriée pour accéder au service SignalR, aucune clé d’accès n’est nécessaire.

Pour utiliser l’authentification Azure AD, 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 Azure AD, y compris l’ID client, le secret client et l’ID du locataire. La chaîne de connexion doit ressembler à ceci :

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 à l’aide de l’application Azure AD, consultez cet article.

Pour utiliser l’identité managée

Vous pouvez également utiliser une identité managée pour vous authentifier auprès du service SignalR.

Il existe deux types d’identités managées. Pour utiliser l’identité attribuée par le système, il vous suffit d’ajouter AuthType=azure.msi à la chaîne de connexion :

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

Le SDK du service SignalR utilise automatiquement l’identité de votre serveur d’applications.

Pour utiliser l’identité attribuée par l’utilisateur, vous devez également spécifier l’ID client de l’identité managée :

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

Pour plus d’informations sur la configuration de l’identité managée, consultez cet article.

Notes

Il est vivement recommandé d’utiliser Azure AD pour s’authentifier auprès du service SignalR, car il s’agit d’une méthode plus sécurisée que l’utilisation d’une clé d’accès. Si vous n’utilisez jamais l’authentification par clé d’accès, vous pouvez la désactiver (accédez au portail Azure -> Clés -> Clé d’accès -> Désactiver). Si vous utilisez toujours des clés d’accès, nous vous recommandons vivement d’effectuer régulièrement une rotation des clés (pour plus d’informations, cliquez ici).

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

La création manuelle d’une chaîne de connexion peut être fastidieuse et sujette aux erreurs.

Pour éviter les erreurs, nous avons créé un outil pour vous aider à générer une chaîne de connexion avec des identités Azure AD comme clientId, tenantId, etc.

Pour utiliser le générateur de chaînes de connexion, ouvrez votre ressource SignalR dans le portail Azure, puis accédez à l’onglet Connection strings :

Capture d’écran montrant le générateur de chaînes de connexion du service SignalR dans le portail Azure.

Dans cette page, vous pouvez choisir différents types d’authentification (clé d’accès, identité managée ou application Azure AD) ainsi que des informations telles que le point de terminaison client, l’ID client, le secret client, etc. La chaîne de connexion est alors générée automatiquement. Vous pouvez la copier et l’utiliser dans votre application.

Notes

Tout ce que vous entrez dans cette page ne sera pas enregistré quand vous quitterez la page (puisqu’il ne s’agit que d’informations côté client). Par conséquent, vous devez les copier et les enregistrer dans un emplacement sécurisé pour que votre application puisse les utiliser.

Notes

Pour plus d’informations sur la génération et la validation des jetons d’accès, consultez cet article.

Points de terminaison du client et du serveur

La chaîne de connexion contient le point de terminaison HTTP permettant au serveur d’applications de se connecter au service SignalR. Il s’agit du point de terminaison qui sera retourné par le serveur aux clients dans la réponse de négociation, de sorte que le client pourra également se connecter au service.

Toutefois, dans certaines applications, toutes les connexions clientes devront d’abord passer par un composant supplémentaire situé devant le service SignalR (pour obtenir des avantages supplémentaires comme la sécurité réseau, vous pouvez utiliser le service Azure Application Gateway qui fournit de telles fonctionnalités).

Dans ce cas, le client doit se connecter à un point de terminaison différent de celui du service SignalR. 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;

Ensuite, le serveur d’applications retournera l’URL de point de terminaison appropriée dans la réponse de négociation pour que le client se connecte.

Notes

Pour plus d’informations sur la façon dont les clients peuvent obtenir l’URL du service via une négociation, consultez cet article.

De même, lorsque le serveur souhaite établir des connexions au serveur ou appeler des API REST pour le service SignalR, ce dernier peut lui aussi se trouver derrière un autre service comme 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 votre application

Il existe deux façons de configurer une chaîne de connexion dans votre application.

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 lira alors la chaîne de connexion à partir d’une configuration nommée Azure:SignalR:ConnectionString dans vos fournisseurs de configuration.

Dans un environnement de développement local, la configuration est stockée dans le fichier (appsettings.json ou secrets.json) ou dans les variables d’environnement. Vous pouvez donc utiliser l’une des méthodes suivantes pour configurer la chaîne de connexion :

  • Utiliser le gestionnaire de secrets .NET (dotnet user-secrets set Azure:SignalR:ConnectionString "<connection_string>")
  • Définissez la chaîne de connexion sur la variable d’environnement nommée Azure__SignalR__ConnectionString (vous devrez remplacer les deux-points par un trait de soulignement double dans le fournisseur de configuration de la variable 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 le fournisseur de configuration pour ces services, consultez leur documentation.

Notes

Même si vous définissez directement la chaîne de connexion à l’aide de code, il n’est pas recommandé de coder en dur la chaîne de connexion dans le code source. Par conséquent, vous devez d’abord lire la chaîne de connexion à partir d’un magasin de secrets comme Key Vault, puis la passer à AddAzureSignalR().

Configurer plusieurs chaînes de connexion

Azure SignalR Service permet également au serveur de se connecter à plusieurs points de terminaison de service en même temps. De cette façon, il peut gérer les connexions qui dépassent la limite d’une instance de service. De même, si une instance de service est arrêtée, d’autres instances de service peuvent être utilisées comme instances de secours. Pour plus d’informations sur l’utilisation de plusieurs instances, consultez cet article.

Il existe deux façons de configurer plusieurs instances :

  • Via le code

    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.

  • Via la configuration

    Vous pouvez utiliser n’importe quel fournisseur de configuration pris en charge (gestionnaire de secrets, variables d’environnement, coffre de clés, etc.) pour stocker des chaînes de connexion. Prenons l’exemple du gestionnaire de secrets :

    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>