Pisanie kodu uwierzytelniania aplikacji klienckiej

Artykuł
10/27/2023

Po skonfigurowaniu wystąpienia i uwierzytelniania usługi Azure Digital Twins możesz utworzyć aplikację kliencką, która będzie używana do interakcji z wystąpieniem. Po skonfigurowaniu projektu klienta początkowego należy napisać kod w tej aplikacji klienckiej, aby uwierzytelnić go w wystąpieniu usługi Azure Digital Twins.

Usługa Azure Digital Twins uwierzytelnia się przy użyciu tokenów zabezpieczających firmy Microsoft w oparciu o protokół OAUTH 2.0. Aby uwierzytelnić zestaw SDK, musisz uzyskać token elementu nośnego z odpowiednimi uprawnieniami do usługi Azure Digital Twins i przekazać go wraz z wywołaniami interfejsu API.

W tym artykule opisano sposób uzyskiwania poświadczeń przy użyciu Azure.Identity biblioteki klienta. Chociaż w tym artykule przedstawiono przykłady kodu w języku C#, takie jak to, co piszesz dla zestawu SDK platformy .NET (C#), możesz użyć wersji Azure.Identity niezależnie od używanego zestawu SDK (aby uzyskać więcej informacji na temat zestawów SDK dostępnych dla usługi Azure Digital Twins, zobacz Interfejsy API i zestawy SDK usługi Azure Digital Twins.

Wymagania wstępne

Najpierw wykonaj kroki konfiguracji opisane w temacie Konfigurowanie wystąpienia i uwierzytelniania. Ta konfiguracja zapewni, że masz wystąpienie usługi Azure Digital Twins, a użytkownik ma uprawnienia dostępu. Po zakończeniu tej konfiguracji możesz napisać kod aplikacji klienckiej.

Aby kontynuować, musisz mieć projekt aplikacji klienckiej, w którym piszesz kod. Jeśli nie masz jeszcze skonfigurowanego projektu aplikacji klienckiej, utwórz podstawowy projekt w wybranym języku do użycia z tym samouczkiem.

Uwierzytelnianie przy użyciu biblioteki Azure.Identity

Azure.Identity to biblioteka kliencka, która udostępnia kilka metod uzyskiwania poświadczeń, których można użyć do uzyskania tokenu elementu nośnego i uwierzytelnienia za pomocą zestawu SDK. Mimo że ten artykuł zawiera przykłady w języku C#, można wyświetlić Azure.Identity kilka języków, w tym...

Trzy typowe metody uzyskiwania poświadczeń w programie Azure.Identity to:

Ustawienie domyślneAzureCredential zapewnia domyślny TokenCredential przepływ uwierzytelniania dla aplikacji, które zostaną wdrożone na platformie Azure i jest zalecanym wyborem w przypadku programowania lokalnego. Można ją również włączyć, aby wypróbować pozostałe dwie metody zalecane w tym artykule; opakowuje ManagedIdentityCredential i może uzyskiwać dostęp za InteractiveBrowserCredential pomocą zmiennej konfiguracji.
Funkcja ManagedIdentityCredential działa dobrze w przypadkach, w których potrzebujesz tożsamości zarządzanych (MSI) i jest dobrym kandydatem do pracy z usługą Azure Functions i wdrażania w usługach platformy Azure.
InteractiveBrowserCredential jest przeznaczony dla aplikacji interaktywnych i może służyć do tworzenia uwierzytelnionego klienta zestawu SDK.

W pozostałej części tego artykułu pokazano, jak używać tych metod z zestawem SDK platformy .NET (C#).

Dodawanie usługi Azure.Identity do projektu platformy .NET

Aby skonfigurować projekt platformy .NET do uwierzytelniania Azure.Identityw programie , wykonaj następujące kroki:

Uwzględnij pakiet Azure.DigitalTwins.Core ZESTAWU SDK i Azure.Identity pakiet w projekcie. W zależności od wybranego narzędzia można uwzględnić pakiety przy użyciu menedżera pakietów programu Visual Studio lub dotnet narzędzia wiersza polecenia.

Dodaj następujące instrukcje using do kodu projektu:

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

Następnie dodaj kod w celu uzyskania poświadczeń przy użyciu jednej z metod w pliku Azure.Identity. Poniższe sekcje zawierają więcej szczegółowych informacji na temat korzystania z każdego z nich.

DefaultAzureCredential, metoda

Ustawienie domyślneAzureCredential zapewnia domyślny TokenCredential przepływ uwierzytelniania dla aplikacji, które zostaną wdrożone na platformie Azure i jest zalecanym wyborem w przypadku programowania lokalnego.

Aby użyć domyślnych poświadczeń platformy Azure, potrzebny jest adres URL wystąpienia usługi Azure Digital Twins (instrukcje do znalezienia).

Oto przykładowy kod umożliwiający dodanie elementu DefaultAzureCredential do projektu:

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

Uwaga

Obecnie występuje znany problem dotyczący DefaultAzureCredential klasy otoki, który może spowodować błąd podczas uwierzytelniania. Jeśli wystąpi ten problem, możesz spróbować utworzyć wystąpienie DefaultAzureCredential za pomocą następującego opcjonalnego parametru, aby rozwiązać ten problem: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

Aby uzyskać więcej informacji na temat tego problemu, zobacz Znane problemy usługi Azure Digital Twins.

Konfigurowanie lokalnych poświadczeń platformy Azure

W programie DefaultAzureCredentialprzykład wyszuka poświadczenia w środowisku lokalnym, takie jak logowanie się platformy Azure w lokalnym interfejsie wiersza polecenia platformy Azure lub w programie Visual Studio lub Visual Studio Code. Z tego powodu należy zalogować się do platformy Azure lokalnie za pomocą jednego z tych mechanizmów, aby skonfigurować poświadczenia dla przykładu.

Jeśli używasz programu Visual Studio lub Visual Studio Code do uruchamiania przykładów kodu, upewnij się, że zalogowaliśmy się do tego edytora przy użyciu tych samych poświadczeń platformy Azure, których chcesz użyć do uzyskania dostępu do wystąpienia usługi Azure Digital Twins. Jeśli używasz lokalnego okna interfejsu wiersza polecenia, uruchom az login polecenie , aby zalogować się do konta platformy Azure. Następnie po uruchomieniu przykładowego kodu powinno nastąpić automatyczne uwierzytelnienie.

ManagedIdentityCredential, metoda

Metoda ManagedIdentityCredential działa dobrze w przypadkach, w których potrzebne są tożsamości zarządzane (MSI) — na przykład podczas uwierzytelniania za pomocą usługi Azure Functions.

Oznacza to, że można użyć ManagedIdentityCredential w tym samym projekcie co DefaultAzureCredential lub InteractiveBrowserCredential, aby uwierzytelnić inną część projektu.

Aby użyć domyślnych poświadczeń platformy Azure, potrzebny jest adres URL wystąpienia usługi Azure Digital Twins (instrukcje do znalezienia). Może być również konieczne zarejestrowanie aplikacji i identyfikator aplikacji (klienta) rejestracji.

W funkcji platformy Azure możesz użyć poświadczeń tożsamości zarządzanej w następujący sposób:

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

Podczas tworzenia poświadczeń pozostawienie parametru pustego, jak pokazano powyżej, spowoduje zwrócenie poświadczeń tożsamości przypisanej przez system aplikacji funkcji, jeśli ma jeden. Aby określić tożsamość przypisaną przez użytkownika, należy przekazać identyfikator klienta tożsamości przypisanej przez użytkownika do parametru .

InteractiveBrowserCredential, metoda

Metoda InteractiveBrowserCredential jest przeznaczona dla aplikacji interaktywnych i wyświetli przeglądarkę internetową do uwierzytelniania. Tej metody można użyć zamiast DefaultAzureCredential w przypadkach, w których wymagane jest uwierzytelnianie interakcyjne.

Aby korzystać z poświadczeń przeglądarki interakcyjnej, potrzebna jest rejestracja aplikacji z uprawnieniami do interfejsów API usługi Azure Digital Twins. Aby uzyskać instrukcje dotyczące konfigurowania tej rejestracji aplikacji, zobacz Tworzenie rejestracji aplikacji przy użyciu dostępu do usługi Azure Digital Twins. Po skonfigurowaniu rejestracji aplikacji będziesz potrzebować...

Oto przykład kodu służącego do tworzenia uwierzytelnionego klienta zestawu SDK przy użyciu polecenia 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);
        }
    }
}

Uwaga

Chociaż identyfikator klienta, identyfikator dzierżawy i adres URL wystąpienia można umieścić bezpośrednio w kodzie, jak pokazano powyżej, dobrym pomysłem jest pobranie tych wartości z pliku konfiguracji lub zmiennej środowiskowej.

Uwierzytelnianie usługi Azure Functions

Ta sekcja zawiera niektóre ważne opcje konfiguracji w kontekście uwierzytelniania za pomocą usługi Azure Functions. Najpierw zapoznasz się z zalecanymi zmiennymi na poziomie klasy i kodem uwierzytelniania, który umożliwi funkcji dostęp do usługi Azure Digital Twins. Następnie zapoznasz się z pewnymi końcowymi krokami konfiguracji, które należy wykonać dla funkcji po opublikowaniu jej kodu na platformie Azure.

Pisanie kodu aplikacji

Podczas pisania funkcji platformy Azure rozważ dodanie tych zmiennych i kodu do funkcji:

Kod służący do odczytywania adresu URL usługi Azure Digital Twins jako zmiennej środowiskowej lub ustawienia konfiguracji. Dobrym rozwiązaniem jest odczytanie adresu URL usługi z zmiennej środowiskowej/ustawienia aplikacji, zamiast kodowania go na stałe w funkcji. W funkcji platformy Azure kod odczytujący zmienną środowiskową może wyglądać następująco:
```
private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
```
Później po opublikowaniu funkcji utworzysz i ustawisz wartość zmiennej środowiskowej dla tego kodu do odczytania. Aby uzyskać instrukcje dotyczące tego, jak to zrobić, przejdź do sekcji Konfigurowanie ustawień aplikacji.
Zmienna statyczna do przechowywania wystąpienia httpClient. Klient HttpClient jest stosunkowo kosztowny do utworzenia, więc prawdopodobnie zechcesz utworzyć go raz przy użyciu kodu uwierzytelniania, aby uniknąć tworzenia go dla każdej wywołania funkcji.
```
private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
```
Poświadczenia tożsamości zarządzanej. Utwórz poświadczenie tożsamości zarządzanej, które będzie używane przez funkcję w celu uzyskania dostępu do usługi 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>");
```
Pozostawienie pustego parametru, jak pokazano powyżej, spowoduje zwrócenie poświadczeń tożsamości przypisanej przez system aplikacji funkcji, jeśli ma ten parametr. Aby określić tożsamość przypisaną przez użytkownika, należy przekazać identyfikator klienta tożsamości przypisanej przez użytkownika do parametru .

Później po opublikowaniu funkcji upewnij się, że tożsamość funkcji ma uprawnienia dostępu do interfejsów API usługi Azure Digital Twins. Aby uzyskać instrukcje dotyczące tego, jak to zrobić, przejdź do sekcji Przypisywanie roli dostępu.
Zmienna lokalna DigitalTwinsClient. Dodaj zmienną wewnątrz funkcji, aby przechowywać wystąpienie klienta usługi Azure Digital Twins. Nie należy określać tej zmiennej jako statycznej wewnątrz klasy.
```
var client = new DigitalTwinsClient(
    new Uri(adtInstanceUrl),
    cred,
    new DigitalTwinsClientOptions
    {
        Transport = new HttpClientTransport(singletonHttpClientInstance)
    });
```
Sprawdzanie wartości null dla elementu adtInstanceUrl. Dodaj sprawdzanie wartości null, a następnie zawijaj logikę funkcji w bloku try/catch, aby przechwycić wszelkie wyjątki.

Po dodaniu tych zmiennych do funkcji kod funkcji może wyglądać podobnie do poniższego przykładu.

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

Po zakończeniu pracy z kodem funkcji, w tym do dodawania uwierzytelniania i logiki funkcji, opublikuj aplikację na platformie Azure

Konfigurowanie opublikowanej aplikacji

Na koniec wykonaj następujące kroki konfiguracji opublikowanej funkcji platformy Azure, aby upewnić się, że może uzyskać dostęp do wystąpienia usługi Azure Digital Twins.

Uruchom następujące polecenia w usłudze Azure Cloud Shell lub lokalnym interfejsie wiersza polecenia platformy Azure.

Uwaga

Ta sekcja musi zostać ukończona przez użytkownika platformy Azure, który ma uprawnienia do zarządzania dostępem użytkowników do zasobów platformy Azure, w tym udzielania i delegowania uprawnień. Typowe role spełniające to wymaganie to Właściciel, Administrator konta lub Kombinacja administratorów dostępu użytkowników i Współautor. Aby uzyskać więcej informacji na temat wymagań dotyczących uprawnień dla ról usługi Azure Digital Twins, zobacz Konfigurowanie wystąpienia i uwierzytelniania.

Przypisywanie roli dostępu

Funkcja platformy Azure wymaga przekazania do niego tokenu elementu nośnego. Aby upewnić się, że token elementu nośnego został przekazany, przyznaj aplikacji funkcji rolę Właściciela danych usługi Azure Digital Twins dla wystąpienia usługi Azure Digital Twins, która da aplikacji funkcji uprawnienie do wykonywania działań płaszczyzny danych w wystąpieniu.

Użyj następującego polecenia, aby utworzyć tożsamość zarządzaną przez system dla funkcji (jeśli funkcja ma już tę funkcję , to polecenie wyświetli jego szczegóły). Zanotuj principalId pole w danych wyjściowych. Użyjesz tego identyfikatora, aby odwołać się do funkcji, aby można było udzielić jej uprawnień w następnym kroku.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
principalId Użyj wartości w poniższym poleceniu, aby nadać funkcji rolę Właściciela danych usługi Azure Digital Twins dla wystąpienia usługi Azure Digital Twins.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

Konfigurowanie ustawień aplikacji

Następnie ustaw dla niej adres URL wystąpienia usługi Azure Digital Twins, ustawiając dla niego zmienną środowiskową.

Napiwek

Adres URL wystąpienia usługi Azure Digital Twins jest wprowadzany przez dodanie https:// na początku nazwy hosta wystąpienia. Aby wyświetlić nazwę hosta wraz ze wszystkimi właściwościami wystąpienia, uruchom polecenie az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Następujące polecenie ustawia zmienną środowiskową dla adresu URL wystąpienia, którego będzie używać funkcja zawsze, gdy będzie ona potrzebna do uzyskania dostępu do wystąpienia.

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

Uwierzytelnianie w wielu dzierżawach

Azure Digital Twins to usługa, która obsługuje tylko jedną dzierżawę firmy Microsoft Entra: główną dzierżawę z subskrypcji, w której znajduje się wystąpienie usługi Azure Digital Twins.

W związku z tym żądania do interfejsów API usługi Azure Digital Twins wymagają użytkownika lub jednostki usługi będącej częścią tej samej dzierżawy, w której znajduje się wystąpienie usługi Azure Digital Twins. Aby zapobiec złośliwemu skanowaniu punktów końcowych usługi Azure Digital Twins, żądania z tokenami dostępu spoza dzierżawy źródłowej zostaną zwrócone komunikat o błędzie "Nie znaleziono domeny podrzędnej 404". Ten błąd zostanie zwrócony, nawet jeśli użytkownik lub jednostka usługi otrzymał rolę właściciela danych usługi Azure Digital Twins lub czytelnika danych usługi Azure Digital Twins za pośrednictwem współpracy firmy Microsoft Entra B2B.

Jeśli musisz uzyskać dostęp do wystąpienia usługi Azure Digital Twins przy użyciu jednostki usługi lub konta użytkownika należącego do innej dzierżawy niż wystąpienie, możesz mieć każdą tożsamość federacyjną z innej dzierżawy zażądać tokenu z dzierżawy "domu" wystąpienia usługi Azure Digital Twins.

Jednym ze sposobów wykonania tej czynności jest użycie następującego polecenia interfejsu wiersza polecenia, gdzie <home-tenant-ID> jest identyfikatorem dzierżawy firmy Microsoft Entra, która zawiera wystąpienie usługi Azure Digital Twins:

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

Po zażądaniu tej tożsamości otrzyma token wystawiony dla https://digitaltwins.azure.net zasobu Microsoft Entra, który ma zgodne oświadczenie identyfikatora dzierżawy do wystąpienia usługi Azure Digital Twins. Użycie tego tokenu w żądaniach interfejsu API lub kodu Azure.Identity powinno umożliwić tożsamości federacyjnej dostęp do zasobu usługi Azure Digital Twins.

Dzierżawę główną można również określić w opcjach poświadczeń w kodzie.

W poniższym przykładzie pokazano, jak ustawić przykładową wartość InteractiveBrowserTenantId identyfikatora dzierżawy dla opcji 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);
}

Dostępne są podobne opcje ustawiania dzierżawy na potrzeby uwierzytelniania w programach Visual Studio i Visual Studio Code. Aby uzyskać więcej informacji na temat dostępnych opcji, zobacz dokumentację DefaultAzureCredentialOptions.

Inne metody poświadczeń

Jeśli powyższe wyróżnione scenariusze uwierzytelniania nie obejmują potrzeb aplikacji, możesz zapoznać się z innymi typami uwierzytelniania oferowanymi w Platforma tożsamości Microsoft. Dokumentacja tej platformy obejmuje więcej scenariuszy uwierzytelniania zorganizowanych według typu aplikacji.

Następne kroki

Dowiedz się więcej o sposobie działania zabezpieczeń w usłudze Azure Digital Twins:

Zabezpieczenia rozwiązań usługi Azure Digital Twins

Lub teraz, gdy uwierzytelnianie jest skonfigurowane, przejdź do tworzenia modeli i zarządzania nimi w twoim wystąpieniu:

Zarządzanie modelami DTDL

Udostępnij za pośrednictwem

Pisanie kodu uwierzytelniania aplikacji klienckiej

Wymagania wstępne

Uwierzytelnianie przy użyciu biblioteki Azure.Identity

Dodawanie usługi Azure.Identity do projektu platformy .NET

DefaultAzureCredential, metoda

Konfigurowanie lokalnych poświadczeń platformy Azure

ManagedIdentityCredential, metoda

InteractiveBrowserCredential, metoda

Uwierzytelnianie usługi Azure Functions

Pisanie kodu aplikacji

Konfigurowanie opublikowanej aplikacji

Przypisywanie roli dostępu

Konfigurowanie ustawień aplikacji

Uwierzytelnianie w wielu dzierżawach

Inne metody poświadczeń

Następne kroki

Opinia

Dodatkowe zasoby