Schreiben von Authentifizierungscode für die Client-App

Nachdem Sie eine Azure Digital Twins-Instanz und -Authentifizierung eingerichtet haben, können Sie eine Clientanwendung erstellen, die Ihnen die Interaktion mit der Instanz ermöglicht. Nachdem Sie ein Clientstartprojekt eingerichtet haben, müssen Sie Code in dieser Client-App schreiben, um die App für die Azure Digital Twins-Instanz zu authentifizieren.

Azure Digital Twins führt die Authentifizierung mithilfe von Microsoft Entra-Sicherheitstoken basierend auf OAUTH 2.0 aus. Zum Authentifizieren Ihres SDK müssen Sie ein Bearertoken mit den richtigen Berechtigungen für Azure Digital Twins abrufen und es zusammen mit ihren API-Aufrufen übergeben.

In diesem Artikel wird beschrieben, wie Sie mithilfe der Azure.Identity-Clientbibliothek Anmeldeinformationen abrufen. Dieser Artikel zeigt Codebeispiele in C#, z. B. für das .NET (C#) SDK. Sie können jedoch unabhängig vom verwendeten SDK eine Version von Azure.Identity verwenden (weitere Informationen zu den für Azure Digital Twins verfügbaren SDKs finden Sie unter Azure Digital Twins-APIs und SDKs.

Voraussetzungen

Führen Sie zunächst die Einrichtungsschritte unter Einrichten von Instanzen und Authentifizierung aus. Durch diese Einrichtung wird sichergestellt, dass Sie über eine Azure Digital Twins-Instanz verfügen und der Benutzer Zugriffsberechtigungen besitzt. Nachdem Sie diese Einrichtung abgeschlossen haben, können Sie Client-App-Code schreiben.

Als Nächstes benötigen Sie ein Client-App-Projekt, in dem Sie den Code schreiben. Wenn Sie nicht bereits ein Client-App-Projekt eingerichtet haben, erstellen Sie ein einfaches Projekt in der Sprache Ihrer Wahl zur Verwendung in diesem Tutorial.

Authentifizieren mit der Azure.Identity-Bibliothek

Azure.Identity ist eine Clientbibliothek, die mehrere Methoden zum Abrufen von Anmeldeinformationen bereitstellt, die Sie verwenden können, um ein Bearertoken abzurufen und sich mit Ihrem SDK zu authentifizieren. Obwohl in diesem Artikel Beispiele in C# aufgeführt werden, können Sie Azure.Identity für verschiedene Sprachen anzeigen, beispielsweise...

• .NET (C#)
• Java
• JavaScript
• Python

In Azure.Identity gibt es drei gängige Methoden zum Abrufen von Anmeldeinformationen:

• DefaultAzureCredential stellt einen TokenCredential-Standardauthentifizierungsfluss für Anwendungen bereit, die in Azure bereitgestellt werden, und ist die empfohlene Wahl für lokale Entwicklung. Außerdem kann DefaultAzureCredential aktiviert werden, um die beiden anderen Methoden zu testen, die in diesem Artikel empfohlen werden. DefaultAzureCredential dient als Wrapper für ManagedIdentityCredential und kann mit einer Konfigurationsvariablen auf InteractiveBrowserCredential zugreifen.
• ManagedIdentityCredential funktioniert gut in Fällen, in denen Sie verwaltete Identitäten (MSI) benötigen, und eignet sich gut für das Arbeiten mit Azure Funktionen und Bereitstellungen in Azure-Diensten.
• InteractiveBrowserCredential ist für interaktive Anwendungen vorgesehen und kann zum Erstellen eines authentifizierten SDK-Clients verwendet werden.

Im restlichen Artikel wird gezeigt, wie Sie diese Methoden mit dem .NET SDK (C#) verwenden.

Hinzufügen von Azure.Identity zu Ihrem .NET-Projekt

Führen Sie die folgenden Schritte aus, um Ihr .NET-Projekt für Authentifizierung mit Azure.Identity einzurichten:

1. Binden Sie das SDK-Paket Azure.DigitalTwins.Core und das Azure.Identity-Paket in Ihr Projekt ein. Je nachdem, welche Tools Sie verwenden, können Sie die Pakete mit dem Visual Studio-Paket-Manager oder mit dem Befehlszeilentool dotnet einbinden.

2. Fügen Sie dem Projektcode folgende using-Anweisungen hinzu:

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

Fügen Sie dann Code zum Abrufen von Anmeldeinformationen mithilfe einer der Methoden in Azure.Identity hinzu. In den folgenden Abschnitten finden Sie weitere Informationen zur Verwendung der einzelnen Methoden.

DefaultAzureCredential-Methode

DefaultAzureCredential stellt einen TokenCredential-Standardauthentifizierungsfluss für Anwendungen bereit, die in Azure bereitgestellt werden, und ist die empfohlene Wahl für lokale Entwicklung.

Wenn Sie die standardmäßigen Azure-Anmeldeinformationen verwenden möchten, benötigen Sie die URL der Azure Digital Twins-Instanz (Anweisungen für die Ermittlung).

Das folgende Codebeispiel fügt Ihrem Projekt DefaultAzureCredential hinzu:

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

Einrichten lokaler Azure-Anmeldeinformationen

Mit DefaultAzureCredential sucht das Beispiel nach Anmeldeinformationen in Ihrer lokalen Umgebung, wie eine Azure-Anmeldung in einer lokalen DefaultAzureCredential oder in Visual Studio oder Visual Studio Code. Aus diesem Grund sollten Sie sich lokal über einen dieser Mechanismen bei Azure anmelden, um Anmeldeinformationen für das Beispiel einzurichten.

Wenn Sie Visual Studio oder Visual Studio Code zum Ausführen von Codebeispielen verwenden, stellen Sie sicher, dass Sie bei diesem Editor mit denselben Anmeldeinformationen für Azure angemeldet sind, die Sie für den Zugriff auf Ihre Instanz von Azure Digital Twins verwenden möchten. Wenn Sie ein lokales CLI-Fenster verwenden, führen Sie den Befehl az login aus, um sich bei Ihrem Azure-Konto anzumelden. Wenn Sie danach Ihr Codebeispiel ausführen, sollten Sie automatisch authentifiziert werden.

ManagedIdentityCredential-Methode

Die ManagedIdentityCredential-Methode funktioniert gut in Fällen, in denen verwaltete Identitäten (MSI) benötigt werden, beispielsweise bei der Authentifizierung mit Azure Funktionen.

Dies bedeutet, dass Sie ManagedIdentityCredential im selben Projekt wie DefaultAzureCredential oder InteractiveBrowserCredential verwenden können, um einen anderen Teil des Projekts zu authentifizieren.

Wenn Sie die standardmäßigen Azure-Anmeldeinformationen verwenden möchten, benötigen Sie die URL der Azure Digital Twins-Instanz (Anweisungen für die Ermittlung). Möglicherweise benötigen Sie auch eine App-Registrierung und die Anwendungs-ID (Client-ID) der Registrierung.

Sie können die Anmeldeinformationen für die verwaltete Identität wie folgt in einer Azure-Funktion verwenden:

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

Beim Erstellen der Anmeldeinformationen gibt der Parameter leer wie oben dargestellt die Anmeldeinformationen für die vom System zugewiesene Identität der Funktions-App zurück, sofern er über eine verfügt. Um stattdessen eine vom Benutzer zugewiesene Identität anzugeben, übergeben Sie die Client-ID der vom Benutzer zugewiesenen Identität an den Parameter.

InteractiveBrowserCredential-Methode

Die InteractiveBrowserCredential-Methode ist für interaktive Anwendungen gedacht und startet einen Webbrowser für die Authentifizierung. Sie können diese Methode anstelle von DefaultAzureCredential in Fällen verwenden, in denen Sie interaktive Authentifizierung benötigen.

Wenn Sie die interaktiven Browseranmeldeinformationen verwenden möchten, benötigen Sie eine App-Registrierung, die über Berechtigungen für die Azure Digital Twins-APIs verfügt. Schritte zum Einrichten dieser App-Registrierung finden Sie unter Erstellen einer App-Registrierung für die Verwendung mit Azure Digital Twins (Portal). Nachdem Sie die App-Registrierung eingerichtet haben, benötigen Sie Folgendes...

• Die Anwendungs-ID (Client-ID) der App-Registrierung
• Die Verzeichnis-ID (Mandanten-ID) der App-Registrierung
• Die URL der Azure Digital Twins-Instanz

Im Folgenden finden Sie ein Beispiel für den Code zum Erstellen eines authentifizierten SDK-Clients mit 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);
        }
    }
}

Authentifizieren mit Azure Functions

Dieser Abschnitt enthält einige wichtige Konfigurationsoptionen im Zusammenhang mit Authentifizierung mit Azure Functions. Zunächst erfahren Sie mehr über empfohlene Variablen auf Klassenebene und Authentifizierungscode, der der Funktion den Zugriff auf Azure Digital Twins ermöglicht. Anschließend erfahren Sie mehr über einige abschließende Konfigurationsschritte für Ihre Funktion, nachdem ihr Code in Azure veröffentlicht wurde.

Schreiben von Anwendungscode

Wenn Sie die Azure-Funktion schreiben, sollten Sie ihrer Funktion diese Variablen und den folgenden Code hinzufügen:

• Code zum Lesen der Dienst-URL für Azure Digital Twins als Umgebungsvariable oder Konfigurationseinstellung. Es hat sich bewährt, die Dienst-URL aus einer Anwendungseinstellung/Umgebungsvariablen zu lesen, anstatt dafür Hartcodierung in der Funktion zu verwenden. In einer Azure-Funktion könnte der Code zum Lesen der Umgebungsvariablen wie folgt aussehen:

  private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
  

  Später, nach dem Veröffentlichen der Funktion, erstellen Sie den Wert der Umgebungsvariablen und legen ihn fest, damit er von diesem Code gelesen werden kann. Anweisungen dazu finden Sie unter Konfigurieren von Anwendungseinstellungen.

• Eine statische Variable zum Aufnehmen einer HttpClient-Instanz Die Erstellung von HttpClient ist relativ teuer, daher sollten Sie diese Instanz wahrscheinlich ein Mal mit dem Authentifizierungscode erstellen, um zu vermeiden, dass sie für jeden Funktionsaufruf erstellt wird.

  private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
  

• Anmeldeinformationen für verwaltete Identität. Erstellen Sie Anmeldeinformationen für die verwaltete Identität, die Ihre Funktion für den Zugriff auf Azure Digital Twins verwendet.

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

  Wenn der Parameter leer bleibt, wie oben gezeigt, werden die Anmeldeinformationen für die vom System zugewiesene Identität der Funktions-App zurückgegeben, sofern er über eine verfügt. Um stattdessen eine vom Benutzer zugewiesene Identität anzugeben, übergeben Sie die Client-ID der vom Benutzer zugewiesenen Identität an den Parameter.

  Später stellen Sie nach der Veröffentlichung der Funktion sicher, dass die Identität der Funktion über die Berechtigung für den Zugriff auf die Azure Digital Twins-APIs verfügt. Anweisungen dazu finden Sie unter Zuweisen einer Zugriffsrolle.

• Eine lokale Variable DigitalTwinsClient. Fügen Sie die Variable innerhalb Ihrer Funktion hinzu, um Ihre Azure Digital Twins-Clientinstanz aufzunehmen. Verwenden Sie hierfür keine statische Variable innerhalb Ihrer Klasse.

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

• Eine NULL-Überprüfung für adtInstanceUrl. Fügen Sie eine NULL-Überprüfung hinzu, und umschließen Sie Ihre Funktionslogik mit einem Try-Catch-Block, um alle Ausnahmen abzufangen.

Nachdem einer Funktion diese Variablen hinzugefügt wurden, könnte Ihr Funktionscode wie im folgenden Beispiel aussehen.

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

Wenn Sie mit Ihrem Funktionscode fertig sind, einschließlich Hinzufügen der Authentifizierung und der Logik der Funktion, veröffentlichen Sie die App in Azure.

Konfigurieren einer veröffentlichten App

Führen Sie abschließend die folgenden Konfigurationsschritte für eine veröffentlichte Azure-Funktion aus, um sicherzustellen, dass sie auf Ihre Azure Digital Twins-Instanz zugreifen kann.

Führen Sie die folgenden Befehle in Azure Cloud Shell oder einer lokalen Installation der Azure CLI aus.

Zuweisen einer Zugriffsrolle

Die Azure-Funktion erfordert die Übergabe eines Bearertokens. Um sicherzustellen, dass das Bearertoken übergeben wird, erteilen Sie der Funktions-App die Rolle Azure Digital Twins-Datenbesitzer für Ihre Azure Digital Twins-Instanz, die der Funktions-App die Berechtigung zum Ausführen von Datenebenenaktivitäten für die Instanz erteilt.

1. Verwenden Sie den folgenden Befehl, um eine systemseitig verwaltete Identität für Ihre Funktion zu erstellen (wenn die Funktion bereits über eine verfügt, gibt dieser Befehl deren Details aus). Notieren Sie sich das Feld principalId in der Ausgabe. Sie verwenden diese ID, um auf die Funktion zu verweisen, damit Sie ihr im nächsten Schritt Berechtigungen erteilen können.

   az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
   

2. Verwenden Sie den Wert principalId im folgenden Befehl, um der Funktion die Rolle Azure Digital Twins-Datenbesitzer für Ihre Azure Digital Twins-Instanz zuzuweisen.

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

Konfigurieren von Anwendungseinstellungen

Ermöglichen Sie Ihrer Funktion dann den Zugriff auf die URL Ihrer Azure Digital Twins-Instanz, indem Sie eine Umgebungsvariable für sie festlegen.

Der folgende Befehl legt eine Umgebungsvariable für die URL Ihrer Instanz fest, die Ihre Funktion immer dann verwendet, wenn sie auf die Instanz zugreifen muss.

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

Mandantenübergreifende Authentifizierung

Bei Azure Digital Twins handelt es sich um einen Dienst, der nur einen einzelnen Microsoft Entra-Mandanten unterstützt: den Hauptmandanten aus dem Abonnement, in dem sich die Azure Digital Twins-Instanz befindet.

Daher erfordern Anforderungen an die Azure Digital Twins-APIs einen Benutzer oder Dienstprinzipal, der Teil desselben Mandanten ist, in dem sich die Azure Digital Twins-Instanz befindet. Um böswillige Überprüfungen von Azure Digital Twins-Endpunkten zu verhindern, wird für Anforderungen mit Zugriffstoken von außerhalb des ursprünglichen Mandanten die Fehlermeldung „404 Sub-Domain nicht gefunden“ zurückgegeben. Dieser Fehler wird zurückgegeben, auch wenn dem Benutzer oder Dienstprinzipal eine Azure Digital Twins Data Owner- oder Azure Digital Twins Data Reader-Rolle über Microsoft Entra B2B-Zusammenarbeit erteilt wurde.

Wenn Sie mit einem Dienstprinzipal oder Benutzerkonto eines anderen Mandanten auf Ihre Azure Digital Twins-Instanz zugreifen müssen, können Sie dafür sorgen, dass von jeder Verbundidentität eines anderen Mandanten ein Token vom Basismandanten der Azure Digital Twins-Instanz angefordert wird.

Eine Möglichkeit hierzu ist der folgende CLI-Befehl, wobei <home-tenant-ID> die ID des Microsoft Entra-Mandanten ist, der die Azure Digital Twins-Instanz enthält:

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

Nach der Anforderung erhält die Identität ein Token, das für die Microsoft Entra-Ressource https://digitaltwins.azure.net ausgestellt wurde, die über einen entsprechenden Mandanten-ID-Anspruch für die Azure Digital Twins-Instanz verfügt. Die Verwendung dieses Tokens in API-Anforderungen oder mit Ihrem Azure.Identity-Code sollte der Verbundidentität den Zugriff auf die Azure Digital Twins ermöglichen.

Sie können auch den Basismandanten in den Anmeldeinformationsoptionen in Ihrem Code angeben.

Das folgende Beispiel zeigt, wie der Wert für eine Beispielmandanten-ID für InteractiveBrowserTenantId in den DefaultAzureCredential-Optionen festgelegt wird:

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

In Visual Studio und Visual Studio Code stehen ähnliche Optionen zum Festlegen eines Mandanten für die Authentifizierung zur Verfügung. Weitere Informationen zu den verfügbaren Optionen finden Sie in der DefaultAzureCredentialOptions-Dokumentation.

Andere Methoden für Anmeldeinformationen

Wenn die oben genannten Authentifizierungsszenarien nicht die Anforderungen Ihrer App abdecken, können Sie andere Arten von Authentifizierung untersuchen, die auf der Microsoft Identity Platform angeboten werden. Die Dokumentation für diese Plattform behandelt weitere Authentifizierungsszenarien, geordnet nach Anwendungstyp.

Nächste Schritte

Erfahren Sie mehr zum Thema Sicherheit in Azure Digital Twins:

• Sicherheit für Azure Digital Twins-Lösungen

Nachdem Sie die Authentifizierung eingerichtet haben, können Sie alternativ damit fortfahren, Modelle in Ihrer Instanz zu erstellen und zu verwalten:

• Verwalten von DTDL-Modellen