Skriva klientappens autentiseringskod

När du har konfigurerat en Azure Digital Twins-instans och autentisering kan du skapa ett klientprogram som du ska använda för att interagera med instansen. När du har konfigurerat ett startklientprojekt måste du skriva kod i klientappen för att autentisera den mot Azure Digital Twins-instansen.

Azure Digital Twins autentiserar med hjälp av Microsoft Entra-säkerhetstoken baserat på OAUTH 2.0. För att autentisera din SDK måste du skaffa en ägartoken med rätt behörigheter till Azure Digital Twins och skicka den tillsammans med dina API-anrop.

Den här artikeln beskriver hur du hämtar autentiseringsuppgifter med hjälp av Azure.Identity klientbiblioteket. Den här artikeln visar kodexempel i C#, till exempel vad du skulle skriva för .NET (C#) SDK, men du kan använda en version av Azure.Identity oavsett vilken SDK du använder (mer information om de SDK:er som är tillgängliga för Azure Digital Twins finns i Azure Digital Twins-API:er och SDK:er.

Förutsättningar

Slutför först installationsstegen i Konfigurera en instans och autentisering. Den här konfigurationen säkerställer att du har en Azure Digital Twins-instans och att användaren har åtkomstbehörighet. Efter den konfigurationen är du redo att skriva kod för klientappen.

För att fortsätta behöver du ett klientappsprojekt där du skriver koden. Om du inte redan har konfigurerat ett klientappsprojekt skapar du ett grundläggande projekt på det språk du vill använda med den här självstudien.

Autentisera med hjälp av Azure.Identity-biblioteket

Azure.Identity är ett klientbibliotek som innehåller flera metoder för att hämta autentiseringsuppgifter som du kan använda för att hämta en ägartoken och autentisera med din SDK. Även om den här artikeln innehåller exempel i C#, kan du visa Azure.Identity för flera språk, inklusive...

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

Tre vanliga metoder för att hämta autentiseringsuppgifter i Azure.Identity är:

• DefaultAzureCredential tillhandahåller ett standardautentiseringsflöde TokenCredential för program som ska distribueras till Azure och är det rekommenderade valet för lokal utveckling. Det kan också aktiveras för att prova de andra två metoderna som rekommenderas i den här artikeln. den omsluter och kan komma åt InteractiveBrowserCredential med en konfigurationsvariabelManagedIdentityCredential.
• ManagedIdentityCredential fungerar bra i fall där du behöver hanterade identiteter (MSI) och är en bra kandidat för att arbeta med Azure Functions och distribuera till Azure-tjänster.
• InteractiveBrowserCredential är avsett för interaktiva program och kan användas för att skapa en autentiserad SDK-klient.

Resten av den här artikeln visar hur du använder dessa metoder med .NET (C#) SDK.

Lägga till Azure.Identity i ditt .NET-projekt

Utför följande steg för att konfigurera .NET-projektet att autentisera med Azure.Identity:

1. Inkludera SDK-paketet Azure.DigitalTwins.Core och Azure.Identity paketet i projektet. Beroende på vilka verktyg du väljer kan du inkludera paketen med hjälp av Visual Studio-pakethanteraren eller dotnet kommandoradsverktyget.

2. Lägg till följande användningsinstruktioner i projektkoden:

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

Lägg sedan till kod för att hämta autentiseringsuppgifter med någon av metoderna i Azure.Identity. Följande avsnitt innehåller mer information om hur du använder var och en.

Standardmetod förAzureCredential

DefaultAzureCredential tillhandahåller ett standardautentiseringsflöde TokenCredential för program som ska distribueras till Azure och är det rekommenderade valet för lokal utveckling.

Om du vill använda standardautentiseringsuppgifterna för Azure behöver du Url:en för Azure Digital Twins-instansen (instruktioner att hitta).

Här är ett kodexempel för att lägga till ett DefaultAzureCredential i projektet:

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

Konfigurera lokala Azure-autentiseringsuppgifter

Med DefaultAzureCredentialsöker exemplet efter autentiseringsuppgifter i din lokala miljö, till exempel en Azure-inloggning i ett lokalt Azure CLI eller i Visual Studio eller Visual Studio Code. Därför bör du logga in på Azure lokalt via någon av dessa mekanismer för att konfigurera autentiseringsuppgifter för exemplet.

Om du använder Visual Studio eller Visual Studio Code för att köra kodexempel kontrollerar du att du är inloggad i redigeringsprogrammet med samma Azure-autentiseringsuppgifter som du vill använda för att komma åt din Azure Digital Twins-instans. Om du använder ett lokalt CLI-fönster kör az login du kommandot för att logga in på ditt Azure-konto. När du sedan kör kodexemplet bör du autentiseras automatiskt.

ManagedIdentityCredential-metod

Metoden ManagedIdentityCredential fungerar bra i fall där du behöver hanterade identiteter (MSI) – till exempel när du autentiserar med Azure Functions.

Det innebär att du kan använda ManagedIdentityCredential i samma projekt som DefaultAzureCredential eller InteractiveBrowserCredential, för att autentisera en annan del av projektet.

Om du vill använda standardautentiseringsuppgifterna för Azure behöver du Url:en för Azure Digital Twins-instansen (instruktioner att hitta). Du kan också behöva en appregistrering och registreringens program-ID (klient).

I en Azure-funktion kan du använda autentiseringsuppgifterna för den hanterade identiteten så här:

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

När du skapar autentiseringsuppgifterna returneras autentiseringsuppgifterna för funktionsappens systemtilldelade identitet om parametern är tom, vilket visas ovan. Om du vill ange en användartilldelad identitet i stället skickar du den användartilldelade identitetens klient-ID till parametern.

InteractiveBrowserCredential-metod

Metoden InteractiveBrowserCredential är avsedd för interaktiva program och öppnar en webbläsare för autentisering. Du kan använda den här metoden i stället för DefaultAzureCredential i fall där du behöver interaktiv autentisering.

Om du vill använda autentiseringsuppgifterna för interaktiva webbläsare behöver du en appregistrering som har behörighet till Azure Digital Twins-API:erna. Anvisningar om hur du konfigurerar den här appregistreringen finns i Skapa en appregistrering med Azure Digital Twins-åtkomst. När appregistreringen har konfigurerats behöver du...

• appregistreringens program-ID (klient)-ID
• appregistreringens katalog-ID (klientorganisation)
• Azure Digital Twins-instansens URL

Här är ett exempel på koden för att skapa en autentiserad SDK-klient med .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);
        }
    }
}

Autentisera Azure Functions

Det här avsnittet innehåller några av de viktiga konfigurationsalternativen i samband med autentisering med Azure Functions. Först ska du läsa om rekommenderade variabler på klassnivå och autentiseringskod som gör att funktionen kan komma åt Azure Digital Twins. Sedan läser du om några sista konfigurationssteg som ska slutföras för din funktion när dess kod har publicerats till Azure.

Skriva programkod

När du skriver Azure-funktionen bör du överväga att lägga till dessa variabler och kod i din funktion:

• Kod för att läsa Azure Digital Twins-tjänstens URL som en miljövariabel eller konfigurationsinställning. Det är en bra idé att läsa tjänst-URL:en från en programinställning/miljövariabel i stället för att hårdkoda den i funktionen. I en Azure-funktion kan koden för att läsa miljövariabeln se ut så här:

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

  Senare, när du har publicerat funktionen, skapar och anger du värdet för miljövariabeln som koden ska läsa. Anvisningar om hur du gör det finns i Konfigurera programinställningar.

• En statisk variabel som ska innehålla en HttpClient-instans. HttpClient är relativt dyrt att skapa, så du vill förmodligen skapa det en gång med autentiseringskoden för att undvika att skapa den för varje funktionsanrop.

  private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
  

• Autentiseringsuppgifter för hanterad identitet. Skapa en autentiseringsuppgift för hanterad identitet som din funktion använder för att få åtkomst till 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>");
  

  Om parametern lämnas tom enligt ovan returneras autentiseringsuppgifterna för funktionsappens systemtilldelade identitet, om den har en. Om du vill ange en användartilldelad identitet i stället skickar du den användartilldelade identitetens klient-ID till parametern.

  Senare, när du har publicerat funktionen, ser du till att funktionens identitet har behörighet att komma åt Azure Digital Twins-API:erna. Anvisningar om hur du gör det finns i Tilldela en åtkomstroll.

• En lokal variabel DigitalTwinsClient. Lägg till variabeln i funktionen för att lagra din Azure Digital Twins-klientinstans. Gör inte den här variabeln statisk i klassen.

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

• En null-kontroll för adtInstanceUrl. Lägg till null-kontrollen och omslut sedan funktionslogiken i ett try/catch-block för att fånga eventuella undantag.

När dessa variabler har lagts till i en funktion kan funktionskoden se ut som i följande exempel.

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

När du är klar med funktionskoden, inklusive att lägga till autentisering och funktionens logik, publicerar du appen i Azure

Konfigurera publicerad app

Slutför slutligen följande konfigurationssteg för en publicerad Azure-funktion för att se till att den kan komma åt din Azure Digital Twins-instans.

Kör följande kommandon i Azure Cloud Shell eller ett lokalt Azure CLI.

Tilldela en åtkomstroll

Azure-funktionen kräver att en ägartoken skickas till den. För att se till att ägartoken skickas beviljar du funktionsappen rollen Azure Digital Twins-dataägare för din Azure Digital Twins-instans, vilket ger funktionsappen behörighet att utföra dataplansaktiviteter på instansen.

1. Använd följande kommando för att skapa en systemhanterad identitet för din funktion (om funktionen redan har en kommer det här kommandot att skriva ut sin information). Anteckna fältet principalId i utdata. Du använder det här ID:t för att referera till funktionen så att du kan ge den behörighet i nästa steg.

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

2. principalId Använd värdet i följande kommando för att ge funktionen rollen Azure Digital Twins-dataägare för din Azure Digital Twins-instans.

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

Konfigurera programinställningar

Gör sedan URL:en för din Azure Digital Twins-instans tillgänglig för din funktion genom att ange en miljövariabel för den.

Följande kommando anger en miljövariabel för instansens URL som funktionen ska använda när den behöver komma åt instansen.

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

Autentisera mellan klienter

Azure Digital Twins är en tjänst som bara stöder en Microsoft Entra-klientorganisation: huvudklientorganisationen från prenumerationen där Azure Digital Twins-instansen finns.

Därför kräver begäranden till Azure Digital Twins-API:erna en användare eller tjänstens huvudnamn som ingår i samma klientorganisation där Azure Digital Twins-instansen finns. För att förhindra skadlig genomsökning av Azure Digital Twins-slutpunkter returneras felmeddelandet "404 underdomän hittades inte" om begäranden med åtkomsttoken utanför den ursprungliga klientorganisationen. Det här felet returneras även om användaren eller tjänstens huvudnamn fick rollen Azure Digital Twins Data Owner eller Azure Digital Twins Data Reader via Microsoft Entra B2B-samarbete.

Om du behöver komma åt din Azure Digital Twins-instans med hjälp av ett huvudnamn för tjänsten eller ett användarkonto som tillhör en annan klientorganisation än instansen kan du låta varje federerad identitet från en annan klient begära en token från Azure Digital Twins-instansens "hem"-klientorganisation.

Ett sätt att göra detta är med följande CLI-kommando, där <home-tenant-ID> är ID:t för Microsoft Entra-klientorganisationen som innehåller Azure Digital Twins-instansen:

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

När du har begärt detta får identiteten en token utfärdad för Microsoft Entra-resursen https://digitaltwins.azure.net , som har ett matchande klient-ID-anspråk till Azure Digital Twins-instansen. Om du använder den här token i API-begäranden eller med din Azure.Identity kod bör den federerade identiteten kunna komma åt Azure Digital Twins-resursen.

Du kan också ange hemklientorganisationen i alternativen för autentiseringsuppgifter i koden.

I följande exempel visas hur du anger ett exempel på klientorganisations-ID i InteractiveBrowserTenantId DefaultAzureCredential alternativen:

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

Det finns liknande alternativ för att ange en klient för autentisering med Visual Studio och Visual Studio Code. Mer information om tillgängliga alternativ finns i dokumentationen DefaultAzureCredentialOptions.

Andra autentiseringsmetoder

Om de markerade autentiseringsscenarierna ovan inte täcker appens behov kan du utforska andra typer av autentisering som erbjuds i Microsofts identitetsplattform. Dokumentationen för den här plattformen omfattar fler autentiseringsscenarier, ordnade efter programtyp.

Nästa steg

Läs mer om hur säkerhet fungerar i Azure Digital Twins:

• Säkerhet för Azure Digital Twins-lösningar

Eller nu när autentiseringen har konfigurerats går du vidare till att skapa och hantera modeller i din instans:

• Hantera DTDL-modeller