Mulai cepat: Inisialisasi aplikasi klien (C#)

Artikel
10/18/2023

Mulai cepat ini akan menunjukkan kepada Anda cara menerapkan pola inisialisasi klien, yang digunakan oleh pembungkus MIP SDK .NET saat runtime.

Catatan

Langkah-langkah yang diuraikan dalam mulai cepat ini diperlukan untuk aplikasi klien apa pun yang menggunakan SDK File, Kebijakan, atau Perlindungan pembungkus MIP .NET. Meskipun Mulai Cepat ini menunjukkan penggunaan SDK File, pola yang sama ini berlaku untuk klien yang menggunakan SDK Kebijakan dan Perlindungan. Mulai Cepat Di Masa Depan harus dilakukan secara serial, karena masing-masing dibangun pada yang sebelumnya, dengan yang satu ini menjadi yang pertama. Kode ini dimaksudkan untuk menunjukkan cara memulai SDK MIP dan tidak dimaksudkan untuk penggunaan produksi.

Prasyarat

Jika Anda belum melakukannya, pastikan untuk:

Selesaikan langkah-langkah dalam penyiapan dan konfigurasi SDK Microsoft Information Protection (MIP). Mulai Cepat "Inisialisasi aplikasi klien" ini bergantung pada penyiapan dan konfigurasi SDK yang tepat.
Opsional:
- Tinjau Profil dan objek mesin. Objek profil dan mesin adalah konsep universal, yang diperlukan oleh klien yang menggunakan SDK File/Kebijakan/Perlindungan MIP.
- Tinjau konsep Autentikasi untuk mempelajari bagaimana autentikasi dan persetujuan diterapkan oleh SDK dan aplikasi klien.

Membuat solusi dan proyek Visual Studio

Pertama, kita membuat dan mengonfigurasi solusi dan proyek Visual Studio awal, di mana Mulai Cepat lainnya akan dibuat.

Buka Visual Studio 2019, pilih menu File , Baru, Proyek. Dalam dialog Proyek Baru:
- Di panel kiri, di bawah Terinstal, Visual C#, pilih Windows Desktop.
- Di panel tengah, pilih Aplikasi Konsol (.NET Framework)
- Di panel bawah, perbarui nama proyek, Lokasi, dan nama Solusi yang berisi yang sesuai.
- Setelah selesai, klik tombol OK di kanan bawah.
Tambahkan paket Nuget untuk MIP File SDK ke proyek Anda:
- Di Penjelajah Solusi, klik kanan pada simpul proyek (langsung di bawah node atas/solusi), dan pilih Kelola paket NuGet...:
- Saat tab Pengelola Paket NuGet terbuka di area tab Grup Editor:
  - Pilih Telusur.
  - Masukkan "Microsoft.InformationProtection" di kotak pencarian.
  - Pilih paket "Microsoft.InformationProtection.File".
  - Klik "Instal", lalu klik "OK" saat dialog Konfirmasi perubahan pratinjau ditampilkan.
Ulangi langkah-langkah di atas untuk menambahkan paket MIP File SDK, tetapi sebagai gantinya tambahkan "Microsoft.Identity.Client" ke aplikasi.

Menerapkan delegasi autentikasi

MIP SDK menerapkan autentikasi menggunakan ekstensibilitas kelas, yang menyediakan mekanisme untuk berbagi pekerjaan autentikasi dengan aplikasi klien. Klien harus memperoleh token akses OAuth2 yang sesuai, dan menyediakan ke MIP SDK saat runtime.

Sekarang buat implementasi untuk delegasi autentikasi, dengan memperluas antarmuka SDK Microsoft.InformationProtection.IAuthDelegate , dan menimpa/mengimplementasikan IAuthDelegate.AcquireToken() fungsi virtual. Delegasi autentikasi dibuat dan digunakan nanti oleh FileProfile objek dan FileEngine .

Klik kanan nama proyek di Visual Studio, pilih Tambahkan lalu Kelas.
Masukkan "AuthDelegateImplementation" di bidang Nama . Klik Tambahkan.
Tambahkan menggunakan pernyataan untuk Microsoft Authentication Library (MSAL) dan pustaka MIP:
```
using Microsoft.InformationProtection;
using Microsoft.Identity.Client;
```
Atur AuthDelegateImplementation untuk mewarisi Microsoft.InformationProtection.IAuthDelegate dan mengimplementasikan variabel Microsoft.InformationProtection.ApplicationInfo privat dan konstruktor yang menerima jenis yang sama.
```
public class AuthDelegateImplementation : IAuthDelegate
{
   private ApplicationInfo _appInfo;
   // Microsoft Authentication Library IPublicClientApplication
   private IPublicClientApplication _app;
   public AuthDelegateImplementation(ApplicationInfo appInfo)
   {
       _appInfo = appInfo;
   }

}
```
Objek ApplicationInfo berisi tiga properti. _appInfo.ApplicationId akan digunakan di AuthDelegateImplementation kelas untuk memberikan ID klien ke pustaka autentikasi. ApplicationName dan ApplicationVersion akan muncul dalam laporan Azure Information Protection Analytics.

Tambahkan metode public string AcquireToken(). Metode ini harus menerima Microsoft.InformationProtection.Identity dan tiga string: URL otoritas, URI sumber daya, dan klaim, jika diperlukan. Variabel string ini akan diteruskan ke pustaka autentikasi oleh API dan tidak boleh dimanipulasi. Masukkan GUID Penyewa dari portal Azure untuk penyewa Anda. Mengedit string selain GUID Penyewa dapat mengakibatkan kegagalan untuk mengautentikasi.

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

Sekarang buat implementasi untuk delegasi persetujuan, dengan memperluas antarmuka SDK Microsoft.InformationProtection.IConsentDelegate , dan mengambil alih/menerapkan GetUserConsent(). Delegasi persetujuan dibuat dan digunakan nanti, oleh profil File dan objek mesin file. Delegasi persetujuan disediakan dengan alamat layanan yang harus disetujui pengguna untuk menggunakan dalam url parameter . Delegasi umumnya harus memberikan beberapa alur yang memungkinkan pengguna untuk menerima atau menolak persetujuan untuk mengakses layanan. Untuk kode Consent.Acceptkeras mulai cepat ini .

Menggunakan fitur "Tambahkan Kelas" Visual Studio yang sama dengan yang kami gunakan sebelumnya, tambahkan kelas lain ke proyek Anda. Kali ini, masukkan "ConsentDelegateImplementation" di bidang Nama Kelas.
Sekarang perbarui ConsentDelegateImpl.cs untuk mengimplementasikan kelas delegasi persetujuan baru Anda. Tambahkan pernyataan penggunaan untuk Microsoft.InformationProtection dan atur kelas untuk mewarisi IConsentDelegate.
```
class ConsentDelegateImplementation : IConsentDelegate
{
     public Consent GetUserConsent(string url)
     {
          return Consent.Accept;
     }
}
```
Secara opsional, coba bangun solusi untuk memastikan bahwa solusi dikompilasi tanpa kesalahan.

Menginisialisasi Pembungkus Terkelola MIP SDK

Dari Penjelajah Solusi, buka file .cs dalam proyek Anda yang berisi implementasi Main() metode . Ini default ke nama yang sama dengan proyek yang berisinya, yang Anda tentukan selama pembuatan proyek.
Hapus implementasi yang dihasilkan dari main().
Pembungkus terkelola mencakup kelas statis, Microsoft.InformationProtection.MIP digunakan untuk inisialisasi, membuat MipContext, memuat profil, dan merilis sumber daya. Untuk menginisialisasi pembungkus untuk operasi File SDK, panggil MIP.Initialize(), teruskan MipComponent.File untuk memuat pustaka yang diperlukan untuk operasi file.
Di Main() Program.cs tambahkan yang berikut ini, ganti <application-id> dengan ID Pendaftaran Aplikasi Microsoft Entra yang dibuat sebelumnya.

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

Membuat Profil File dan Mesin

Seperti disebutkan, profil dan objek mesin diperlukan untuk klien SDK menggunakan API MIP. Lengkapi bagian pengkodean mulai cepat ini, dengan menambahkan kode untuk memuat DLL asli lalu membuat instans profil dan objek mesin.

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

Ganti nilai tempat penampung dalam kode sumber yang Anda tempelkan, menggunakan nilai berikut:

Placeholder	Nilai	Contoh
<application-id>	ID Aplikasi Microsoft Entra yang ditetapkan ke aplikasi yang terdaftar dalam "penyiapan dan konfigurasi MIP SDK" (2 instans).	0edbblll-8773-44de-b87c-b8c6276d41eb
<nama ramah>	Nama ramah yang ditentukan pengguna untuk aplikasi Anda.	AppInitialization
<Tenant-GUID>	ID Penyewa untuk penyewa Microsoft Entra Anda	IDPenyewa

Sekarang lakukan build akhir aplikasi dan atasi kesalahan apa pun. Kode Anda harus berhasil dibuat.

Langkah berikutnya

Setelah kode inisialisasi selesai, Anda siap untuk mulai cepat berikutnya, tempat Anda akan mulai mengalami SDK File MIP.

Mencantumkan label sensitivitas

Bagikan melalui

Mulai cepat: Inisialisasi aplikasi klien (C#)

Prasyarat

Membuat solusi dan proyek Visual Studio

Menerapkan delegasi autentikasi

Menginisialisasi Pembungkus Terkelola MIP SDK

Membuat Profil File dan Mesin

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Mulai cepat: Inisialisasi aplikasi klien (C#)

Prasyarat

Membuat solusi dan proyek Visual Studio

Menerapkan delegasi autentikasi

Menerapkan delegasi persetujuan

Menginisialisasi Pembungkus Terkelola MIP SDK

Membuat Profil File dan Mesin

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: