Partager via

Écrire le code d’authentification de l’application cliente

  • Article

Après avoir configuré une instance et une authentification Azure Digital Twins, vous pouvez créer une application cliente que vous allez utiliser pour interagir avec l’instance. Après avoir configuré un projet client de démarrage, vous devez écrire du code dans cette application cliente pour l’authentifier auprès de l’instance Azure Digital Twins.

Azure Digital Twins s’authentifie à l’aide de jetons de sécurité Microsoft Entra basés sur OAUTH 2.0. Pour authentifier votre kit de développement logiciel (SDK), vous devez obtenir un jeton du porteur avec les autorisations appropriées sur Azure Digital Twins et le transmettre avec vos appels d’API.

Cet article explique comment obtenir des informations d’identification à l’aide de la bibliothèque cliente Azure.Identity. Bien que cet article présente des exemples de code en C#, tels que ce que vous écrivez pour le kit de développement logiciel (SDK) .NET (C#), vous pouvez utiliser une version de Azure.Identity quel que soit le kit de développement logiciel (SDK) que vous utilisez (pour plus d’informations sur les SDK disponibles pour Azure Digital Twins, consultez API et SDK Azure Digital Twins).

Prérequis

Tout d’abord, terminez les étapes de configuration dans Configurer une instance et l’authentification. Cette configuration permet de s’assurer que vous disposez d’une instance Azure Digital Twins et que votre utilisateur dispose d’autorisations d’accès. Une fois cette configuration terminée, vous êtes prêt à écrire le code de l’application cliente.

Pour continuer, vous aurez besoin d’un projet d’application cliente dans lequel écrire votre code. Si vous n’avez pas encore configuré de projet d’application cliente, créez un projet de base à utiliser avec ce didacticiel dans le langage de votre choix.

S’authentifier à l’aide de la bibliothèque Azure.Identity

Azure.Identity est une bibliothèque cliente qui fournit plusieurs méthodes d’obtention d’informations d’identification que vous pouvez utiliser pour obtenir un jeton du porteur et vous authentifier avec votre kit de développement logiciel (SDK). Bien que cet article donne des exemples en C# , vous pouvez afficher Azure.Identity pour plusieurs langages, notamment...

Trois méthodes d’obtention d’informations d’identification courantes dans Azure.Identity sont les suivantes :

  • DefaultAzureCredential fournit un flux d’authentification TokenCredential par défaut pour les applications qui seront déployées sur Azure, et est le choix recommandé pour le développement local. Il peut également être activé pour essayer les deux autres méthodes recommandées dans cet article. Il encapsule ManagedIdentityCredential et peut accéder à InteractiveBrowserCredential à l’aide d’une variable de configuration.
  • ManagedIdentityCredential fonctionne bien dans les cas où vous avez besoin d’identités managées (MSI) et est un bon candidat pour travailler avec Azure Functions et déployer sur les services Azure.
  • InteractiveBrowserCredential est destiné aux applications interactives et peut être utilisé pour créer un client de kit de développement logiciel (SDK) authentifié.

Le reste de cet article explique comment utiliser ces méthodes avec le Kit de développement logiciel (SDK) .NET (C#).

Ajouter Azure.Identity à votre projet .NET

Pour configurer votre projet .NET pour l’authentification avec Azure.Identity, procédez comme suit :

  1. Incluez le package du kit de développement logiciel (SDK) Azure.DigitalTwins.Core et le package Azure.Identity dans votre projet. Selon les outils que vous choisissez, vous pouvez inclure les packages à l’aide du gestionnaire de package Visual Studio ou de l’outil en ligne de commande dotnet.

  2. Ajoutez les instructions using suivantes à votre code de projet :

    using Azure.DigitalTwins.Core;
using Azure.Identity;
using System;

Ajoutez ensuite du code pour obtenir des informations d’identification à l’aide de l’une des méthodes dans Azure.Identity. Les sections suivantes fournissent plus de détails sur l’utilisation de chacune d’elles.

Méthode DefaultAzureCredential

DefaultAzureCredential fournit un flux d’authentification TokenCredential par défaut pour les applications qui seront déployées sur Azure, et est le choix recommandé pour le développement local.

Pour utiliser les informations d’identification Azure par défaut, vous avez besoin de l’URL de l’instance Azure Digital Twins (instructions pour les trouver).

Voici un exemple de code pour ajouter un DefaultAzureCredential à votre projet :

public class DefaultAzureCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new DefaultAzureCredential();
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Remarque

Il existe actuellement un problème connu affectant la classe wrapper DefaultAzureCredential susceptible d’entraîner une erreur lors de l’authentification. Si vous rencontrez ce problème, vous pouvez essayer d’instancier DefaultAzureCredential avec le paramètre facultatif suivant afin de le résoudre : new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

Pour plus d’informations sur ce problème, consultez Problèmes connus d’Azure Digital Twins.

Configurer les informations d’identification Azure locales

Avec DefaultAzureCredential, l’exemple recherche les informations d’identification dans votre environnement local, comme une connexion Azure dans une interface de ligne de commande Azure locale ou dans Visual Studio ou Visual Studio Code. C’est la raison pour laquelle vous devez vous connecter à Azure localement via l’un de ces mécanismes afin de configurer les informations d’identification pour l’exemple.

Si vous utilisez Visual Studio ou Visual Studio Code pour exécuter des exemples de code, vérifiez que vous êtes connecté à cet éditeur avec les mêmes informations d’identification Azure que celles que vous souhaitez utiliser pour accéder à votre instance Azure Digital Twins. Si vous utilisez une fenêtre CLI locale, exécutez la commande az login pour vous connecter à votre compte Azure. Après cela, lorsque vous exécutez votre échantillon de code, vous devriez être authentifié automatiquement.

Méthode ManagedIdentityCredential

La méthode ManagedIdentityCredential fonctionne bien dans les cas où vous avez besoin d’identités managées (MSI), par exemple lors de l’authentification auprès d’Azure Functions.

Cela signifie que vous pouvez utiliser ManagedIdentityCredential dans le même projet que DefaultAzureCredential ou InteractiveBrowserCredentialpour authentifier une autre partie du projet.

Pour utiliser les informations d’identification Azure par défaut, vous avez besoin de l’URL de l’instance Azure Digital Twins (instructions pour les trouver). Il se peut que vous ayez également besoin de l’inscription d’application et de l’ID d’application.

Dans une fonction Azure, vous pouvez utiliser les informations d’identification de l’identité managée comme suit :

public class ManagedIdentityCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        DigitalTwinsClient client;
        try
        {
            // To use the function app's system-assigned identity:
            ManagedIdentityCredential cred = new ManagedIdentityCredential();
            // To use a user-assigned identity for the function app:
            //ManagedIdentityCredential cred = new ManagedIdentityCredential("<uai-client-ID>");

            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Lors de la création des informations d’identification, laissant le paramètre vide comme indiqué ci-dessus retourne les informations d’identification pour l’identité affectée par le système de l’application de fonction, si elle en a une. Pour spécifier une identité affectée par l’utilisateur à la place, transmettez l’ID client de l’identité affectée par l’utilisateur dans le paramètre.

Méthode InteractiveBrowserCredential

La méthode InteractiveBrowserCredential est destinée aux applications interactives et affiche un navigateur web pour l’authentification. Vous pouvez utiliser cette méthode à la place de DefaultAzureCredential lorsque vous avez besoin d’une authentification interactive.

Pour utiliser les informations d’identification du navigateur interactif, vous avez besoin d’une inscription d’application disposant d’autorisations sur les API Azure Digital Twins. Pour plus d’informations sur la configuration de cette inscription d’application, consultez Créer une inscription d’application avec accès à Azure Digital Twins. Une fois l’inscription d’application configurée, vous avez besoin de...

Voici un exemple de code permettant de créer un client du kit de développement logiciel (SDK) authentifié à l’aide de InteractiveBrowserCredential.

public class InteractiveBrowserCredentialSample
{
    // Your client / app registration ID
    private const string clientId = "<your-client-ID>";
    // Your tenant / directory ID
    private const string tenantId = "<your-tenant-ID>";
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new InteractiveBrowserCredential(tenantId, clientId);
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Remarque

Bien que vous puissiez placer l’ID client, l’ID de locataire et l’URL de l’instance directement dans le code comme indiqué ci-dessus, il peut être judicieux de faire en sorte que votre code récupère ces valeurs à partir d’un fichier de configuration ou d’une variable d’environnement.

Authentifier Azure Functions

Cette section contient quelques-unes des options de configuration importantes dans le contexte de l’authentification avec Azure Functions. Tout d’abord, vous allez découvrir les concepts sur les variables au niveau de la classe et le code d’authentification permettant à la fonction d’accéder à Azure Digital Twins. Ensuite, vous découvrirez certaines étapes de configuration finales à effectuer pour votre fonction une fois que son code est publié sur Azure.

Écrire le code de l’application

Lors de l’écriture de la fonction Azure, envisagez d’ajouter ces variables et du code à votre fonction :

  • Code permettant de lire l’URL du service Azure Digital Twins en tant que variable d’environnement ou de paramètre de configuration. Il est recommandé de lire l’URL du service à partir d’un(e) paramètre d’application/variable d’environnement plutôt que de le (la) coder en dur dans la fonction. Dans une fonction Azure, ce code permettant de lire la variable d’environnement peut se présenter comme suit :

    private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");

    Plus tard, après avoir publié la fonction, vous allez créer et définir la valeur de la variable d’environnement pour que ce code soit lu. Pour obtenir des instructions sur la procédure à suivre, passez directement à la section Configurer les paramètres de l’application.

  • Une variable statique destinée à contenir une instance HttpClient. HttpClient étant relativement coûteux à créer, vous souhaiterez probablement le créer une fois avec le code d’authentification pour éviter d’avoir à le créer pour chaque appel de fonction.

    private static readonly HttpClient singletonHttpClientInstance = new HttpClient();

  • Informations d’identification d’identité managée. Créez les informations d’identification d’identité managée que votre fonction utilisera pour accéder à Azure Digital Twins.

    // To use the function app's system-assigned identity:
var cred = new ManagedIdentityCredential();
// To use a user-assigned identity for the function app:
//var cred = new ManagedIdentityCredential("<uai-client-ID>");

    Laissant le paramètre vide comme indiqué ci-dessus retourne les informations d’identification de l’identité affectée par le système de l’application de fonction, si elle en a une. Pour spécifier une identité affectée par l’utilisateur à la place, transmettez l’ID client de l’identité affectée par l’utilisateur dans le paramètre.

    Par la suite, après la publication de la fonction, vous vous assurez que l’identité de la fonction a l’autorisation d’accéder aux API Azure Digital Twins. Pour obtenir des instructions sur la procédure à suivre, passez directement à la rubrique Attribuer un rôle d’accès.

  • Variable locale DigitalTwinsClient. Ajoutez la variable à l'intérieur de votre fonction pour contenir votre instance de client Azure Digital Twins. Vous ne devez pas rendre cette variable statique dans votre classe.

    var client = new DigitalTwinsClient(
    new Uri(adtInstanceUrl),
    cred,
    new DigitalTwinsClientOptions
    {
        Transport = new HttpClientTransport(singletonHttpClientInstance)
    });

  • Case activée null pour adtInstanceUrl. Ajoutez le contrôle de valeur Null, puis wrappez la logique de votre fonction dans un bloc try/catch pour intercepter toutes les exceptions.

Une fois ces variables ajoutées à une fonction, votre code de fonction peut ressembler à l’exemple suivant.

// Default URL for triggering event grid function in the local environment.
// http://localhost:7071/runtime/webhooks/EventGrid?functionName={functionname}
//<Function_dependencies>
using Azure.Core.Pipeline;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using Azure.Messaging.EventGrid;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;
using System;
using System.Net.Http;
//</Function_dependencies>

namespace DigitalTwins_Samples
{
    public class DigitalTwinsIngestFunctionSample
    {
        // Your Digital Twin URL is stored in an application setting in Azure Functions
        // <ADT_service_URL>
        private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
        // </ADT_service_URL>
        // <HTTP_client>
        private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
        // </HTTP_client>

        [FunctionName("TwinsFunction")]
        public void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.Data.ToString());
            if (adtInstanceUrl == null) log.LogError("Application setting \"ADT_SERVICE_URL\" not set");
            try
            {
                // Authenticate with Digital Twins
                // <ManagedIdentityCredential>
                // To use the function app's system-assigned identity:
                var cred = new ManagedIdentityCredential();
                // To use a user-assigned identity for the function app:
                //var cred = new ManagedIdentityCredential("<uai-client-ID>");
                // </ManagedIdentityCredential>
                // <DigitalTwinsClient>
                var client = new DigitalTwinsClient(
                    new Uri(adtInstanceUrl),
                    cred,
                    new DigitalTwinsClientOptions
                    {
                        Transport = new HttpClientTransport(singletonHttpClientInstance)
                    });
                // </DigitalTwinsClient>
                log.LogInformation($"ADT service client connection created.");

                // Add your business logic here.
            }
            catch (Exception e)
            {
                log.LogError(e.Message);
            }
        }
    }
}

Lorsque vous avez terminé avec votre code de fonction, y compris l’ajout de l’authentification et la logique de la fonction, publiez l’application dans Azure

Configurer l’application publiée

Enfin, effectuez les étapes de configuration suivantes pour une fonction Azure publiée afin de vous assurer qu’elle peut accéder à votre instance Azure Digital Twins.

Exécutez les commandes suivantes dans Azure Cloud Shell ou une interface locale d’Azure CLI.

Remarque

Cette section doit être effectuée par un utilisateur Azure qui dispose des autorisations nécessaires pour gérer l’accès utilisateur aux ressources Azure, y compris l’octroi et la délégation d’autorisations. Les rôles communs qui répondent à cette exigence sont Propriétaire, Administrateur de compte ou la combinaison des rôles Administrateur de l’accès utilisateur et Contributeur. Pour plus d’informations sur les exigences d’autorisation pour les rôles Azure Digital Twins, consultez Configurer une instance et l’authentification.

Attribuer un rôle d’accès

La fonction Azure nécessite un jeton de porteur pour transmission. Pour vous assurer que le jeton du porteur est transmis, accordez à l’Application de fonction le rôle de Propriétaire des données Azure Digital Twins pour votre instance Azure Digital Twins, ce qui permettra à l’application de fonction d’effectuer des activités de plan de données sur l’instance.

  1. Utilisez la commande suivante pour créer une identité managée affectée par le système pour votre fonction (si la fonction en a déjà une, cette commande imprime les détails). Notez le principalId champ dans la sortie. Vous utiliserez cet ID pour faire référence à la fonction afin de pouvoir lui accorder des autorisations à l’étape suivante.

    az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>

  2. Utilisez la principalId valeur dans la commande suivante afin d’affecter à la fonction le rôle de Propriétaire des données Azure Digital Twins pour votre instance Azure Digital Twins.

    az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"

Configurer les paramètres de l’application

Ensuite, rendez l’URL de votre instance Azure Digital Twins accessible à votre fonction en définissant une variable d’environnement pour celle-ci.

Conseil

L’URL de l’instance Azure Digital Twins est créée en ajoutant https:// au début du nom d’hôte de votre instance. Pour afficher le nom d’hôte, ainsi que toutes les propriétés de votre instance, exécutez az dt show --dt-name <your-Azure-Digital-Twins-instance>.

La commande suivante définit une variable d’environnement pour l’URL d’instance que votre fonction utilisera chaque fois qu’elle aura besoin d’accéder à l’instance.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

S’authentifier auprès des locataires

Azure Digital Twins est un service qui ne prend en charge qu’un seul locataire Microsoft Entra : le locataire principal de l’abonnement où se trouve l’instance Azure Digital Twins.

Par conséquent, les demandes envoyées aux API Azure Digital Twins nécessitent un utilisateur ou un principal de service qui fait partie du même locataire que celui où réside l’instance Azure Digital Twins. Pour empêcher l’analyse malveillante des points de terminaison Azure Digital Twins, les demandes avec des jetons d’accès qui ne proviennent pas du locataire d’origine recevront le message d’erreur « 404 Sous-domaine introuvable ». Cette erreur est retournée même si l’utilisateur ou le principal de service a reçu un rôle de propriétaire de données Azure Digital Twins ou lecteur de données Azure Digital Twins via Microsoft Entra B2B Collaboration.

Si vous avez besoin d’accéder à votre instance Azure Digital Twins à l’aide d’un principal de service ou d’un compte d’utilisateur qui appartient à un autre locataire de l’instance, vous pouvez faire en sorte que chaque identité fédérée issue d’un autre locataire demande un jeton au locataire « d’accueil » de l’instance Azure Digital Twins.

Pour ce faire, utilisez la commande CLI suivante, où <home-tenant-ID> est l’ID du locataire Microsoft Entra qui contient l’instance Azure Digital Twins :

az account get-access-token --tenant <home-tenant-ID> --resource https://digitaltwins.azure.net

Après avoir demandé cela, l’identité reçoit un jeton émis pour la https://digitaltwins.azure.net ressource Microsoft Entra, qui a une revendication d’ID de locataire correspondante à l’instance Azure Digital Twins. L’utilisation de ce jeton dans les demandes d’API ou avec votre code Azure.Identity doit permettre à l’identité fédérée d’accéder à la ressource Azure Digital Twins.

Vous pouvez également spécifier un locataire d’accueil dans les options d’informations d’identification de votre code.

L’exemple suivant montre comment définir un exemple de valeur d’ID de locataire pour InteractiveBrowserTenantId dans les options DefaultAzureCredential :

public class DefaultAzureCredentialOptionsSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    private static DefaultAzureCredentialOptions credentialOptions = new DefaultAzureCredentialOptions()
    {
        ExcludeSharedTokenCacheCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        TenantId = "<your-Azure-Active-Directory-tenant-ID>"
    };

    private static DefaultAzureCredential credential = new DefaultAzureCredential(credentialOptions);

    DigitalTwinsClient client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
}

Des options similaires sont disponibles pour définir un locataire pour l’authentification avec Visual Studio et Visual Studio Code. Pour plus d’informations sur les options disponibles, consultez la documentation de DefaultAzureCredentialOptions.

Autres méthodes d’informations d’identification

Si les scénarios d’authentification indiqués ci-dessus ne couvrent pas les besoins de votre application, vous pouvez explorer les autres types d’authentification proposés dans la Plateforme d’identité Microsoft. La documentation de cette plateforme couvre des scénarios d’authentification supplémentaires, organisés par type d’application.

Étapes suivantes

En savoir plus sur le fonctionnement de la sécurité dans Azure Digital Twins :

Sinon, l’authentification étant configurée, passez à la création et à la gestion de modèles dans votre instance :