Ügyfélalkalmazás-hitelesítési kód írása

Cikk
03/25/2023

Miután beállított egy Azure Digital Twins-példányt és -hitelesítést, létrehozhat egy ügyfélalkalmazást, amelyet használni fog a példány használatához. Miután beállított egy kezdő ügyfélprojektet, kódot kell írnia az ügyfélalkalmazásban, hogy hitelesítse azt az Azure Digital Twins-példányon.

Az Azure Digital Twins az OAUTH 2.0-n alapuló Microsoft Entra biztonsági jogkivonatokkal hitelesít. Az SDK hitelesítéséhez le kell szereznie egy tulajdonosi jogkivonatot a megfelelő engedélyekkel az Azure Digital Twinshez, és továbbítania kell azt az API-hívásokkal együtt.

Ez a cikk bemutatja, hogyan szerezhet be hitelesítő adatokat az Azure.Identity ügyfélkódtár használatával. Bár ez a cikk c#-kódpéldákat mutat be, például azt, hogy mit ír a .NET (C#) SDK-hoz, a használt SDK-któl függetlenül használhat egy verziót Azure.Identity (az Azure Digital Twinshez elérhető SDK-król további információt az Azure Digital Twins API-k és az SDK-k című témakörben talál.

Előfeltételek

Először végezze el a példány és a hitelesítés beállításának lépéseit. Ez a beállítás biztosítja, hogy rendelkezik Egy Azure Digital Twins-példánysal, és a felhasználó rendelkezik hozzáférési engedélyekkel. A beállítás után készen áll az ügyfélalkalmazás kódjának írására.

A folytatáshoz szüksége lesz egy ügyfélalkalmazás-projektre, amelyben megírja a kódot. Ha még nincs beállítva ügyfélalkalmazás-projekt, hozzon létre egy alapszintű projektet az ön által választott nyelven, amelyet ezzel az oktatóanyaggal használhat.

Hitelesítés az Azure.Identity-kódtár használatával

Azure.Identity Egy ügyfélkódtár, amely számos hitelesítőadat-lekérési módszert biztosít, amelyekkel lekérheti a tulajdonosi jogkivonatot, és hitelesítheti az SDK-val. Bár ez a cikk példákat tartalmaz a C#-ban, számos nyelvet tekinthet meg Azure.Identity , többek között...

Három gyakori hitelesítőadat-lekérési módszer a Azure.Identity következő:

A DefaultAzureCredential alapértelmezett TokenCredential hitelesítési folyamatot biztosít az Azure-ban üzembe helyezett alkalmazásokhoz, és ez a helyi fejlesztéshez ajánlott választás. A cikkben javasolt másik két módszer kipróbálása is engedélyezhető; ez körbefut, ManagedIdentityCredential és egy konfigurációs változóval is elérhető InteractiveBrowserCredential .
A ManagedIdentityCredential jól működik olyan esetekben, amikor felügyelt identitásokra (MSI) van szüksége, és jó választás az Azure Functions használatához és az Azure-szolgáltatásokban való üzembe helyezéshez.
Az InteractiveBrowserCredential interaktív alkalmazásokhoz készült, és hitelesített SDK-ügyfél létrehozásához használható.

A cikk további része bemutatja, hogyan használhatja ezeket a metódusokat a .NET (C#) SDK-val.

Azure.Identity hozzáadása a .NET-projekthez

A .NET-projekt hitelesítésének Azure.Identitybeállításához hajtsa végre a következő lépéseket:

Vegye fel az SDK-csomagot Azure.DigitalTwins.Core és a Azure.Identity csomagot a projektbe. A választott eszközöktől függően a csomagokat a Visual Studio csomagkezelőjével vagy a dotnet parancssori eszközzel is felveheti.

Adja hozzá a következő utasításokat a projektkódhoz:

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

Ezután adjon hozzá kódot a hitelesítő adatok beszerzéséhez a következő Azure.Identitymetódusok egyikével: . Az alábbi szakaszok részletesebben ismertetik az egyes műveletek használatát.

DefaultAzureCredential metódus

A DefaultAzureCredential alapértelmezett TokenCredential hitelesítési folyamatot biztosít az Azure-ban üzembe helyezett alkalmazásokhoz, és ez a helyi fejlesztéshez ajánlott választás.

Az alapértelmezett Azure-hitelesítő adatok használatához szüksége lesz az Azure Digital Twins-példány URL-címére (a kereséshez szükséges utasításokra).

Íme egy kódminta a projekthez való hozzáadásához DefaultAzureCredential :

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

Megjegyzés:

Jelenleg ismert probléma van a DefaultAzureCredential burkolóosztályt érintően, amely a hitelesítés során hibát okozhat. Ha ezt a problémát tapasztalja, a probléma megoldásához próbálja meg példányosítani DefaultAzureCredential a következő opcionális paramétert: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

A problémával kapcsolatos további információkért tekintse meg az Azure Digital Twins ismert problémáit.

Helyi Azure-hitelesítő adatok beállítása

Ezzel DefaultAzureCredentiala példával a minta hitelesítő adatokat keres a helyi környezetben, például egy Azure-bejelentkezést egy helyi Azure CLI-ben vagy a Visual Studióban vagy a Visual Studio Code-ban. Ezért helyileg kell bejelentkeznie az Azure-ba ezen mechanizmusok egyikével a minta hitelesítő adatainak beállításához.

Ha a Visual Studio vagy a Visual Studio Code használatával futtat kódmintákat, győződjön meg arról , hogy ugyanazokkal az Azure-hitelesítő adatokkal jelentkezett be a szerkesztőbe , amelyeket az Azure Digital Twins-példány eléréséhez használni szeretne. Ha helyi CLI-ablakot használ, futtassa a parancsot az az login Azure-fiókba való bejelentkezéshez. Ezt követően a kódminta futtatásakor automatikusan hitelesíteni kell.

ManagedIdentityCredential metódus

A ManagedIdentityCredential metódus jól működik azokban az esetekben, amikor felügyelt identitásokra (MSI) van szüksége – például az Azure Functions-hitelesítéskor.

Ez azt jelenti, hogy ugyanabban a projektben használhatja ManagedIdentityCredential , mint DefaultAzureCredential vagy InteractiveBrowserCredentiala projekt egy másik részének hitelesítéséhez.

Az alapértelmezett Azure-hitelesítő adatok használatához szüksége lesz az Azure Digital Twins-példány URL-címére (a kereséshez szükséges utasításokra). Szükség lehet egy alkalmazásregisztrációra és a regisztrációs alkalmazás (ügyfél) azonosítójára is.

Egy Azure-függvényben a következő módon használhatja a felügyelt identitás hitelesítő adatait:

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

A hitelesítő adatok létrehozásakor a paraméter üresen hagyása a fent látható módon visszaadja a függvényalkalmazás rendszer által hozzárendelt identitásának hitelesítő adatait, ha rendelkezik ilyen azonosítóval. Ha ehelyett felhasználó által hozzárendelt identitást szeretne megadni, adja meg a felhasználó által hozzárendelt identitás ügyfélazonosítóját a paraméternek.

InteractiveBrowserCredential metódus

Az InteractiveBrowserCredential metódus interaktív alkalmazásokhoz készült, és létrehoz egy webböngészőt a hitelesítéshez. Ezt a módszert használhatja DefaultAzureCredential azokban az esetekben, amikor interaktív hitelesítésre van szükség.

Az interaktív böngésző hitelesítő adatainak használatához olyan alkalmazásregisztrációra lesz szüksége, amely rendelkezik az Azure Digital Twins API-k engedélyével. Az alkalmazásregisztráció beállításának lépéseit az Alkalmazásregisztráció létrehozása Azure Digital Twins-hozzáféréssel című témakörben találja. Az alkalmazásregisztráció beállítása után...

Íme egy példa arra a kódra, amely egy hitelesített SDK-ügyfelet hoz létre a használatával 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);
        }
    }
}

Megjegyzés:

Bár az ügyfél-azonosítót, a bérlőazonosítót és a példány URL-címét közvetlenül a kódba helyezheti, a fentieknek megfelelően célszerű ezeket az értékeket egy konfigurációs fájlból vagy környezeti változóból lekérni.

Az Azure Functions hitelesítése

Ez a szakasz néhány fontos konfigurációs lehetőséget tartalmaz az Azure Functions-hitelesítés kontextusában. Először az ajánlott osztályszintű változókról és hitelesítési kódról olvashat, amelyek lehetővé teszik a függvény számára az Azure Digital Twins elérését. Ezután megismerhet néhány végső konfigurációs lépést, amelyet a függvénynek végre kell hajtania a kód Azure-ban való közzététele után.

Alkalmazáskód írása

Az Azure-függvény írásakor vegye fel ezeket a változókat és kódot a függvénybe:

Kód az Azure Digital Twins szolgáltatás URL-címének környezeti változóként vagy konfigurációs beállításként való olvasásához. Ajánlott beolvasni a szolgáltatás URL-címét egy alkalmazásbeállításból/környezeti változóból, ahelyett, hogy a függvényben kódolva lenne. Egy Azure-függvényben a környezeti változó olvasására használt kód a következőképpen nézhet ki:
```
private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
```
Később, a függvény közzététele után létrehozza és be fogja állítani a kódhoz tartozó környezeti változó értékét olvasásra. Ennek módjával kapcsolatos útmutatásért ugorjon tovább az alkalmazásbeállítások konfigurálásához.
Egy httpClient-példány tárolására használt statikus változó. A HttpClient létrehozása viszonylag költséges, ezért érdemes egyszer létrehozni a hitelesítési kóddal, hogy ne hozza létre minden függvényhíváshoz.
```
private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
```
Felügyelt identitás hitelesítő adatai. Hozzon létre egy felügyelt identitás hitelesítő adatait, amelyet a függvény az Azure Digital Twins eléréséhez fog használni.
```
// 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>");
```
Ha a paramétert üresen hagyja a fent látható módon, a függvényalkalmazás rendszer által hozzárendelt identitásának hitelesítő adatait adja vissza, ha van ilyenje. Ha ehelyett felhasználó által hozzárendelt identitást szeretne megadni, adja meg a felhasználó által hozzárendelt identitás ügyfélazonosítóját a paraméternek.

Később, a függvény közzététele után győződjön meg arról, hogy a függvény identitása rendelkezik engedéllyel az Azure Digital Twins API-k eléréséhez. Ennek módjával kapcsolatos útmutatásért ugorjon előre a hozzáférési szerepkör hozzárendeléséhez.

A DigitalTwinsClient helyi változója. Adja hozzá a változót a függvényhez az Azure Digital Twins-ügyfélpéldány tárolásához. Ne tegye ezt a változót statikussá az osztályon belül.

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

Null értékű ellenőrzés az adtInstanceUrl esetében. Adja hozzá a null ellenőrzést, majd csomagolja be a függvénylogikát egy próba/fogási blokkba a kivételek elfogásához.

Miután hozzáadta ezeket a változókat egy függvényhez, a függvénykód az alábbi példához hasonlóan nézhet ki.

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

Ha végzett a függvénykóddal, beleértve a hitelesítést és a függvény logikáját, tegye közzé az alkalmazást az Azure-ban

Közzétett alkalmazás konfigurálása

Végül végezze el a következő konfigurációs lépéseket egy közzétett Azure-függvényhez, hogy biztosan hozzáférhessen az Azure Digital Twins-példányhoz.

Futtassa az alábbi parancsokat az Azure Cloud Shellben vagy egy helyi Azure CLI-ben.

Megjegyzés:

Ezt a szakaszt egy Olyan Azure-felhasználónak kell kitöltenie, aki jogosult az Azure-erőforrásokhoz való felhasználói hozzáférés kezelésére, beleértve az engedélyek megadását és delegálását. A követelménynek megfelelő gyakori szerepkörök a tulajdonos, a fiókadminisztrátor vagy a felhasználói hozzáférés Rendszergazda istrator és a közreműködő kombinációja. További információ az Azure Digital Twins-szerepkörök engedélykövetelményeiről: Példány és hitelesítés beállítása.

Hozzáférési szerepkör hozzárendelése

Az Azure-függvényhez egy tulajdonosi jogkivonatot kell átadni. A tulajdonosi jogkivonat átadásához adja meg a függvényalkalmazásnak az Azure Digital Twins-példány Azure Digital Twins-adattulajdonosi szerepkörét, amely engedélyt ad a függvényalkalmazásnak az adatsík-tevékenységek végrehajtására a példányon.

A következő paranccsal hozzon létre egy rendszer által felügyelt identitást a függvényhez (ha a függvény már rendelkezik ilyenrel, ez a parancs kinyomtatja annak részleteit). Jegyezze fel a principalId kimenet mezőjét. Ezzel az azonosítóval hivatkozhat a függvényre, így a következő lépésben engedélyeket adhat neki.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```

principalId Az alábbi paranccsal adja meg a függvény Azure Digital Twins-adattulajdonosi szerepkörét az Azure Digital Twins-példányhoz.

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

Alkalmazásbeállítások konfigurálása

Ezután tegye elérhetővé az Azure Digital Twins-példány URL-címét a függvény számára egy környezeti változó beállításával.

Tipp.

Az Azure Digital Twins-példány URL-címe úgy jön létre , hogy hozzáadja a https:// a példány gazdagépnevének elejéhez. A gazdagép nevének és a példány összes tulajdonságának megtekintéséhez futtassa a parancsot az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Az alábbi parancs beállít egy környezeti változót a példány URL-címéhez, amelyet a függvény minden alkalommal használni fog, amikor hozzá kell férnie a példányhoz.

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

Hitelesítés bérlőkön keresztül

Az Azure Digital Twins egy szolgáltatás, amely csak egy Microsoft Entra-bérlőt támogat: a fő bérlőt abból az előfizetésből, amelyben az Azure Digital Twins-példány található.

Ennek eredményeképpen az Azure Digital Twins API-khoz irányuló kérésekhez olyan felhasználóra vagy szolgáltatásnévre van szükség, amely ugyanahhoz a bérlőhöz tartozik, ahol az Azure Digital Twins-példány található. Az Azure Digital Twins-végpontok rosszindulatú vizsgálatának megakadályozása érdekében a rendszer "404 altartomány nem található" hibaüzenetet ad vissza az eredeti bérlőn kívüli hozzáférési jogkivonatokkal. Ez a hiba akkor is megjelenik, ha a felhasználó vagy szolgáltatásnév Azure Digital Twins-adattulajdonosi vagy Azure Digital Twins-adatolvasói szerepkört kapott a Microsoft Entra B2B együttműködésével.

Ha az Azure Digital Twins-példányt egy olyan szolgáltatásnévvel vagy felhasználói fiókkal kell elérnie, amely a példánytól eltérő bérlőhöz tartozik, minden egyes összevont identitás egy másik bérlőtől kérhet jogkivonatot az Azure Digital Twins-példány "otthoni" bérlőjétől.

Ennek egyik módja a következő CLI-parancs, ahol <home-tenant-ID> az Azure Digital Twins-példányt tartalmazó Microsoft Entra-bérlő azonosítója található:

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

Ezt követően az identitás megkapja a https://digitaltwins.azure.net Microsoft Entra-erőforráshoz kiadott jogkivonatot, amely egyező bérlőazonosító-jogcímet biztosít az Azure Digital Twins-példányhoz. Ha ezt a jogkivonatot API-kérésekben vagy a Azure.Identity kóddal használja, engedélyeznie kell az összevont identitás számára az Azure Digital Twins-erőforrás elérését.

Az otthoni bérlőt a kód hitelesítő adatai között is megadhatja.

Az alábbi példa bemutatja, hogyan állíthat be egy bérlőazonosító-mintaértéket InteractiveBrowserTenantId a DefaultAzureCredential beállítások között:

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

A Visual Studióval és a Visual Studio Code-tal való hitelesítéshez hasonló lehetőségek állnak rendelkezésre a bérlők beállításához. Az elérhető lehetőségekről további információt a DefaultAzureCredentialOptions dokumentációjában talál.

Egyéb hitelesítő módszerek

Ha a fenti kiemelt hitelesítési forgatókönyvek nem fedik le az alkalmazás igényeit, a Microsoft Identitásplatform más típusú hitelesítéseket is megismerhet. A platform dokumentációja több hitelesítési forgatókönyvet is tartalmaz, alkalmazástípus szerint rendezve.

Következő lépések

További információ a biztonság működéséről az Azure Digital Twinsben:

Az Azure Digital Twins-megoldások biztonsága

Vagy most, hogy a hitelesítés be van állítva, lépjen tovább a modellek létrehozására és kezelésére a példányban:

DTDL-modellek kezelése

Megosztás a következőn keresztül:

Ügyfélalkalmazás-hitelesítési kód írása

Előfeltételek

Hitelesítés az Azure.Identity-kódtár használatával

Azure.Identity hozzáadása a .NET-projekthez

DefaultAzureCredential metódus

Helyi Azure-hitelesítő adatok beállítása

ManagedIdentityCredential metódus

InteractiveBrowserCredential metódus

Az Azure Functions hitelesítése

Alkalmazáskód írása

Közzétett alkalmazás konfigurálása

Hozzáférési szerepkör hozzárendelése

Alkalmazásbeállítások konfigurálása

Hitelesítés bérlőkön keresztül

Egyéb hitelesítő módszerek

Következő lépések

Visszajelzés

További források