Verificatiecode voor client-apps schrijven

Nadat u een Azure Digital Twinsen verificatie hebt ingesteld, kunt u een clienttoepassing maken die u gaat gebruiken om met het exemplaar te communiceren. Zodra u een startersclientproject hebt ingesteld, moet u code schrijven in die client-app om deze te verifiëren aan de Azure Digital Twins exemplaar.

Azure Digital Twins wordt geverifieerd met behulp van Azure AD-beveiligingstokens op basis van OAUTH 2.0. Als u uw SDK wilt verifiëren, moet u een Bearer-token met de juiste machtigingen voor Azure Digital Twins en deze samen met uw API-aanroepen doorgeven.

In dit artikel wordt beschreven hoe u referenties kunt verkrijgen met behulp van de Azure.Identity clientbibliotheek. Hoewel in dit artikel codevoorbeelden in C# worden beschreven, zoals wat u schrijft voor de .NET -SDK (C#),kunt u een versie gebruiken van ongeacht welke SDK u gebruikt (zie Azure Digital Twins API's en SDK's voor meer informatie over de Azure.Identity SDK's die beschikbaar zijn voor Azure Digital Twins.

Vereisten

Voltooi eerst de installatiestappen in Een exemplaar en verificatie instellen. Deze installatie zorgt ervoor dat u een Azure Digital Twins hebt en dat uw gebruiker toegangsmachtigingen heeft. Na deze installatie bent u klaar om de code van de client-app te schrijven.

Als u wilt doorgaan, hebt u een client-app-project nodig waarin u uw code schrijft. Als u nog geen client-app-project hebt ingesteld, maakt u een basisproject in de taal van uw keuze voor gebruik met deze zelfstudie.

Verifiëren met behulp van azure.identity-bibliotheek

Azure.Identity is een clientbibliotheek die verschillende methoden voor het verkrijgen van referenties biedt die u kunt gebruiken om een Bearer-token op te halen en te verifiëren met uw SDK. Hoewel dit artikel voorbeelden in C# bevat, kunt u voor verschillende Azure.Identity talen bekijken, waaronder...

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

Drie veelvoorkomende methoden voor het verkrijgen van referenties in Azure.Identity zijn:

• DefaultAzureCredential biedt een standaardverificatiestroom voor toepassingen die worden geïmplementeerd in Azure en is de aanbevolen keuze TokenCredential voor lokale ontwikkeling. Het kan ook worden ingeschakeld om de andere twee methoden uit te proberen die in dit artikel worden aanbevolen; deze wordt verpakt ManagedIdentityCredential en kan worden toegankelijk met een InteractiveBrowserCredential configuratievariabele.
• ManagedIdentityCredential werkt goed in gevallen waarin u beheerde identiteiten (MSI)nodig hebt en een goede kandidaat is voor het werken met Azure Functions en implementatie in Azure-services.
• InteractiveBrowserCredential is bedoeld voor interactieve toepassingen en kan worden gebruikt om een geverifieerde SDK-client te maken.

In de rest van dit artikel ziet u hoe u deze methoden gebruikt met de .NET SDK (C#).

Azure.Identity toevoegen aan uw .NET-project

Voltooi de volgende stappen om uw .NET-project in te stellen voor verificatie met Azure.Identity :

1. Neem het SDK-pakket Azure.DigitalTwins.Core en het pakket op in uw Azure.Identity project. Afhankelijk van de hulpprogramma's van uw keuze, kunt u de pakketten opnemen met behulp van Visual Studio pakketbeheer of het dotnet opdrachtregelprogramma.

2. Voeg de volgende using-instructies toe aan uw projectcode:

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

Voeg vervolgens code toe om referenties te verkrijgen met behulp van een van de methoden in Azure.Identity . De volgende secties geven meer informatie over het gebruik van elke sectie.

Methode DefaultAzureCredential

DefaultAzureCredential biedt een standaardverificatiestroom voor toepassingen die worden geïmplementeerd in Azure en is de aanbevolen keuze TokenCredential voor lokale ontwikkeling.

Als u de standaardreferenties van Azure wilt gebruiken, hebt u de URL Azure Digital Twins van het exemplaar nodig(instructies om te zoeken).

Hier is een codevoorbeeld om een toe te DefaultAzureCredential voegen aan uw project:

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

Lokale Azure-referenties instellen

Met DefaultAzureCredential zoekt het voorbeeld naar referenties in uw lokale omgeving, zoals een Azure-aanmelding in een lokale Azure-CLI of in Visual Studio of Visual Studio Code. Daarom moet u zich lokaal aanmelden bij Azure via een van deze mechanismen om referenties in te stellen voor het voorbeeld.

Als u gebruikmaakt van Visual Studio of Visual Studio Code om het codevoorbeeld uit te voeren, moet u ervoor zorgen dat u bent aangemeld bij die editor met dezelfde Azure-referenties die u wilt gebruiken om uw Azure Digital Twins-instantie te openen.

Anders kunt u de Azure-CLI lokaal installeren, de opdrachtprompt uitvoeren op uw machine en de opdracht az login uitvoeren om u aan te melden bij uw Azure-account. Wanneer u hierna uw codevoorbeeld moet uitvoeren, zou u automatisch aangemeld moeten worden.

Methode ManagedIdentityCredential

De methode ManagedIdentityCredential werkt goed in gevallen waarin u beheerde identiteiten (MSI)nodig hebt, bijvoorbeeld bij het Azure Functions .

Dit betekent dat u in hetzelfde project als of kunt gebruiken om ManagedIdentityCredential een ander deel van het project te DefaultAzureCredential InteractiveBrowserCredential verifiëren.

Als u de standaardreferenties van Azure wilt gebruiken, hebt u de URL Azure Digital Twins van het exemplaar nodig(instructies om te zoeken). Mogelijk hebt u ook een app-registratie en de toepassings-id (client-id) van de registratie nodig.

In een Azure-functie kunt u de referenties van de beheerde identiteit als de volgende gebruiken:

public class ManagedIdentityCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";
    // Your client / app registration ID
    private const string adtAppId = "<your-client-ID>";

    internal void RunSample()
    {
        DigitalTwinsClient client;
        try
        {
            ManagedIdentityCredential cred = new ManagedIdentityCredential(adtAppId);
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Methode InteractiveBrowserCredential

De methode InteractiveBrowserCredential is bedoeld voor interactieve toepassingen en biedt een webbrowser voor verificatie. U kunt deze methode gebruiken in plaats van DefaultAzureCredential in gevallen waarin u interactieve verificatie nodig hebt.

Als u de referenties van de interactieve browser wilt gebruiken, hebt u een app-registratie nodig die machtigingen heeft voor de Azure Digital Twins API's. Zie Een app-registratie maken voor stappen voor het instellen van deze app-registratie. Zodra de app-registratie is ingesteld, hebt u...

• de toepassings-id (client-id) van de app-registratie
• de directory-id (tenant-id) van de app-registratie
• url Azure Digital Twins van het exemplaar

Hier is een voorbeeld van de code voor het maken van een geverifieerde SDK-client met behulp van 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);
        }
    }

Verificatie Azure Functions

Deze sectie bevat enkele van de belangrijke configuratiekeuzen in de context van de Azure Functions. Eerst leest u meer over aanbevolen variabelen op klasseniveau en verificatiecode waarmee de functie toegang krijgt tot Azure Digital Twins. Vervolgens leest u over een aantal laatste configuratiestappen die moeten worden uitgevoerd voor uw functie nadat de code is gepubliceerd naar Azure.

Toepassingscode schrijven

Wanneer u de Azure-functie schrijft, kunt u deze variabelen en code toevoegen aan uw functie:

• Code voor het lezen van Azure Digital Twins service-URL als een omgevingsvariabele of configuratie-instelling. Het is een goed idee om de service-URL van een toepassingsinstelling/omgevingsvariabele te lezen in plaats van deze in de functie hard te coderen. In een Azure-functie kan die code voor het lezen van de omgevingsvariabele er als volgende uitzien:

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

  Later, nadat u de functie hebt gepubliceerd, gaat u de waarde van de omgevingsvariabele voor deze code maken en instellen om te lezen. Ga verder met Toepassingsinstellingen configureren voor instructies om dit te doen.

• Een statische variabele voor het gebruik van een HttpClient-exemplaar. HttpClient is relatief duur om te maken, dus u wilt deze waarschijnlijk één keer maken met de verificatiecode om te voorkomen dat deze voor elke functieaanroep wordt gemaakt.

  private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
  

• Referenties voor beheerde identiteit. Maak een beheerde identiteitsreferentie die uw functie gebruikt voor toegang tot Azure Digital Twins.

  var cred = new ManagedIdentityCredential("https://digitaltwins.azure.net");
  

  Later, nadat u de functie hebt gepubliceerd, moet u ervoor zorgen dat de identiteit van de functie toegang heeft tot de Azure Digital Twins API's. Ga verder met Een toegangsrol toewijzen voor instructies om dit te doen.

• Een lokale variabele DigitalTwinsClient. Voeg de variabele toe binnen uw functie om uw Azure Digital Twins te houden. Maak deze variabele niet statisch binnen uw klasse.

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

• Een null-controle voor adtInstanceUrl. Voeg de null-controle toe en verpak uw functielogica in een try/catch-blok om eventuele uitzonderingen te ondervangen.

Nadat deze variabelen zijn toegevoegd aan een functie, kan uw functiecode lijken op het volgende voorbeeld.

// 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 Microsoft.Azure.EventGrid.Models;
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>
                var cred = new ManagedIdentityCredential("https://digitaltwins.azure.net");
                // </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);
            }
        }
    }
}

Wanneer u klaar bent met uw functiecode, inclusief het toevoegen van verificatie en de logica van de functie, publiceert u de app naar Azure

Gepubliceerde app configureren

Voltooi ten slotte de volgende configuratiestappen voor een gepubliceerde Azure-functie om ervoor te zorgen dat deze toegang heeft tot Azure Digital Twins-exemplaar.

Voer de volgende opdrachten uit in Azure Cloud Shell of een lokale Azure CLI.

Een toegangsrol toewijzen

De Azure-functie vereist dat er een Bearer-token aan wordt doorgegeven. Om ervoor te zorgen dat het bearer-token wordt doorgegeven, verleent u de functie-app de rol Azure Digital Twins Gegevenseigenaar voor uw Azure Digital Twins-exemplaar, waarmee de functie-app toestemming krijgt om gegevensvlakactiviteiten op het exemplaar uit te voeren.

1. Gebruik de volgende opdracht om de details van de door het systeem beheerde identiteit van uw functie te bekijken. Noteer het principalId veld in de uitvoer. U gebruikt deze id om naar de functie te verwijzen, zodat u deze in de volgende stap machtigingen kunt verlenen.

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

   Notitie

   Als het resultaat leeg is in plaats van identiteitsdetails weer te geven, maakt u een nieuwe door het systeem beheerde identiteit voor de functie met behulp van deze opdracht:

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

   In de uitvoer worden details van de identiteit weergegeven, met inbegrip van principalId de waarde die is vereist voor de volgende stap.

2. Gebruik de waarde in de volgende opdracht om de functie de rol Azure Digital Twins principalId gegevenseigenaar voor uw Azure Digital Twins geven.

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

Toepassingsinstellingen configureren

Maak vervolgens de URL van uw Azure Digital Twins toegankelijk voor uw functie door er een omgevingsvariabele voor in te stellen.

Met de volgende opdracht stelt u een omgevingsvariabele in voor de URL van uw exemplaar die door uw functie wordt gebruikt wanneer deze toegang nodig heeft tot het exemplaar.

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

Verifiëren in meerdere tenants

Azure Digital Twins is een service die slechts één Azure Active Directory (Azure AD)-tenantondersteunt: de hoofd-tenant van het abonnement waarin de Azure Digital Twins zich bevindt.

Als gevolg hiervan is voor aanvragen naar Azure Digital Twins API's een gebruiker of service-principal vereist die deel uitmaakt van dezelfde tenant waarin de Azure Digital Twins zich bevindt. Om schadelijke scans van Azure Digital Twins eindpunten te voorkomen, krijgen aanvragen met toegangstokens van buiten de oorspronkelijke tenant het foutbericht '404 Sub-Domain niet gevonden'. Deze fout wordt zelfs geretourneerd als de gebruiker of service-principal de rol Azure Digital Twins Gegevenseigenaar of Azure Digital Twins-gegevenslezer heeft gekregen via Azure AD B2B-samenwerking.

Als u toegang wilt krijgen tot uw Azure Digital Twins-exemplaar met behulp van een service-principal of gebruikersaccount dat tot een andere tenant van het exemplaar behoort, kunt u elke federatief identiteit van een andere tenant een token laten aanvragen bij de tenant 'home' van het Azure Digital Twins-exemplaar.

Een manier om dit te doen is met de volgende CLI-opdracht, waarbij de id is van de Azure AD-tenant die de <home-tenant-ID> Azure Digital Twins bevat:

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

Nadat u dit hebt gevraagd, ontvangt de identiteit een token dat is uitgegeven voor de Azure AD-resource, die een overeenkomende tenant-id-claim heeft voor het https://digitaltwins.azure.net Azure Digital Twins exemplaar. Als u dit token gebruikt in API-aanvragen of met uw code, kan de federatiede identiteit toegang krijgen tot Azure.Identity de Azure Digital Twins resource.

U kunt ook de thuis-tenant opgeven in de referentieopties in uw code.

In het volgende voorbeeld ziet u hoe u een tenant-id-waarde in de InteractiveBrowserTenantId opties in kunt stellen DefaultAzureCredential voor:

Er zijn vergelijkbare opties beschikbaar om een tenant in te stellen voor verificatie met Visual Studio en Visual Studio Code. Zie de defaultAzureCredentialOptions-documentatievoor meer informatie over de beschikbare opties.

Andere referentiemethoden

Als de gemarkeerde verificatiescenario's hierboven niet voldoen aan de behoeften van uw app, kunt u andere typen verificatie verkennen die worden aangeboden in de Microsoft identity platform. De documentatie voor dit platform bevat meer verificatiescenario's, geordend op toepassingstype.

Volgende stappen

Lees meer over hoe beveiliging werkt in Azure Digital Twins:

• Beveiliging voor Azure Digital Twins-oplossingen

Of, nu de verificatie is ingesteld, gaat u verder met het maken en beheren van modellen in uw exemplaar:

• DTDL-modellen beheren