Skriva autentiseringskod för klientapp

När du har skapat Azure Digital Twins instans ochautentisering kan du skapa ett klientprogram som du använder för att interagera med instansen. När du har ställt in 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 Azure AD-säkerhetstoken baserat på OAUTH 2.0. För att autentisera din SDK måste du hämta en bearer-token med rätt behörigheter för att Azure Digital Twins och skicka den tillsammans med dina API-anrop.

I den här artikeln beskrivs hur du hämtar autentiseringsuppgifter med Azure.Identity hjälp av klientbiblioteket. Den här artikeln visar kodexempel i C#, till exempel vad du skriver för .NET (C#) SDK,men du kan använda en version oavsett vilken SDK du använder (mer information om SDK:er som är tillgängliga för Azure Digital Twins finns i Azure Digital Twins API:er och Azure.Identity 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örigheter. Efter installationen är du redo att skriva kod för klientappen.

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

Autentisera med hjälp av Azure.Identity-biblioteket

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

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

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

• DefaultAzureCredential tillhandahåller ett standardautentiseringsflöde för program som distribueras till Azure och är det rekommenderade TokenCredential 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 ManagedIdentityCredential och kan komma åt med en InteractiveBrowserCredential konfigurationsvariabel.
• 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 .NET-projektet

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

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

2. Lägg till följande using-uttryck 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 vart och ett.

DefaultAzureCredential-metod

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

Om du vill använda Azure-standardautentiseringsuppgifterna behöver du Azure Digital Twins-instansens URL (instruktioner för att hitta).

Här är ett kodexempel för att lägga till DefaultAzureCredential en 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 DefaultAzureCredential söker exemplet efter autentiseringsuppgifter i din lokala miljö, t. ex. 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 metoder för att ställa in autentiseringsuppgifter för exemplet.

Om du använder Visual Studio eller Visual Studio Code för att köra kod exemplet måste du kontrol lera att du är inloggad i redigeraren med samma Azure-autentiseringsuppgifter som du vill använda för att få åtkomst till Azure Digitals-instansen.

Annars kan du installera den lokala Azure CLI, starta en kommando tolk på datorn och köra az login kommandot för att logga in på ditt Azure-konto. När du har loggat in när du kör kod exemplet ska du logga in automatiskt.

ManagedIdentityCredential-metod

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

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

Om du vill använda Azure-standardautentiseringsuppgifterna behöver du Azure Digital Twins-instansens URL (instruktioner för 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 hanterade identiteter 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>";
    // 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);
        }
    }
}

InteractiveBrowserCredential-metod

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

Om du vill använda autentiseringsuppgifterna för den interaktiva webbläsaren behöver du en appregistrering som har behörighet till Azure Digital Twins API:er. Anvisningar för hur du ställer in den här appregistreringen finns i Skapa en appregistrering. När appregistreringen har ställts in behöver du...

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

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 när det gäller 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 att slutföra för funktionen 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 url Azure Digital Twins tjänsten som en miljövariabel eller konfigurationsinställning. Det är en bra idé att läsa tjänstens URL 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, ska du skapa och ange värdet för miljövariabeln som koden ska läsa. Om du vill ha anvisningar om hur du gör det kan du gå vidare till 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 den 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 autentiseringsuppgifter för hanterade identiteter som funktionen ska använda för att komma åt Azure Digital Twins.

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

  Senare, när du har publicerat funktionen, kontrollerar du att funktionens identitet har behörighet att komma åt Azure Digital Twins API:er. Om du vill ha anvisningar om hur du gör det kan du gå vidare till Tilldela en åtkomstroll.

• En lokal variabel, DigitalTwinsClient. Lägg till variabeln i din funktion för att Azure Digital Twins klientinstansen. 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 upp 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 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);
            }
        }
    }
}

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 en lokal Azure CLI.

Tilldela en åtkomstroll

Azure-funktionen kräver att en bearer-token skickas till den. För att säkerställa att ägartoken skickas beviljar du funktionsappen rollen Azure Digital Twins Data Owner 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 se information om funktionens system hanterade identitet. 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 show --resource-group <your-resource-group> --name <your-function-app-name> 
   

   Anteckning

   Om resultatet är tomt i stället för att visa identitetsinformation skapar du en ny system hanterad identitet för funktionen med hjälp av det här kommandot:

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

   Utdata visar information om identiteten, inklusive det principalId värde som krävs för nästa steg.

2. Använd värdet i följande kommando för att ge funktionen rollen principalId 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 tillgänglig för funktionen genom att ange en miljövariabel för den.

Följande kommando anger en miljövariabel för din instanss URL som funktionen använder när den behöver åtkomst till 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 endast stöder en Azure Active Directory-klientorganisation (Azure AD):den huvudsakliga klientorganisationen från den prenumeration där Azure Digital Twins-instansen finns.

Därför kräver begäranden till Azure Digital Twins API:er en användare eller tjänstens huvudnamn som är en del av samma klientorganisation där Azure Digital Twins instansen finns. För att förhindra skadlig genomsökning Azure Digital Twins slutpunkter returneras begäranden med åtkomsttoken utanför den ursprungliga klientorganisationen ett felmeddelande om att "404 Sub-Domain hittades inte". Det här felet returneras även om användarens eller tjänstens huvudnamn har fått rollen Azure Digital Twins dataägare eller Azure Digital Twins dataläsare via Azure AD B2B-samarbete.

Om du behöver åtkomst till 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 få varje federerad identitet från en annan klientorganisation att 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 är ID:t för <home-tenant-ID> den Azure AD-klientorganisation som innehåller Azure Digital Twins instansen:

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

När identiteten har begärt detta får den en token utfärdad för Azure AD-resursen, som har ett matchande https://digitaltwins.azure.net klient-ID-anspråk till Azure Digital Twins instansen. Med denna token i API-begäranden eller med din kod bör den Azure.Identity federerade identiteten få åtkomst till Azure Digital Twins resurs.

Du kan också ange hemklientorganisationen i autentiseringsalternativen i koden.

I följande exempel visas hur du anger ett klientorganisations-ID-värde InteractiveBrowserTenantId för i DefaultAzureCredential alternativen:

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 behoven i din app 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 ställts in, går du vidare till att skapa och hantera modeller i din instans:

• Hantera DTDL-modeller