Schreiben von Authentifizierungscode für die Client-App

Nachdem Sie eine Azure Digital Twins-Instanz und -Authentifizierung eingerichtet haben, können Sie eine Clientanwendung für die Interaktion mit der Instanz erstellen. In diesem Artikel wird erläutert, wie Sie Code in dieser Client-App schreiben, um sie bei der Azure Digital Twins-Instanz zu authentifizieren.

Azure Digital Twins führt die Authentifizierung mithilfe von Microsoft Entra-Sicherheitstoken basierend auf OAUTH 2.0 aus. Um Ihr SDK zu authentifizieren, rufen Sie ein Bearertoken mit den richtigen Berechtigungen für Azure Digital Twins ab, und übergeben Sie es zusammen mit Ihren API-Aufrufen.

In diesem Artikel wird beschrieben, wie Sie mithilfe der Azure.Identity-Clientbibliothek Anmeldeinformationen abrufen. Während in diesem Artikel Codebeispiele in C# gezeigt werden, z. B. solche, die Sie für das .NET (C#)-SDK schreiben würden, können Sie unabhängig davon, welches SDK Sie verwenden, eine Version von Azure.Identity nutzen. 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 die benutzende Person 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 Standard-TokenCredentialAuthentifizierungsfluss für Anwendungen bereit, die in Azure bereitgestellt werden. Diese Methode ist die empfohlene Wahl für die lokale Entwicklung. Es ist auch in der Lage, die beiden anderen in diesem Artikel empfohlenen Methoden auszuprobieren; es umschließt ManagedIdentityCredential und kann mit einer Konfigurationsvariablen auf InteractiveBrowserCredential zugreifen.
• ManagedIdentityCredential funktioniert gut in Fällen, in denen Sie verwaltete Identitäten (MSI) benötigen. Diese Methode ist ein guter Kandidat für die Arbeit mit Azure Functions und der Bereitstellung in Azure-Diensten.
• InteractiveBrowserCredential ist für interaktive Anwendungen vorgesehen. Dies ist eine Methode zum Erstellen eines authentifizierten SDK-Clients.

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 Details zur Verwendung der einzelnen Methoden.

DefaultAzureCredential-Methode

DefaultAzureCredential stellt einen Standard-TokenCredentialAuthentifizierungsfluss für Anwendungen bereit, die in Azure bereitgestellt werden. Diese Methode ist die empfohlene Wahl für die 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).

Hier ist ein Codebeispiel, um ein DefaultAzureCredential zu Ihrem Projekt hinzuzufügen:

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 Azure CLI 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. Nachdem Sie angemeldet sind, authentifiziert sich Ihr Codebeispiel automatisch, wenn es ausgeführt wird.

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.

Sie können ManagedIdentityCredential im selben Projekt wie DefaultAzureCredential oder InteractiveBrowserCredential verwenden, 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);
        }
    }
}

Wenn Sie die Anmeldeinformationen ohne Parameter erstellen, wie im vorherigen Beispiel gezeigt, werden die Anmeldeinformationen für die vom System zugewiesene Identität der Funktions-App zurückgegeben, sofern sie ü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 id für den Konstruktor.

InteractiveBrowserCredential-Methode

Die InteractiveBrowserCredential-Methode ist für interaktive Anwendungen gedacht und startet einen Webbrowser für die Authentifizierung. Verwenden Sie diese Methode anstelle von DefaultAzureCredential, wenn eine interaktive Authentifizierung erforderlich ist.

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. Nachdem die App-Registrierung eingerichtet wurde, benötigen Sie die folgenden Werte:

• 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 wichtige Konfigurationsoptionen für die Authentifizierung mit Azure-Funktionen. 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");
  

  Erstellen und festlegen Sie später nach der Veröffentlichung der Funktion den Wert der Umgebungsvariable für diesen Code, der gelesen werden soll. Anweisungen dazu finden Sie unter "Konfigurieren von Anwendungseinstellungen".

• Eine statische Variable zum Speichern 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 Sie die Anmeldeinformationen ohne Parameter erstellen, wie im vorherigen Beispiel gezeigt, werden die Anmeldeinformationen für die vom System zugewiesene Identität der Funktions-App zurückgegeben, sofern sie ü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 id für den Konstruktor.

  Stellen Sie später nach der Veröffentlichung der Funktion sicher, dass die Identität der Funktion über die Berechtigung zum 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 Sie diese Variablen zu einer Funktion hinzugefügt haben, kann 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 Data Owner " für Ihre Azure Digital Twins-Instanz, die der Funktions-App die Berechtigung zum Ausführen von Datenebenenaktivitäten in der Instanz erteilt.

1. Verwenden Sie den folgenden Befehl, um eine vom System verwaltete Identität für Ihre Funktion zu erstellen (wenn die Funktion bereits über einen verfügt, druckt dieser Befehl seine Details). 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 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 die böswillige Überprüfung von Azure Digital Twins-Endpunkten zu verhindern, geben Anforderungen mit Zugriffstoken von außerhalb des ursprünglichen Mandanten eine Fehlermeldung "404 Sub-Domain nicht gefunden" zurück. Dieser Fehler wird zurückgegeben, auch wenn dem Benutzer oder Dienstprinzipal eine Azure Digital Twins Data Owner-Rolle 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 dieser Anforderung empfängt die Identität ein Token, das für die https://digitaltwins.azure.net Microsoft Entra-Ressource ausgestellt wurde, die über einen übereinstimmenden Mandanten-ID-Anspruch an die Azure Digital Twins-Instanz verfügt. Um der Verbundidentität den Zugriff auf die Azure Digital Twins-Ressource zu ermöglichen, sollten Sie dieses Token in API-Anforderungen oder mit Ihrem Azure.Identity-Code verwenden.

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 zur Verfügung, um einen Mandanten für die Authentifizierung festzulegen. Weitere Informationen zu den verfügbaren Optionen finden Sie in der DefaultAzureCredentialOptions-Dokumentation.

Andere Methoden für Anmeldeinformationen

Wenn die in diesem Artikel beschriebenen hervorgehobenen Authentifizierungsszenarien nicht die Anforderungen Ihrer App abdecken, erkunden Sie andere Authentifizierungstypen, die in der Microsoft Identity Platform angeboten werden. Die Dokumentation für diese Plattform behandelt weitere Authentifizierungsszenarien, geordnet nach Anwendungstyp.

Nächste Schritte

Weitere Informationen zur Funktionsweise von Sicherheit in Azure Digital Twins finden Sie unter:

• 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