Tulis kode autentikasi aplikasi klien

Artikel
03/25/2023

Setelah Anda menyiapkan instans dan autentikasi Azure Digital Twins, Anda dapat membuat aplikasi klien yang akan Anda gunakan untuk berinteraksi dengan instans. Setelah Anda menyiapkan proyek klien pemula, Anda harus menulis kode di aplikasi klien tersebut untuk mengautentikasinya terhadap instans Azure Digital Twins.

Azure Digital Twins mengautentikasi menggunakan Token Keamanan Microsoft Entra berdasarkan OAUTH 2.0. Untuk mengautentikasi SDK, Anda harus mendapatkan token pembawa dengan izin yang tepat ke Azure Digital Twins, dan meneruskannya bersama dengan panggilan API.

Artikel ini menjelaskan cara mendapatkan kredensial menggunakan pustaka klien Azure.Identity. Meskipun artikel ini menunjukkan contoh kode dalam C#, seperti apa yang akan Anda tulis untuk .NET (C#) SDK, Anda dapat menggunakan versi Azure.Identity terlepas dari SDK apa yang Anda gunakan (untuk lebih lanjut tentang SDK yang tersedia untuk Azure Digital Twins, lihat API dan SDK Azure Digital Twins.

Prasyarat

Pertama, selesaikan langkah penyiapan di Menyiapkan instans dan autentikasi. Penyiapan ini akan memastikan Anda memiliki instans Azure Digital Twins dan pengguna Anda memiliki izin akses. Setelah penyiapan, Anda siap untuk menulis kode aplikasi klien.

Untuk melanjutkan, Anda memerlukan proyek aplikasi klien tempat Anda menulis kode. Jika Anda belum menyiapkan proyek aplikasi klien, buat proyek dasar dalam bahasa pilihan Anda untuk digunakan dengan tutorial ini.

Mengautentikasi menggunakan Azure.Identity

Azure.Identity adalah pustaka klien yang menyediakan beberapa metode perolehan kredensial yang dapat Anda gunakan untuk mendapatkan token pembawa dan mengautentikasi dengan SDK Anda. Meskipun artikel ini memberikan contoh dalam C#, Anda dapat melihat Azure.Identity untuk beberapa bahasa, termasuk...

Tiga metode perolehan kredensial yang umum di Azure.Identity adalah:

DefaultAzureCredential menyediakan alur autentikasi TokenCredential default untuk aplikasi yang akan diterapkan ke Azure, dan merupakan pilihan yang disarankan untuk pengembangan lokal. Itu juga dapat diaktifkan untuk mencoba dua metode lain yang direkomendasikan dalam artikel ini; itu membungkus ManagedIdentityCredential dan dapat mengakses InteractiveBrowserCredential dengan variabel konfigurasi.
ManagedIdentityCredential berfungsi dengan baik dalam kasus di mana Anda memerlukan identitas terkelola (MSI), dan merupakan kandidat yang baik untuk bekerja dengan Azure Functions dan menyebarkan ke layanan Azure.
InteractiveBrowserCredential ditujukan untuk aplikasi interaktif, dan dapat digunakan untuk membuat klien SDK yang diautentikasi.

Selebihnya dalam artikel ini menunjukkan cara menggunakannya dengan SDK .NET (C#).

Tambahkan Azure.Identity ke proyek .NET Anda

Untuk menyiapkan proyek .NET Anda untuk mengautentikasi dengan Azure.Identity, selesaikan langkah-langkah berikut:

Sertakan paket SDK Azure.DigitalTwins.Core dan paket Azure.Identity dalam proyek Anda. Bergantung pada alat pilihan Anda, Anda dapat menyertakan paket menggunakan manajer paket Visual Studio atau dotnet alat baris perintah.

Tambahkan berikut ini menggunakan pernyataan ke kode proyek Anda:

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

Berikutnya, tambahkan kode untuk mendapatkan info masuk menggunakan salah satu metode di Azure.Identity. Bagian berikut memberikan detail lebih lanjut tentang menggunakan masing-masing metode.

Metode DefaultAzureCredential

DefaultAzureCredential menyediakan alur autentikasi TokenCredential default untuk aplikasi yang akan diterapkan ke Azure, dan merupakan pilihan yang disarankan untuk pengembangan lokal.

Untuk menggunakan info masuk Azure default, Anda memerlukan URL instans Azure Digital Twins (petunjuk untuk menemukan).

Berikut adalah sampel kode untuk menambahkan DefaultAzureCredential ke proyek Anda:

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

Catatan

Saat ini ada masalah yang diketahui yang memengaruhi DefaultAzureCredential kelas pembungkus yang dapat mengakibatkan kesalahan saat mengautentikasi. Jika Anda mengalami masalah ini, Anda dapat mencoba membuat instans DefaultAzureCredential dengan parameter opsional berikut untuk mengatasinya: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

Untuk informasi selengkapnya tentang masalah ini, lihat Masalah umum Azure Digital Twins.

Siapkan kredensial Azure lokal

Dengan DefaultAzureCredential, sampel akan mencari kredensial di lingkungan lokal Anda, seperti masuk Azure di Azure CLI lokal atau di Visual Studio atau Visual Studio Code. Untuk alasan ini, Anda harus masuk ke Azure secara lokal melalui salah satu mekanisme ini untuk menyiapkan kredensial untuk sampel tersebut.

Jika Anda menggunakan Visual Studio atau Visual Studio Code untuk menjalankan sampel kode, pastikan Anda masuk ke editor tersebut dengan kredensial Azure yang sama dengan yang ingin Anda gunakan untuk mengakses instans Azure Digital Twins Anda. Jika Anda menggunakan jendela CLI lokal, jalankan az login perintah untuk masuk ke akun Azure Anda. Setelah ini, saat menjalankan sampel kode, Anda harus diautentikasi secara otomatis.

Metode ManagedIdentityCredential

Metode ManagedIdentityCredential berfungsi dengan baik jika Anda memerlukan identitas terkelola (MSI)—misalnya, saat mengautentikasi dengan Azure Functions.

Ini berarti Anda dapat menggunakan ManagedIdentityCredential dalam proyek yang sama dengan DefaultAzureCredential atau InteractiveBrowserCredential, untuk mengautentikasi bagian proyek yang berbeda.

Untuk menggunakan info masuk Azure default, Anda memerlukan URL instans Azure Digital Twins (petunjuk untuk menemukan). Anda mungkin membutuhkan pendaftaran aplikasi dan ID (klien) Aplikasi.

Dalam fungsi Azure, Anda dapat menggunakan info masuk identitas terkelola seperti ini:

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

Saat membuat kredensial, membiarkan parameter kosong seperti yang ditunjukkan di atas akan mengembalikan kredensial untuk identitas yang ditetapkan sistem aplikasi fungsi, jika memilikinya. Untuk menentukan identitas yang ditetapkan pengguna, berikan ID klien identitas yang ditetapkan pengguna ke dalam parameter .

Metode InteractiveBrowserCredential

Metode InteractiveBrowserCredential ditujukan untuk aplikasi interaktif dan akan menampilkan browser web untuk autentikasi. Anda dapat menggunakan ini sebagai ganti DefaultAzureCredential jika Anda memerlukan autentikasi interaktif.

Untuk menggunakan info masuk browser interaktif, Anda memerlukan pendaftaran aplikasi yang memiliki izin ke API Azure Digital Twins. Untuk langkah-langkah tentang cara menyiapkan pendaftaran aplikasi ini, lihat Membuat pendaftaran aplikasi dengan akses Azure Digital Twins. Setelah pendaftaran aplikasi disiapkan, Anda memerlukan...

Berikut adalah contoh kode untuk membuat klien SDK yang diautentikasi menggunakan 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);
        }
    }
}

Catatan

Meskipun Anda dapat menempatkan ID klien, ID penyewa, dan URL instans langsung ke dalam kode seperti yang ditunjukkan di atas, sebaiknya kode Anda mendapatkan nilai-nilai ini dari file konfigurasi atau variabel lingkungan.

Mengautentikasi Azure Functions

Bagian ini berisi beberapa pilihan konfigurasi penting dalam konteks mengautentikasi dengan Azure Functions. Pertama, Anda akan membaca variabel tingkat kelas yang disarankan dan kode autentikasi yang akan memungkinkan fungsi untuk mengakses Azure Digital Twins. Kemudian, Anda akan membaca tentang beberapa langkah konfigurasi akhir yang harus diselesaikan untuk fungsi Anda setelah kodenya dipublikasikan ke Azure.

Menulis kode aplikasi

Saat menulis fungsi Azure, pertimbangkan untuk menambahkan variabel dan kode ini ke fungsi Anda:

Kode untuk membaca URL layanan Azure Digital Twins sebagai variabel lingkungan atau pengaturan konfigurasi. Adalah praktik yang baik untuk membaca URL layanan dari pengaturan aplikasi/variabel lingkungan, daripada mengodekan keras dalam fungsi. Dalam fungsi Azure, kode untuk membaca variabel lingkungan mungkin terlihat seperti ini:
```
private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
```
Kemudian, setelah menerbitkan fungsi, Anda akan membuat dan mengatur nilai variabel lingkungan untuk dibaca kode ini. Untuk petunjuk tentang cara melakukan ini, langsung maju ke Mengonfigurasi pengaturan aplikasi.
Variabel statik untuk menahan instans HttpClient. HttpClient relatif mahal untuk dibuat, jadi Anda mungkin ingin membuatnya sekali dengan kode autentikasi untuk menghindari pembuatannya untuk setiap pemanggilan fungsi.
```
private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
```
Kredensial identitas terkelola. Buat info masuk identitas terkelola yang akan digunakan fungsi Anda untuk mengakses 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>");
```
Membiarkan parameter kosong seperti yang ditunjukkan di atas akan mengembalikan kredensial untuk identitas yang ditetapkan sistem aplikasi fungsi, jika memilikinya. Untuk menentukan identitas yang ditetapkan pengguna, berikan ID klien identitas yang ditetapkan pengguna ke dalam parameter .

Kemudian, setelah menerbitkan fungsi, Anda akan memastikan identitas fungsi memiliki izin untuk mengakses API Azure Digital Twins. Untuk petunjuk tentang cara melakukannya, langsung maju ke Menetapkan peran akses.

Variabel lokal DigitalTwinsClient. Tambahkan variabel di dalam fungsi Anda untuk menahan instans klien Azure Digital Twins Anda. Jangan membuat variabel ini statik di dalam kelas Anda.

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

Pemeriksaan null untuk adtInstanceUrl. Tambahkan pemeriksaan null dan kemudian bungkus logika fungsi Anda dalam blok coba/tangkap untuk menangkap pengecualian apa pun.

Setelah variabel ini ditambahkan ke fungsi, kode fungsi Anda mungkin terlihat seperti contoh berikut.

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

Setelah selesai dengan kode fungsi Anda, termasuk menambahkan autentikasi dan logika fungsi, terbitkan aplikasi ke Azure

Mengonfigurasi aplikasi yang diterbitkan

Terakhir, selesaikan langkah-langkah konfigurasi berikut untuk fungsi Azure yang dipublikasikan untuk memastikannya dapat mengakses instans Azure Digital Twins Anda.

Jalankan perintah berikut di Azure Cloud Shell atau Azure CLI lokal.

Catatan

Bagian ini harus diselesaikan oleh pengguna Azure yang memiliki izin untuk mengelola akses pengguna ke sumber daya Azure, termasuk memberikan dan mendelegasikan izin. Peran umum yang memenuhi persyaratan ini adalah Pemilik, Admin akun, atau kombinasi Kontributor dan Administrator Akses Pengguna. Untuk mengetahui informasi selengkapnya tentang persyaratan izin untuk peran Azure Digital Twins, lihat Menyiapkan instans dan autentikasi.

Menetapkan peran akses

Fungsi Azure mengharuskan token pembawa diteruskan ke fungsi Azure. Untuk memastikan bahwa token pembawa diteruskan, beri aplikasi fungsi peran Pemilik Data Azure Digital Twins untuk instans Azure Digital Twins Anda, yang akan memberi aplikasi fungsi izin untuk melakukan aktivitas data plane di instans tersebut.

Gunakan perintah berikut untuk membuat identitas yang dikelola sistem untuk fungsi Anda (jika fungsi sudah memilikinya, perintah ini akan mencetak detailnya). Perhatikan bidang principalId dalam output. Anda akan menggunakan ID ini untuk merujuk ke fungsi sehingga Anda dapat memberikannya izin pada langkah berikutnya.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```

Gunakan nilai principalId dalam perintah berikut untuk memberi fungsi peran Pemilik Data Azure Digital Twins untuk instans Azure Digital Twins Anda.

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

Mengonfigurasi pengaturan aplikasi

Selanjutnya, buat URL instans Azure Digital Twins Anda dapat diakses oleh fungsi Anda dengan mengatur variabel lingkungan untuk instans tersebut.

Tip

URL instans Azure Digital Twins dibuat dengan menambahkan https:// ke awal nama host instans Anda. Untuk melihat nama host, bersama dengan semua properti instans Anda, jalankan az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Perintah berikut mengatur variabel lingkungan untuk URL instans yang akan digunakan fungsi Anda setiap kali fungsi tersebut perlu mengakses instans.

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>"

Mengautentikasi di seluruh penyewa

Azure Digital Twins adalah layanan yang hanya mendukung satu penyewa Microsoft Entra: penyewa utama dari langganan tempat instans Azure Digital Twins berada.

Akibatnya, permintaan ke API Azure Digital Twins memerlukan perwakilan pengguna atau layanan yang merupakan bagian dari penyewa yang sama tempat instans Azure Digital Twins berada. Untuk mencegah pemindaian titik akhir Azure Digital Twins yang berbahaya, permintaan dengan token akses dari luar penyewa asal akan menampilkan pesan kesalahan "404 Sub-Domain tidak ditemukan". Kesalahan ini akan dikembalikan meskipun pengguna atau perwakilan layanan diberikan peran Pemilik Data Azure Digital Twins atau Pembaca Data Azure Digital Twins melalui kolaborasi Microsoft Entra B2B.

Jika Anda perlu mengakses instans Azure Digital Twins menggunakan perwakilan layanan atau akun pengguna milik penyewa berbeda dari instans, Anda dapat meminta setiap identitas gabungan dari penyewa lain meminta token dari Azure Digital Twins penyewa "rumah" instans.

Salah satu cara untuk melakukan ini adalah dengan perintah CLI berikut, di mana <home-tenant-ID> adalah ID penyewa Microsoft Entra yang berisi instans Azure Digital Twins:

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

Setelah meminta ini, identitas akan menerima token yang dikeluarkan untuk https://digitaltwins.azure.net sumber daya Microsoft Entra, yang memiliki klaim ID penyewa yang cocok dengan instans Azure Digital Twins. Menggunakan token ini dalam permintaan API atau dengan Azure.Identity kode Anda harus memungkinkan identitas federasi untuk mengakses sumber daya Azure Digital Twins.

Anda juga dapat menentukan penyewa rumah dalam opsi info masuk dalam kode Anda.

Contoh berikut menunjukkan cara mengatur nilai ID penyewa sampel untuk InteractiveBrowserTenantId dalam DefaultAzureCredential opsi:

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

Ada opsi serupa yang tersedia untuk menetapkan penyewa untuk autentikasi dengan Visual Studio dan Visual Studio Code. Untuk informasi selengkapnya tentang opsi yang tersedia, lihat Dokumentasi DefaultAzureCredentialOptions.

Metode info masuk lainnya

Jika skenario autentikasi yang disorot di atas tidak memenuhi kebutuhan aplikasi Anda, Anda dapat menjelajahi jenis autentikasi lain yang ditawarkan di platform identitas Microsoft. Dokumentasi untuk platform ini mencakup skenario autentikasi tambahan, yang diatur menurut jenis aplikasi.

Langkah berikutnya

Baca selengkapnya tentang cara kerja keamanan di Azure Digital Twins:

Keamanan untuk solusi Azure Digital Twins

Atau, setelah autentikasi disiapkan, lanjutkan ke pembuatan dan pengelolaan model di instans Anda:

Mengelola model DTDL

Bagikan melalui

Tulis kode autentikasi aplikasi klien

Prasyarat

Mengautentikasi menggunakan Azure.Identity

Tambahkan Azure.Identity ke proyek .NET Anda

Metode DefaultAzureCredential

Siapkan kredensial Azure lokal

Metode ManagedIdentityCredential

Metode InteractiveBrowserCredential

Mengautentikasi Azure Functions

Menulis kode aplikasi

Mengonfigurasi aplikasi yang diterbitkan

Menetapkan peran akses

Mengonfigurasi pengaturan aplikasi

Mengautentikasi di seluruh penyewa

Metode info masuk lainnya

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: