Verificatiecode voor client-apps schrijven

Nadat u een Azure Digital Twins-exemplaar en -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 bij het Azure Digital Twins-exemplaar.

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

In dit artikel wordt beschreven hoe u referenties ophaalt met behulp van de Azure.Identity clientbibliotheek. Hoewel in dit artikel codevoorbeelden in C# worden weergegeven, zoals wat u schrijft voor de .NET -SDK (C#), kunt u een versie gebruiken van Azure.Identity ongeacht welke SDK u gebruikt (zie Azure Digital Twins-API's en SDK's voor meer informatie over de 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-exemplaar hebt en dat uw gebruiker toegangsmachtigingen heeft. Na deze installatie bent u klaar om code voor client-apps 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 biedt voor het verkrijgen van referenties 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 talen bekijken Azure.Identity , waaronder...

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

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

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

De rest van dit artikel laat zien hoe u deze methoden gebruikt met de .NET -SDK (C#).

Azure.Identity toevoegen aan uw .NET-project

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

1. Neem het SDK-pakket Azure.DigitalTwins.Core en het Azure.Identity pakket in uw project op. Afhankelijk van uw hulpprogramma's kunt u de pakketten opnemen met 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. In de volgende secties vindt u meer informatie over het gebruik van elke sectie.

Methode DefaultAzureCredential

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

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

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

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

Notitie

Er is momenteel een bekend probleem dat van invloed is op de DefaultAzureCredential wrapper-klasse die kan leiden tot een fout tijdens het verifiëren. Als u dit probleem ondervindt, kunt u proberen te instantiëren DefaultAzureCredential met de volgende optionele parameter om dit op te lossen: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

Zie bekende problemen met Azure Digital Twins voor meer informatie over dit probleem.

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 Visual Studio of Visual Studio Code gebruikt om codevoorbeelden uit te voeren, moet u ervoor zorgen dat u bent aangemeld bij die editor met dezelfde Azure-referenties die u wilt gebruiken voor toegang tot uw Azure Digital Twins-exemplaar. Als u een lokaal CLI-venster gebruikt, voert u de az login opdracht uit om u aan te melden bij uw Azure-account. Daarna moet u, wanneer u het codevoorbeeld uitvoert, automatisch worden geverifieerd.

Methode ManagedIdentityCredential

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

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

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

In een Azure-functie kunt u de referenties van de beheerde identiteit als volgt 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>";

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

Wanneer u de referentie maakt, retourneert u de referentie voor de door het systeem toegewezen identiteit van de functie-app, als deze een parameter leeg laat, zoals hierboven wordt weergegeven. Als u in plaats daarvan een door de gebruiker toegewezen identiteit wilt opgeven, geeft u de client-id van de door de gebruiker toegewezen identiteit door aan de parameter.

Methode InteractiveBrowserCredential

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

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

• de toepassings-id (client) van de app-registratie
• de map-id van de app-registratie (tenant)
• DE URL van het Azure Digital Twins-exemplaar

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

Notitie

Hoewel u de client-id, tenant-id en exemplaar-URL rechtstreeks in de code kunt plaatsen zoals hierboven wordt weergegeven, is het een goed idee om deze waarden op te halen uit een configuratiebestand of omgevingsvariabele.

Azure Functions verifiëren

Deze sectie bevat enkele van de belangrijke configuratiekeuzes in de context van verificatie met 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 meer over enkele laatste configuratiestappen die u voor uw functie moet uitvoeren nadat de code is gepubliceerd naar Azure.

Toepassingscode schrijven

Overweeg bij het schrijven van de Azure-functie deze variabelen en code toe te voegen aan uw functie:

• Code voor het lezen van de URL van de Azure Digital Twins-service als een omgevingsvariabele of configuratie-instelling. Het is een goede gewoonte om de service-URL te lezen van een toepassingsinstelling/omgevingsvariabele 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 volgt uitzien:

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

  Later maakt en stelt u na het publiceren van de functie de waarde van de omgevingsvariabele in om deze code te lezen. Voor instructies over hoe u dit doet, gaat u verder met het configureren van toepassingsinstellingen.

• Een statische variabele voor het opslaan 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 wordt gemaakt voor elke functie-aanroep.

  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.

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

  Als u de parameter leeg laat, zoals hierboven wordt weergegeven, wordt de referentie geretourneerd voor de door het systeem toegewezen identiteit van de functie-app, als deze er een heeft. Als u in plaats daarvan een door de gebruiker toegewezen identiteit wilt opgeven, geeft u de client-id van de door de gebruiker toegewezen identiteit door aan de parameter.

  Later zorgt u er na het publiceren van de functie voor dat de identiteit van de functie toegang heeft tot de Azure Digital Twins-API's. Voor instructies over hoe u dit doet, gaat u verder met het toewijzen van een toegangsrol.

• Een lokale variabele DigitalTwinsClient. Voeg de variabele in uw functie toe om uw Azure Digital Twins-clientexemplaren op te slaan. Maak deze variabele niet statisch in 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 verpakt uw functielogica vervolgens in een try/catch-blok om eventuele uitzonderingen te ondervangen.

Nadat deze variabelen aan een functie zijn toegevoegd, kan uw functiecode eruitzien als in 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 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);
            }
        }
    }
}

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 uw Azure Digital Twins-exemplaar.

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

Notitie

Deze sectie moet worden voltooid door een Azure-gebruiker met machtigingen voor het beheren van gebruikerstoegang tot Azure-resources, waaronder het verlenen en delegeren van machtigingen. Algemene rollen die aan deze vereiste voldoen, zijn Eigenaar, Accountbeheerder of de combinatie van Gebruikerstoegang Beheer istrator en Inzender. Zie Een exemplaar en verificatie instellen voor meer informatie over machtigingsvereisten voor Azure Digital Twins-rollen.

Een toegangsrol toewijzen

Voor de Azure-functie moet een Bearer-token worden 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 geeft om activiteiten in het gegevensvlak op het exemplaar uit te voeren.

1. Gebruik de volgende opdracht om een door het systeem beheerde identiteit voor uw functie te maken (als de functie al een identiteit heeft, worden de details van deze opdracht afgedrukt). 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 assign --resource-group <your-resource-group> --name <your-function-app-name>	
   

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

   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-exemplaar toegankelijk voor uw functie door er een omgevingsvariabele voor in te stellen.

Fooi

De URL van het Azure Digital Twins-exemplaar wordt gemaakt door https:// toe te voegen aan het begin van de hostnaam van uw exemplaar. Als u de hostnaam, samen met alle eigenschappen van uw exemplaar, wilt zien, voert u deze uit az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Met de volgende opdracht wordt een omgevingsvariabele ingesteld 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 Microsoft Entra-tenant ondersteunt: de hoofdtenant van het abonnement waarin het Azure Digital Twins-exemplaar zich bevindt.

Als gevolg hiervan is voor aanvragen voor de Azure Digital Twins-API's een gebruiker of service-principal vereist die deel uitmaakt van dezelfde tenant waarin het Azure Digital Twins-exemplaar zich bevindt. Om kwaadwillende scans van Azure Digital Twins-eindpunten te voorkomen, krijgen aanvragen met toegangstokens van buiten de oorspronkelijke tenant een foutbericht '404 Subdomein niet gevonden'. Deze fout wordt geretourneerd, zelfs als de gebruiker of service-principal een Azure Digital Twins-gegevenseigenaar of Azure Digital Twins-gegevenslezerrol heeft gekregen via Microsoft Entra B2B-samenwerking.

Als u toegang wilt krijgen tot uw Azure Digital Twins-exemplaar met behulp van een service-principal of gebruikersaccount dat deel uitmaakt van een andere tenant dan het exemplaar, kunt u elke federatieve identiteit van een andere tenant een token aanvragen vanuit de 'home'-tenant van het Azure Digital Twins-exemplaar.

Een van de manieren om dit te doen, is met de volgende CLI-opdracht, waarbij <home-tenant-ID> de id is van de Microsoft Entra-tenant die het Azure Digital Twins-exemplaar bevat:

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

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

U kunt ook de basistenant opgeven in de referentieopties in uw code.

In het volgende voorbeeld ziet u hoe u een voorbeeld van een tenant-id instelt voor InteractiveBrowserTenantId in de DefaultAzureCredential opties:

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

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

Andere referentiemethoden

Als in de bovenstaande gemarkeerde verificatiescenario's de behoeften van uw app niet worden behandeld, kunt u andere typen verificatie verkennen die worden aangeboden in het Microsoft Identity Platform. De documentatie voor dit platform bevat meer verificatiescenario's, georganiseerd op toepassingstype.

Volgende stappen

Lees meer over de werking van beveiliging in Azure Digital Twins:

• Beveiliging voor Azure Digital Twins-oplossingen

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

• DTDL-modellen beheren