Udostępnij za pośrednictwem


Pisanie kodu uwierzytelniania aplikacji klienckiej

Po skonfigurowaniu wystąpienia Azure Digital Twins i uwierzytelnienia możesz utworzyć aplikację kliencką do interakcji z tym wystąpieniem. W tym artykule wyjaśniono, jak napisać kod w tej aplikacji klienckiej w celu uwierzytelnienia jej 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, pobierz token uwierzytelniający z odpowiednimi uprawnieniami dla usługi Azure Digital Twins i przekaż 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 można napisać 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. Konfiguracja ta zapewnia, że masz wystąpienie usługi Azure Digital Twins, a Twój użytkownik ma odpowiednie uprawnienia dostępu. Po zakończeniu tej konfiguracji możesz napisać kod aplikacji klienckiej.

Aby kontynuować, potrzebny jest 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 pozyskiwania poświadczeń, których można użyć do uzyskania tokenu uwierzytelniającego i uwierzytelnienia w zestawie SDK. Mimo że ten artykuł zawiera przykłady w języku C#, można zobaczyć przykłady w kilku innych językach, 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 wdrożonych na platformie Azure. Ta metoda jest zalecanym wyborem w przypadku programowania lokalnego. Jest również w stanie wypróbować pozostałe dwie metody zalecane w tym artykule; obejmuje ManagedIdentityCredential i może uzyskiwać dostęp za pomocą zmiennej konfiguracji InteractiveBrowserCredential.
  • Funkcja ManagedIdentityCredential działa dobrze w przypadkach, w których potrzebne są tożsamości zarządzane (MSI). Ta metoda jest dobrym kandydatem do pracy z usługą Azure Functions i wdrażania w usługach platformy Azure.
  • InteractiveBrowserCredential jest przeznaczony dla aplikacji interaktywnych. Jest to jedna z metod 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 .NET do uwierzytelniania z Azure.Identity, wykonaj następujące kroki:

  1. Uwzględnij pakiet Azure.DigitalTwins.Core SDK i pakiet Azure.Identity w projekcie. W zależności od wybranych narzędzi, można włączyć pakiety za pomocą menedżera pakietów Visual Studio lub narzędzia wiersza poleceń dotnet.

  2. 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żdej metody.

Metoda DefaultAzureCredential

Ustawienie domyślneAzureCredential zapewnia domyślny TokenCredential przepływ uwierzytelniania dla aplikacji wdrożonych na platformie Azure. Ta metoda 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, jak znaleźć).

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 znany problem wpływa na klasę wrapper DefaultAzureCredential, co 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 DefaultAzureCredentialpróbka wyszukuje poświadczenia w środowisku lokalnym, na przykład logowanie do platformy Azure w lokalnym interfejsie wiersza polecenia platformy Azure lub w programie Visual Studio czy Visual Studio Code. Z tego powodu należy zalogować się lokalnie do platformy Azure 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 zalogujesz się do tego edytora przy użyciu tych samych poświadczeń platformy Azure, których chcesz użyć do uzyskania dostępu do instancji Azure Digital Twins. Jeśli używasz lokalnego okna interfejsu wiersza polecenia, uruchom az login polecenie, aby zalogować się do konta Azure. Po zalogowaniu się po uruchomieniu przykładowego kodu powinno nastąpić automatyczne uwierzytelnienie.

Metoda ManagedIdentityCredential

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.

Można użyć ManagedIdentityCredential w tym samym projekcie co DefaultAzureCredential lub InteractiveBrowserCredential do uwierzytelniania innej części projektu.

Aby użyć domyślnych poświadczeń platformy Azure, potrzebny jest adres URL wystąpienia usługi Azure Digital Twins (instrukcje, jak znaleźć). 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);
        }
    }
}

Kiedy tworzysz poświadczenia bez parametrów, jak pokazano w poprzednim przykładzie, zwracane są poświadczenia tożsamości przypisanej przez system dla aplikacji funkcji, jeśli ją ma. Aby zamiast tego określić tożsamość przypisaną przez użytkownika, przekaż identyfikator klienta przypisanego przez użytkownika do parametru id konstruktora.

Metoda InteractiveBrowserCredential

Metoda InteractiveBrowserCredential jest przeznaczona dla aplikacji interaktywnych i wywołuje przeglądarkę internetową do uwierzytelniania. Użyj tej metody zamiast DefaultAzureCredential , gdy wymagane jest uwierzytelnianie interakcyjne.

Aby użyć poświadczeń przeglądarki interaktywnej, 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 potrzebne są następujące wartości:

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

Mimo że powyższy przykład umieszcza identyfikator klienta, identyfikator dzierżawy i adres URL wystąpienia bezpośrednio w kodzie, dobrym pomysłem jest pobranie tych wartości z pliku konfiguracji lub zmiennej środowiskowej.

Uwierzytelnianie usługi Azure Functions

Ta sekcja zawiera ważne opcje konfiguracji uwierzytelniania za pomocą usługi Azure Functions. Najpierw przeczytaj o zalecanych zmiennych na poziomie klasy i kodzie uwierzytelniania, które umożliwiają funkcji dostęp do usługi Azure Digital Twins. Następnie zapoznasz się z pewnymi ostatnimi 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 ustawienia aplikacji lub zmiennej środowiskowej, 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 utwórz i ustaw wartość zmiennej środowiskowej dla tego kodu do odczytania. Aby uzyskać instrukcje dotyczące tego, jak to zrobić, zobacz Konfigurowanie ustawień aplikacji.

  • Zmienna statyczna do przechowywania wystąpienia HttpClient. Tworzenie HttpClient jest stosunkowo kosztowne, więc prawdopodobnie chcesz go utworzyć raz wraz z kodem uwierzytelniania, aby uniknąć tworzenia go przy każdym wywołaniu funkcji.

    private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
    
  • Poświadczenie zarządzanej tożsamości. Utwórz poświadczenia tożsamości zarządzanej używane przez funkcję do uzyskiwania 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>");
    

    Kiedy tworzysz poświadczenia bez parametrów, jak pokazano w poprzednim przykładzie, zwracane są poświadczenia tożsamości przypisanej przez system dla aplikacji funkcji, jeśli ją ma. Aby zamiast tego określić tożsamość przypisaną przez użytkownika, przekaż identyfikator klienta przypisanego przez użytkownika do parametru id konstruktora.

    Później, po opublikowaniu funkcji, upewnij się, że uprawnienia tożsamości funkcji pozwalają na dostęp do interfejsów API Azure Digital Twins. Aby uzyskać instrukcje dotyczące tego, jak to zrobić, zobacz Przypisywanie roli dostępu.

  • Zmienna lokalna DigitalTwinsClient. Dodaj zmienną do funkcji w celu przechowywania wystąpienia 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. Aby przechwycić wszelkie wyjątki, dodaj sprawdzanie wartości null, a następnie umieść logikę funkcji w bloku try/catch.

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 dodaniu uwierzytelniania i logiki funkcji, opublikuj aplikację na platformie Azure.

Konfigurowanie opublikowanej aplikacji

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

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

Uwaga

Użytkownik 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ń, musi wykonać tę sekcję. 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 Azure wymaga przekazania do niej tokenu nosiciela. Aby upewnić się, że token nosiciela jest przekazywany, przyznaj aplikacji funkcji rolę Właściciela danych usługi Azure Digital Twins dla wystąpienia usługi Azure Digital Twins, która daje aplikacji funkcji pozwolenie na wykonywanie operacji na warstwie danych w wystąpieniu.

  1. 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świetla jego szczegóły). Zwróć uwagę na pole principalId w wynikach. 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>	
    
  2. Użyj wartości principalId w poniższym poleceniu, aby nadać funkcji rolę Właściciela danych dla wystąpienia 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, aby uczynić adres URL wystąpienia usługi Azure Digital Twins dostępnym dla twojej funkcji, ustaw dla niego zmienną środowiskową.

Napiwek

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

Następujące polecenie ustawia zmienną środowiskową dla adresu URL Twojego wystąpienia, z którego korzysta funkcja, gdy musi uzyskać dostęp do tego 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 między dzierżawcami

Azure Digital Twins to usługa, która obsługuje tylko jednego dzierżawcę Microsoft Entra: głównego dzierżawcę 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 podmiotu usługi będącego częścią tej samej dzierżawy, w której znajduje się instancja. 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 zwracają komunikat o błędzie "404 Sub-Domain nie znaleziono". Ten błąd jest zwracany, nawet jeśli użytkownik lub podmiot usługi otrzymał rolę właściciela danych Azure Digital Twins lub czytelnika danych Azure Digital Twins poprzez współpracęfirmy Microsoft Entra B2B.

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

Jednym ze sposobów wykonania tej czynności jest użycie następującego polecenia CLI, gdzie <home-tenant-ID> jest identyfikatorem dzierżawy 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 tym żądaniu tożsamość otrzymuje token wystawiony dla zasobu Microsoft Entra https://digitaltwins.azure.net, który ma pasujące oświadczenie dotyczące identyfikatora dzierżawy z instancją usługi Azure Digital Twins. Użycie tego tokenu w żądaniach interfejsu API lub w kodzie Azure.Identity powinno umożliwić tożsamości federacyjnej uzyskanie dostępu do zasobu usługi Azure Digital Twins.

Możesz również określić głównego użytkownika w opcjach poświadczeń w swoim kodzie.

W poniższym przykładzie pokazano, jak ustawić przykładową wartość identyfikatora dzierżawcy dla opcji InteractiveBrowserTenantId w 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 konfigurowania dzierżawcy do 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 wyróżnione scenariusze uwierzytelniania opisane w tym artykule nie obejmują potrzeb aplikacji, zapoznaj się z innymi typami uwierzytelniania oferowanymi na platformie tożsamości firmy Microsoft. Dokumentacja tej platformy obejmuje więcej scenariuszy uwierzytelniania zorganizowanych według typu aplikacji.

Następne kroki

Aby dowiedzieć się więcej o sposobie działania zabezpieczeń w usłudze Azure Digital Twins, zobacz:

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