Démarrage rapide : initialisation des applications clientes (C#)

Article
10/18/2023

Ce démarrage rapide vous expliquera comment implémenter le modèle d’initialisation du client, utilisé par le wrapper .NET du kit de développement logiciel (SDK) MIP lors du runtime.

Remarque

Les étapes décrites dans ce démarrage rapide sont nécessaires pour toute application cliente qui utilise les kits SDK MIP du wrapper .NET File, Policy ou Protection. Bien que ce Démarrage rapide illustre l’utilisation des kits de développement logiciel (SDK) File, ce même modèle est applicable aux clients qui utilisent les kits de développement logiciel (SDK) Policy et Protection. Les Démarrages rapides futurs doivent être exécutés en série, car chacun repose sur le précédent, celui-ci étant le premier. Ce code sert à montrer le démarrage avec le kit SDK MIP. Il n’est pas prévu pour une utilisation en production.

Prérequis

Si ce n’est déjà fait, veillez à :

Suivre les étapes dans Installation et configuration du kit de développement logiciel (SDK) Microsoft Information Protection. Ce Démarrage rapide « Initialisation des applications clientes » repose sur l’installation et la configuration appropriées du kit de développement logiciel (SDK).
Si vous le souhaitez :
- Passez en revue Objets de profil et de moteur. Les objets de profil et de moteur sont des concepts universels requis par les clients qui utilisent les kits de développement logiciel (SDK) MIP File/Policy/Protection.
- Passez en revue les Concepts d’authentification pour découvrir comment l’authentification et le consentement sont implémentés par le kit de développement logiciel (SDK) et l’application cliente.

Créer une solution et un projet Visual Studio

Tout d’abord, nous créons et configurons la solution et le projet Visual Studio initiaux sur lesquels reposeront les autres démarrages rapides.

Ouvrez Visual Studio 2019, sélectionnez le menu Fichier, Nouveau, puis Projet. Dans la boîte de dialogue Nouveau projet :
- Dans le volet gauche, sous Installé, Visual C#, sélectionnez Bureau Windows.
- Dans le volet central, sélectionnez Application console (.NET Framework)
- Dans le volet inférieur, mettez à jour le Nom du projet, l’Emplacement et le Nom de la solution qui le contient en conséquence.
- Lorsque vous avez terminé, cliquez sur le bouton OK en bas à droite.
Ajoutez le package NuGet du kit de développement logiciel (SDK) MIP File à votre projet :
- Dans l’Explorateur de solutions, cliquez avec le bouton de droite sur le nœud du projet (directement sous le nœud supérieur/de la solution), puis sélectionnez Gérer les packages NuGet… :
- Lorsque l’onglet Gestionnaire de packages NuGet s’ouvre dans la zone des onglets du groupe d’éditeurs :
  - Cliquez sur Parcourir.
  - Entrez « Microsoft.InformationProtection » dans la zone de recherche.
  - Sélectionnez le package « Microsoft.InformationProtection.File ».
  - Cliquez sur « Installer », puis sur « OK » lorsque la boîte de dialogue de confirmation Aperçu des modifications s’affiche.
Répétez les étapes ci-dessus pour ajouter le package du kit de développement logiciel (SDK) File MIP, mais ajoutez à la place « Microsoft.Identity.Client » à l’application.

Implémenter un délégué d’authentification

Le kit de développement logiciel (SDK) MIP implémente l’authentification à l’aide de l’extensibilité de la classe, ce qui fournit un mécanisme pour partager le travail d’authentification avec l’application cliente. Le client doit acquérir un jeton d’accès OAuth2 approprié et le fournir au kit de développement logiciel (SDK) MIP lors du runtime.

Maintenant, créez une implémentation pour un délégué d’authentification en étendant l’interface Microsoft.InformationProtection.IAuthDelegate du kit de développement logiciel (SDK) et en substituant/implémentant la fonction virtuelle IAuthDelegate.AcquireToken(). Le délégué d’authentification est instancié et utilisé ultérieurement par les objets FileProfile et FileEngine.

Cliquez avec le bouton de droite sur le nom du projet dans Visual Studio, sélectionnez Ajouter, puis Classe.
Saisissez « AuthDelegateImplementation » dans le champ Nom. Cliquez sur Ajouter.
Ajoutez des instructions d’utilisation à l’aide de la bibliothèque Microsoft Authentication Library (MSAL) et de la bibliothèque MIP :
```
using Microsoft.InformationProtection;
using Microsoft.Identity.Client;
```
Définissez AuthDelegateImplementation pour hériter Microsoft.InformationProtection.IAuthDelegate et implémenter une variable privée de Microsoft.InformationProtection.ApplicationInfo et un constructeur qui accepte le même type.
```
public class AuthDelegateImplementation : IAuthDelegate
{
   private ApplicationInfo _appInfo;
   // Microsoft Authentication Library IPublicClientApplication
   private IPublicClientApplication _app;
   public AuthDelegateImplementation(ApplicationInfo appInfo)
   {
       _appInfo = appInfo;
   }

}
```
L’objet ApplicationInfo contient trois propriétés. _appInfo.ApplicationId sera utilisé dans la classe AuthDelegateImplementation pour fournir l’ID client à la bibliothèque d’authentification. ApplicationName et ApplicationVersion seront disponibles dans les rapports d’analyse Azure Information Protection.

Ajoutez la méthode public string AcquireToken(). Cette méthode doit accepter Microsoft.InformationProtection.Identity et trois chaînes : URL de l’autorité, URI des ressources et les déclarations (si nécessaire). Ces variables de chaîne seront transmises à la bibliothèque d’authentification par l’API et ne doivent pas être manipulées. Veuillez saisir le GUID abonné à partir du Portail Azure pour votre abonné. La modification de chaînes autres que le GUID abonné peut entraîner une défaillance de l’authentification.

public string AcquireToken(Identity identity, string authority, string resource, string claims)
{
   var authorityUri = new Uri(authority);
   authority = String.Format("https://{0}/{1}", authorityUri.Host, "<Tenant-GUID>");

   _app = PublicClientApplicationBuilder.Create(_appInfo.ApplicationId).WithAuthority(authority).WithDefaultRedirectUri().Build();
   var accounts = (_app.GetAccountsAsync()).GetAwaiter().GetResult();

   // Append .default to the resource passed in to AcquireToken().
   string[] scopes = new string[] { resource[resource.Length - 1].Equals('/') ? $"{resource}.default" : $"{resource}/.default" };
   var result = _app.AcquireTokenInteractive(scopes).WithAccount(accounts.FirstOrDefault()).WithPrompt(Prompt.SelectAccount)
              .ExecuteAsync().ConfigureAwait(false).GetAwaiter().GetResult();

   return result.AccessToken;
}

Maintenant, créez une implémentation pour un délégué de consentement en étendant l’interface Microsoft.InformationProtection.IConsentDelegate du kit de développement logiciel (SDK) et en substituant/implémentant GetUserConsent(). Le délégué de consentement est instancié et utilisé ultérieurement par les objets de profil File et de moteur File. Le délégué de consentement est fourni avec l’adresse du service pour lequel l’utilisateur doit donner son consentement pour une utilisation dans le paramètre url. Le délégué doit généralement fournir un flux qui permet à l’utilisateur d’accepter ou de refuser de donner son consentement pour accéder au service. Pour ce démarrage rapide, codez en dur Consent.Accept.

En utilisant la fonctionnalité « Ajouter une classe » de Visual Studio que nous avons utilisée précédemment, ajoutez une autre classe à votre projet. Cette fois, entrez « ConsentDelegateImplementation » dans le champ Nom de la classe.
Maintenant, mettez à jour ConsentDelegateImpl.cs pour implémenter votre nouvelle classe de délégué de consentement. Ajoutez l’instruction d’utilisation pour Microsoft.InformationProtection et définissez la classe à hériter IConsentDelegate.
```
class ConsentDelegateImplementation : IConsentDelegate
{
     public Consent GetUserConsent(string url)
     {
          return Consent.Accept;
     }
}
```
Vous avez également la possibilité de tenter de générer la solution afin de vous assurer qu’aucune erreur ne se produit lors de la compilation.

Initialiser le wrapper managé du kit de développement logiciel (SDK) MIP

À partir de l’Explorateur de solutions, ouvrez le fichier .cs dans votre projet qui contient l’implémentation de la méthode Main(). Par défaut, il a le même nom que le projet qui le contient et que vous avez spécifié lors de la création du projet.
Supprimez l’implémentation générée de main().
Le wrapper managé inclut une classe statique, Microsoft.InformationProtection.MIP utilisée pour l’initialisation, la création d’un MipContext, le chargement des profils et le lancement de ressources. Pour initialiser le wrapper pour les opérations du kit de développement logiciel (SDK) File, appelez MIP.Initialize(), en passant par MipComponent.File pour charger les bibliothèques nécessaires aux opérations de fichiers.
Dans Main() dans Program.cs ajoutez ce qui suit, en remplaçant <application-id> par l’ID d’inscription d’application Microsoft Entra créé précédemment.

using System;
using System.Threading.Tasks;
using Microsoft.InformationProtection;
using Microsoft.InformationProtection.Exceptions;
using Microsoft.InformationProtection.File;
using Microsoft.InformationProtection.Protection;

namespace mip_sdk_dotnet_quickstart
{
    class Program
    {
        private const string clientId = "<application-id>";
        private const string appName = "<friendly-name>";

        static void Main(string[] args)
        {
            //Initialize Wrapper for File SDK operations
            MIP.Initialize(MipComponent.File);
            
        }
    }
}

Construire un profil et un moteur File

Comme mentionné, les objets de profil et de moteur sont requis par les clients du kit de développement logiciel (SDK) qui utilisent les API MIP. Complétez la partie de code de ce Démarrage rapide en ajoutant du code pour charger les DLL natives, puis instancier les objets de profil et de moteur.

using System;
using System.Threading.Tasks;
using Microsoft.InformationProtection;
using Microsoft.InformationProtection.File;

namespace mip_sdk_dotnet_quickstart
{
  class Program
  {
       private const string clientId = "<application-id>";
       private const string appName = "<friendly-name>";

       static void Main(string[] args)
       {
            // Initialize Wrapper for File SDK operations.
            MIP.Initialize(MipComponent.File);

            // Create ApplicationInfo, setting the clientID from Microsoft Entra App Registration as the ApplicationId.
            ApplicationInfo appInfo = new ApplicationInfo()
            {
                 ApplicationId = clientId,
                 ApplicationName = appName,
                 ApplicationVersion = "1.0.0"
            };

            // Instantiate the AuthDelegateImpl object, passing in AppInfo.
            AuthDelegateImplementation authDelegate = new AuthDelegateImplementation(appInfo);

            // Create MipConfiguration Object
            MipConfiguration mipConfiguration = new MipConfiguration(appInfo, "mip_data", LogLevel.Trace, false);

            // Create MipContext using Configuration
            MipContext mipContext = MIP.CreateMipContext(mipConfiguration);

            // Initialize and instantiate the File Profile.
            // Create the FileProfileSettings object.
            // Initialize file profile settings to create/use local state.
            var profileSettings = new FileProfileSettings(mipContext,
                                     CacheStorageType.OnDiskEncrypted,
                                     new ConsentDelegateImplementation());

            // Load the Profile async and wait for the result.
            var fileProfile = Task.Run(async () => await MIP.LoadFileProfileAsync(profileSettings)).Result;

            // Create a FileEngineSettings object, then use that to add an engine to the profile.
            // This pattern sets the engine ID to user1@tenant.com, then sets the identity used to create the engine.
            var engineSettings = new FileEngineSettings("user1@tenant.com", authDelegate, "", "en-US");
            engineSettings.Identity = new Identity("user1@tenant.com");

            var fileEngine = Task.Run(async () => await fileProfile.AddEngineAsync(engineSettings)).Result;

            // Application Shutdown
            // handler = null; // This will be used in later quick starts.
            fileEngine = null;
            fileProfile = null;
            mipContext.ShutDown();
            mipContext = null;
       }
  }
}

Remplacez les valeurs d’espace réservé dans le code source que vous avez collé par les valeurs suivantes :

Paramètre substituable	Valeur	Exemple
<application-id>	ID d’application Microsoft Entra attribué à l’application inscrite dans « Installation et configuration du kit de développement logiciel (SDK) MIP » (2 instances).	0edbblll-8773-44de-b87c-b8c6276d41eb
<friendly-name>	Nom convivial défini par l’utilisateur pour votre application.	AppInitialization
<Tenant-GUID>	ID locataire pour votre locataire Microsoft Entra	TenantID

Maintenant, procédez à une dernière génération de l’application et résolvez les erreurs éventuelles. Votre code doit être correctement généré.

Étapes suivantes

Maintenant que votre code d’initialisation est terminé, vous êtes prêt pour le prochain Démarrage rapide, où vous allez commencer à utiliser les kits de développement logiciel (SDK) MIP File.

Répertorier les étiquettes de confidentialité

Partager via

Démarrage rapide : initialisation des applications clientes (C#)

Prérequis

Créer une solution et un projet Visual Studio

Implémenter un délégué d’authentification

Initialiser le wrapper managé du kit de développement logiciel (SDK) MIP

Construire un profil et un moteur File

Étapes suivantes

Commentaires

Ressources supplémentaires

Partager via

Démarrage rapide : initialisation des applications clientes (C#)

Prérequis

Créer une solution et un projet Visual Studio

Implémenter un délégué d’authentification

Implémenter un délégué de consentement

Initialiser le wrapper managé du kit de développement logiciel (SDK) MIP

Construire un profil et un moteur File

Étapes suivantes

Commentaires

Ressources supplémentaires