Psaní ověřovacího kódu klientské aplikace

Po nastavení instance Azure Digital Twinsověřování můžete vytvořit klientskou aplikaci, kterou použijete k interakci s instancí. Jakmile nastavíte počáteční klientský projekt, budete muset v této klientské aplikaci napsat kód, který ho ověří vůči Azure Digital Twins instanci.

Azure Digital Twins ověřování pomocí tokenů zabezpečení Azure AD na základě OAUTH 2.0. K ověření sady SDK budete muset získat bearer token se správnými oprávněními k Azure Digital Twins a předat ho společně s voláními rozhraní API.

Tento článek popisuje, jak získat přihlašovací údaje pomocí Azure.Identity klientské knihovny. I když tento článek ukazuje příklady kódu v jazyce C#, například co napíšete pro sadu .NET (C#) SDK,můžete použít verzi bez ohledu na to, jakou sadu SDK používáte (další informace o sadách SDK dostupných pro Azure Digital Twins najdete v tématu Rozhraní AZURE DIGITAL TWINS API a sady SDK Azure.Identity .

Požadavky

Nejprve proveďte kroky nastavení v části Nastavení instance a ověřování. Toto nastavení zajistí, že máte instanci Azure Digital Twins a že váš uživatel má přístupová oprávnění. Po tomto nastavení jste připraveni napsat kód klientské aplikace.

Abyste mohli pokračovat, budete potřebovat projekt klientské aplikace, do kterého budete psát kód. Pokud ještě nemáte nastavený projekt klientské aplikace, vytvořte základní projekt ve vašem jazyce podle volby, který budete v tomto kurzu používat.

Ověřování pomocí knihovny Azure.Identity

Azure.Identity je klientská knihovna, která poskytuje několik metod získávání přihlašovacích údajů, které můžete použít k získání bearer tokenu a ověření pomocí vaší sady SDK. I když tento článek obsahuje příklady v jazyce C#, můžete zobrazit Azure.Identity několik jazyků, včetně...

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

V souboru existují tři běžné metody získávání přihlašovacích Azure.Identity údajů:

• DefaultAzureCredential poskytuje výchozí tok ověřování pro aplikace, které se nasadí do Azure, a je doporučenou volbou TokenCredential pro místní vývoj. Můžete také povolit vyzkoušet další dvě metody doporučené v tomto článku. Zabalí a ManagedIdentityCredential má přístup pomocí konfigurační InteractiveBrowserCredential proměnné.
• ManagedIdentityCredential funguje skvěle v případech, kdy potřebujete spravované identity (MSI)a je dobrým kandidátem pro práci s Azure Functions a nasazování do služeb Azure.
• Vlastnost InteractiveBrowserCredential je určená pro interaktivní aplikace a lze ji použít k vytvoření ověřeného klienta sady SDK.

Zbývající část tohoto článku ukazuje, jak tyto metody používat se sadou .NET SDK (C#).

Přidání Azure.Identity do projektu .NET

Pokud chcete nastavit ověřování pomocí projektu Azure.Identity .NET, proveďte následující kroky:

1. Do svého projektu Azure.DigitalTwins.Core Azure.Identity zahrnte balíček SDK a balíček . V závislosti na vašich nástrojích můžete zahrnout balíčky pomocí Visual Studio nebo dotnet nástroje příkazového řádku.

2. Do kódu projektu přidejte následující příkazy using:

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

Dále přidejte kód pro získání přihlašovacích údajů pomocí jedné z metod v Azure.Identity . V následujících částech najdete podrobnější informace o používání každé z nich.

Metoda DefaultAzureCredential

DefaultAzureCredential poskytuje výchozí tok ověřování pro aplikace, které se nasadí do Azure, a je doporučenou volbou TokenCredential pro místní vývoj.

Pokud chcete použít výchozí přihlašovací údaje Azure, budete potřebovat adresu URL Azure Digital Twins instance služby(pokyny k vyhledání).

Tady je ukázka kódu pro přidání do DefaultAzureCredential projektu:

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

Nastavení místních přihlašovacích údajů Azure

V DefaultAzureCredential případě bude ukázka Hledat přihlašovací údaje v místním prostředí, jako je například přihlášení k Azure v místním rozhraní příkazového řádku Azure nebo v aplikaci Visual Studio nebo Visual Studio Code. Z tohoto důvodu byste se měli přihlásit k Azure místně prostřednictvím jednoho z těchto mechanismů a nastavit přihlašovací údaje pro ukázku.

Pokud používáte aplikaci Visual Studio nebo Visual Studio Code ke spuštění ukázky kódu, ujistěte se, že jste přihlášeni k tomuto editoru se stejnými přihlašovacími údaji Azure, které chcete použít pro přístup k instanci digitálních vláken Azure.

V opačném případě můžete nainstalovat místní rozhranípříkazového řádku Azure, spustit příkazový řádek na svém počítači a spustit az login příkaz pro přihlášení k účtu Azure. Po přihlášení si můžete při spuštění ukázky kódu automaticky přihlásit.

Metoda ManagedIdentityCredential

Metoda ManagedIdentityCredential funguje skvěle v případech, kdy potřebujete spravované identity (MSI),například při ověřování pomocí Azure Functions.

To znamená, že můžete ManagedIdentityCredential použít ve stejném projektu jako nebo k ověření jiné části DefaultAzureCredential InteractiveBrowserCredential projektu.

Pokud chcete použít výchozí přihlašovací údaje Azure, budete potřebovat adresu URL Azure Digital Twins instance služby(pokyny k vyhledání). Můžete také potřebovat registraci aplikace a ID aplikace (klienta) registrace.

Ve funkci Azure můžete použít přihlašovací údaje spravované identity, jako je tato:

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

Metoda InteractiveBrowserCredential

Metoda InteractiveBrowserCredential je určená pro interaktivní aplikace a zobrazí webový prohlížeč pro ověřování. Tuto metodu můžete použít místo DefaultAzureCredential v případech, kdy vyžadujete interaktivní ověřování.

Pokud chcete použít přihlašovací údaje interaktivního prohlížeče, budete potřebovat registraci aplikace, která má oprávnění k Azure Digital Twins API. Postup nastavení této registrace aplikace najdete v tématu Vytvoření registrace aplikace. Po nastavení registrace aplikace budete potřebovat...

• ID aplikace (klienta) registrace aplikace
• ID adresáře (tenanta) registrace aplikace
• adresa AZURE DIGITAL TWINS instance služby

Tady je příklad kódu pro vytvoření ověřeného klienta sady SDK pomocí 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);
        }
    }

Ověřování Azure Functions

Tato část obsahuje některé důležité možnosti konfigurace v kontextu ověřování pomocí Azure Functions. Nejprve si přečtete informace o doporučených proměnných na úrovni třídy a ověřovacím kódu, které této funkci umožní přístup k Azure Digital Twins. Potom si přečtete o některých finálních krocích konfigurace pro vaši funkci po publikování jejího kódu do Azure.

Psaní kódu aplikace

Při psaní funkce Azure zvažte přidání těchto proměnných a kódu do funkce:

• Kód pro čtení Azure Digital Twins adresy URL služby jako proměnné prostředí nebo nastavení konfigurace. Je dobrým postupem načíst adresu URL služby z proměnné prostředí nebo nastavení aplikace,místo abyste ji do funkce zakódoval na pevném disku. Ve funkci Azure může tento kód pro čtení proměnné prostředí vypadat podobně jako tento:

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

  Později po publikování funkce vytvoříte a nastavíte hodnotu proměnné prostředí pro čtení tohoto kódu. Pokyny k tomu, jak to udělat, najdete v části Konfigurace nastavení aplikace.

• Statická proměnná pro instanci HttpClient. Vytvoření objektu HttpClient je poměrně nákladné, takže ho pravděpodobně budete chtít vytvořit jednou s ověřovacím kódem, abyste se vyhnuli jeho vytváření pro každé vyvolání funkce.

  private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
  

• Přihlašovací údaje spravované identity. Vytvořte přihlašovací údaje spravované identity, které vaše funkce použije pro přístup k Azure Digital Twins.

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

  Později po publikování funkce budete mít jistotu, že identita funkce má oprávnění pro přístup k Azure Digital Twins API. Pokyny k tomu, jak to provést, najdete v tématu Přiřazení přístupové role.

• Místní proměnná DigitalTwinsClient. Do funkce přidejte proměnnou , která bude obsahovat Azure Digital Twins instanci klienta. Nedělejte tuto proměnnou statickou uvnitř třídy.

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

• Kontrola hodnoty null pro adtInstanceUrl Přidejte kontrolu hodnoty null a pak logiku funkce zabalte do bloku try/catch, aby se zachytály všechny výjimky.

Po přidání těchto proměnných do funkce může kód funkce vypadat jako v následujícím příkladu.

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

Až budete s kódem funkce hotovi, včetně přidání ověřování a logiky funkce, publikujte aplikaci do Azure.

Konfigurace publikované aplikace

Nakonec proveďte následující kroky konfigurace publikované funkce Azure, abyste se ujistili, že má přístup k vaší Azure Digital Twins instanci.

Spusťte následující příkazy v Azure Cloud Shell nebo v místním rozhraní příkazového řádku Azure.

Přiřazení role přístupu

Funkce Azure vyžaduje předání nosných tokenů. Abyste se ujistili, že je předaný token nosiče, udělte aplikaci funkcí roli vlastníka dat digitálních vláken Azure pro instanci digitálního vlákna Azure, která poskytne oprávnění aplikace Function App k provádění aktivit datových roviny instance.

1. Pomocí následujícího příkazu můžete zobrazit podrobnosti o identitě spravované systémemvaší funkce. Poznamenejte si principalId pole ve výstupu. Toto ID použijete k tomu, abyste se mohli podívat na funkci, abyste mohli udělit oprávnění v dalším kroku.

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

   Poznámka

   Pokud je výsledek prázdný místo zobrazení podrobností identity, vytvořte novou systémově spravovanou identitu pro funkci pomocí tohoto příkazu:

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

   Výstup zobrazí podrobnosti o identitě, včetně principalId hodnoty požadované pro další krok.

2. Použijte principalId hodnotu v následujícím příkazu, abyste funkci poskytli roli vlastníka dat v Azure pro vaši instanci digitálních vláken Azure.

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

Konfigurace nastavení aplikace

V dalším kroku nastavte pro tuto funkci adresu URL vaší instance digitálního vlákna Azure , a to tak, že nastavíte pro ni proměnnou prostředí .

Následující příkaz nastaví proměnnou prostředí pro adresu URL vaší instance, kterou vaše funkce použije, kdykoli bude potřebovat přístup k instanci.

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

Ověřování mezi tenanty

Azure Digital Twins je služba, která podporuje pouze jednoho tenanta Azure Active Directory (Azure AD):hlavního tenanta z předplatného, ve kterém Azure Digital Twins instance služby.

V důsledku toho požadavky na rozhraní API pro digitální vlákna Azure vyžadují uživatele nebo instanční objekt, který je součástí stejného tenanta, kde se nachází instance digitálního vlákna Azure. Aby se zabránilo zlomyslné kontrole koncových bodů digitálních vláken Azure, budou žádosti s přístupovými tokeny mimo původního tenanta vracet chybové zprávy "404 Sub-Domain Nenalezeno". Tato chyba se vrátí i v případě , že se uživateli nebo instančnímu objektu dostala role data Reader pro digitální vlákna Azure nebo služba Azure Digital data Reader prostřednictvím spolupráce Azure AD B2B .

Pokud potřebujete přístup ke své instanci Azure Digital Twins pomocí objektu služby nebo uživatelského účtu, který patří do jiného tenanta z instance, můžete mít každou federovanou identitu z jiného tenanta, která si vyžádá token z "domovského" tenanta instance Azure Digital Twins.

To lze provést pomocí následujícího příkazu rozhraní příkazového řádku, kde <home-tenant-ID> je ID tenanta Azure AD, který obsahuje instanci digitálních vláken Azure:

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

Po vyžádání bude identita přijímat token vydaný pro https://digitaltwins.azure.net prostředek služby Azure AD, který má stejnou deklaraci ID tenanta pro instanci digitálních vláken Azure. Použití tohoto tokenu v požadavcích rozhraní API nebo s vaším Azure.Identity kódem by mělo umožňovat federované identitě přístup k prostředku digitálních vláken Azure.

V možnostech přihlašovacích údajů v kódu můžete také zadat domovského tenanta.

Následující příklad ukazuje, jak nastavit hodnotu ID tenanta pro InteractiveBrowserTenantId v DefaultAzureCredential možnostech:

K dispozici jsou podobné možnosti pro nastavení tenanta pro ověřování pomocí sady Visual Studio a Visual Studio Code. Další informace o dostupných možnostech najdete v dokumentaci k DefaultAzureCredentialOptions.

Další metody přihlašovacích údajů

Pokud výše uvedené zvýrazněné scénáře ověřování nepokryje potřeby vaší aplikace, můžete prozkoumat další typy ověřování, které nabízí Microsoft identity platform. Dokumentace k této platformě se věnuje více scénářům ověřování uspořádaným podle typu aplikace.

Další kroky

Přečtěte si další informace o tom, jak zabezpečení funguje Azure Digital Twins:

• Zabezpečení pro řešení Azure Digital Twins

Nebo teď, když je nastavené ověřování, přejděte k vytváření a správě modelů ve vaší instanci:

• Správa modelů DTDL