Dela via

Autentisering och auktorisering för Azure Time Series Insights API

  • Artikel

Kommentar

Time Series Insights-tjänsten dras tillbaka den 7 juli 2024. Överväg att migrera befintliga miljöer till alternativa lösningar så snart som möjligt. Mer information om utfasning och migrering finns i vår dokumentation.

Beroende på dina affärsbehov kan lösningen innehålla ett eller flera klientprogram som du använder för att interagera med AZURE Time Series Insights-miljöns API:er. Azure Time Series Insights utför autentisering med hjälp av Microsoft Entra-säkerhetstoken baserat på OAUTH 2.0. För att autentisera dina klienter måste du skaffa en ägartoken med rätt behörigheter och skicka den tillsammans med dina API-anrop. Det här dokumentet beskriver flera metoder för att hämta autentiseringsuppgifter som du kan använda för att hämta en ägartoken och autentisera, inklusive användning av hanterad identitet och registrering av Microsoft Entra-appar.

Hanterade identiteter

I följande avsnitt beskrivs hur du använder en hanterad identitet från Microsoft Entra-ID för att få åtkomst till Azure Time Series Insights-API:et. I Azure innebär hanterade identiteter att utvecklare slipper hantera autentiseringsuppgifter genom att ange en identitet för Azure-resursen i Microsoft Entra ID och sedan använda identiteten för att erhålla Microsoft Entra. Här är några av fördelarna med att använda hanterade identiteter:

  • Du behöver inte hantera autentiseringsuppgifter. Autentiseringsuppgifter är inte ens tillgängliga för dig.
  • Du kan använda hanterade identiteter för att autentisera till alla Azure-tjänster som stöder Microsoft Entra-autentisering, inklusive Azure Key Vault.
  • Hanterade identiteter kan användas utan extra kostnad.

Mer information om de två typerna av hanterade identiteter finns i Vad är hanterade identiteter för Azure-resurser?

Du kan använda hanterade identiteter från:

  • Virtuella Azure-datorer
  • Azure App Services
  • Azure Functions
  • Azure Container-instanser
  • och mer ...

Se Azure-tjänster som stöder hanterade identiteter för Azure-resurser för den fullständiga listan.

Registrering av Microsoft Entra-appar

Vi rekommenderar att du använder hanterade identiteter när det är möjligt så att du inte behöver hantera autentiseringsuppgifter. Om klientprogrammet inte finns på en Azure-tjänst som stöder hanterade identiteter kan du registrera ditt program med en Microsoft Entra-klientorganisation. När du registrerar ditt program med Microsoft Entra-ID skapar du en identitetskonfiguration för ditt program som gör att det kan integreras med Microsoft Entra-ID. När du registrerar en app i Azure-portalen väljer du om det är en enda klientorganisation (endast tillgänglig i din klientorganisation) eller flera klientorganisationer (tillgänglig i andra klienter) och kan också ange en omdirigerings-URI (där åtkomsttoken skickas till).

När du har slutfört appregistreringen har du en globalt unik instans av appen (programobjektet) som finns i din hemklient eller katalog. Du har också ett globalt unikt ID för din app (appen eller klient-ID:t). I portalen kan du sedan lägga till hemligheter eller certifikat och omfång för att få din app att fungera, anpassa appens varumärkesanpassning i inloggningsdialogrutan med mera.

Om du registrerar ett program i portalen skapas ett programobjekt och ett objekt för tjänstens huvudnamn automatiskt i din hemklientorganisation. Om du registrerar/skapar ett program med hjälp av Microsoft Graph-API:erna är det ett separat steg att skapa objektet för tjänstens huvudnamn. Ett objekt för tjänstens huvudnamn krävs för att begära token.

Se till att granska säkerhetschecklistan för ditt program. Vi rekommenderar att du använder autentiseringsuppgifter för certifikat, inte autentiseringsuppgifter för lösenord (klienthemligheter).

Mer information finns i Program- och tjänstobjekt i Microsoft Entra-ID .

Steg 1: Skapa din hanterade identitet eller appregistrering

När du har identifierat om du ska använda en hanterad identitet eller appregistrering är nästa steg att etablera en.

Hanterad identitet

De steg som du använder för att skapa en hanterad identitet varierar beroende på var koden finns och om du skapar en systemtilldelad eller användartilldelad identitet. Läs Hanterade identitetstyper för att förstå skillnaden. När du har valt din identitetstyp letar du upp och följer rätt självstudie i dokumentationen om Hanterade Microsoft Entra-identiteter. Där hittar du instruktioner för hur du konfigurerar hanterade identiteter för:

Programregistrering

Följ stegen i Registrera ett program.

  • När du har valt rätt plattform i steg 4 i Konfigurera plattformsinställningar konfigurerar du dina omdirigerings-URI:er och åtkomsttoken på sidopanelen till höger om användargränssnittet.

    • Omdirigerings-URI:er måste matcha den adress som anges av autentiseringsbegäran:

      • För appar som finns i en lokal utvecklingsmiljö väljer du Offentlig klient (mobil och skrivbord). Se till att ställa in den offentliga klienten på Ja.
      • För Ensidesappar som finns i Azure App Service väljer du Webb.

    • Avgör om en utloggnings-URL är lämplig.

    • Aktivera det implicita beviljandeflödet genom att kontrollera Åtkomsttoken eller ID-token.

    Skapa omdirigerings-URI:er

    Klicka på Konfigurera och sedan på Spara.

  • Associera din Microsoft Entra-app Azure Time Series Insights. Välj API-behörigheter>Lägg till en behörighets-API>:er som min organisation använder.

    Associera ett API med din Microsoft Entra-app

    Skriv Azure Time Series Insights i sökfältet och välj Azure Time Series Insightssedan .

  • Ange sedan den typ av API-behörighet som din app kräver. Som standard markeras delegerade behörigheter . Välj en behörighetstyp och välj sedan Lägg till behörigheter.

    Ange vilken typ av API-behörighet din app kräver

  • Lägg till autentiseringsuppgifter om programmet anropar miljöns API:er som sig själva. Med autentiseringsuppgifter kan programmet autentiseras som sig självt, vilket inte kräver någon interaktion från en användare vid körning.

Steg 2: Bevilja åtkomst

När din Azure Time Series Insights-miljö tar emot en begäran verifieras först anroparens ägartoken. Om valideringen godkänns har anroparen autentiserats och sedan görs en annan kontroll för att säkerställa att anroparen har behörighet att utföra den begärda åtgärden. Om du vill auktorisera alla användare eller tjänstens huvudnamn måste du först ge dem åtkomst till miljön genom att tilldela dem rollen Läsare eller Deltagare.

  • Om du vill bevilja åtkomst via azure-portalens användargränssnitt följer du anvisningarna i artikeln Bevilja dataåtkomst till en miljö . När du väljer användaren kan du söka efter den hanterade identiteten eller appregistreringen med dess namn eller ID.

  • Om du vill bevilja åtkomst med hjälp av Azure CLI kör du följande kommando. I dokumentationen här finns en fullständig lista över kommandon som är tillgängliga för att hantera åtkomst.

    az tsi access-policy create --name "ap1" --environment-name "env1" --description "some description" --principal-object-id "aGuid" --roles Reader Contributor --resource-group "rg1"

Kommentar

Timeseriesinsights-tillägget för Azure CLI kräver version 2.11.0 eller senare. Tillägget installeras automatiskt första gången du kör ett az tsi access-policy-kommando. Läs mer om tillägg.

Steg 3: Begära token

När din hanterade identitet eller appregistrering har etablerats och tilldelats en roll är du redo att börja använda den för att begära OAuth 2.0-ägartoken. Vilken metod du använder för att hämta en token varierar beroende på var koden finns och vilket språk du väljer. När du anger resursen (kallas även "målgruppen" för token) kan du identifiera Azure Time Series Insights med dess URL eller GUID:

  • https://api.timeseries.azure.com/
  • 120d688d-1518-4cf7-bd38-182f158850b6

Viktigt!

Om du använder URL:en som resurs-ID måste token utfärdas exakt till https://api.timeseries.azure.com/. Det avslutande snedstrecket krävs.

  • Om du använder Postman blir din AuthURL därför: https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default
  • https://api.timeseries.azure.com/ är giltigt men https://api.timeseries.azure.com är inte det.

Hanterade identiteter

När du kommer åt från Azure App Service eller Functions följer du vägledningen i Hämta token för Azure-resurser.

För .NET-program och -funktioner är det enklaste sättet att arbeta med en hanterad identitet via Azure Identity-klientbiblioteket för .NET. Det här klientbiblioteket är populärt på grund av dess enkelhet och säkerhetsfördelar. Utvecklare kan skriva kod en gång och låta klientbiblioteket bestämma hur de ska autentisera baserat på programmiljön – oavsett om det är på en utvecklararbetsstation som använder ett utvecklarkonto eller distribueras i Azure med hjälp av en hanterad tjänstidentitet. För migreringsvägledning från föregående AppAuthentication-bibliotek läser du AppAuthentication till Azure.Identity Migration Guidance.

Begär en token för Azure Time Series Insights med hjälp av C# och Azure Identity-klientbiblioteket för .NET:

using Azure.Identity;
// ...
var credential = new DefaultAzureCredential();
var token = credential.GetToken(
new Azure.Core.TokenRequestContext(
    new[] { "https://api.timeseries.azure.com/" }));
var accessToken = token.Token;

Appregistrering

MSAL kan användas i många programscenarier, inklusive, men inte begränsat till:

För C#-exempelkod som visar hur du hämtar en token som en appregistrering och frågar efter data från en Gen2-miljö, kan du visa exempelappen på GitHub

Viktigt!

Om du använder Azure Active Directory Authentication Library (ADAL) migrerar du till MSAL.

Vanliga rubriker och parametrar

I det här avsnittet beskrivs vanliga HTTP-begärandehuvuden och parametrar som används för att göra frågor mot Azure Time Series Insights Gen1- och Gen2-API:er. API-specifika krav beskrivs mer detaljerat i referensdokumentationen för REST API för Azure Time Series Insights.

Dricks

Läs referensen för Azure REST API för att lära dig mer om hur du använder REST-API:er, gör HTTP-begäranden och hanterar HTTP-svar.

HTTP-rubriker

Nödvändiga begärandehuvuden beskrivs nedan.

Obligatoriskt begärandehuvud beskrivning
Auktorisering Om du vill autentisera med Azure Time Series Insights måste en giltig OAuth 2.0 Bearer-token skickas i auktoriseringshuvudet.

Dricks

Läs den värdbaserade Azure Time Series Insights-klientens SDK-exempelvisualisering för att lära dig hur du autentiserar med Azure Time Series Insights-API:erna programmatiskt med Hjälp av JavaScript Client SDK tillsammans med diagram och diagram.

Valfria begärandehuvuden beskrivs nedan.

Valfritt begärandehuvud beskrivning
Innehållstyp endast application/json stöds.
x-ms-client-request-id Ett klientbegärans-ID. Tjänsten registrerar det här värdet. Tillåter att tjänsten spårar åtgärder mellan tjänster.
x-ms-client-session-id Ett klientsessions-ID. Tjänsten registrerar det här värdet. Gör att tjänsten kan spåra en grupp relaterade åtgärder mellan tjänster.
x-ms-client-application-name Namnet på programmet som genererade den här begäran. Tjänsten registrerar det här värdet.

Valfria men rekommenderade svarshuvuden beskrivs nedan.

Svarsrubrik beskrivning
Innehållstyp Endast application/json stöds.
x-ms-request-id Servergenererat begärande-ID. Kan användas för att kontakta Microsoft för att undersöka en begäran.
x-ms-property-not-found-behavior Valfritt svarshuvud för GA API. Möjliga värden är ThrowError (standard) eller UseNull.

HTTP-parametrar

Dricks

Mer information om nödvändig och valfri frågeinformation finns i referensdokumentationen.

Obligatoriska URL-frågesträngsparametrar beror på API-versionen.

Frisläpp API-versionsvärden
Gen1 api-version=2016-12-12
Gen2 api-version=2020-07-31

Valfria URL-frågesträngsparametrar inkluderar att ange en tidsgräns för KÖRNINGstider för HTTP-begäranden.

Valfri frågeparameter beskrivning Version
timeout=<timeout> Tidsgräns på serversidan för körning av HTTP-begäranden. Gäller endast API:erna Hämta miljöhändelser och Hämta miljöaggregeringar . Timeout-värdet ska vara i ISO 8601-varaktighetsformat, till exempel "PT20S" och bör ligga i intervallet 1-30 s. Standardvärdet är 30 s. Gen1
storeType=<storeType> För Gen2-miljöer med varmt arkiv aktiverat kan frågan köras antingen på WarmStore eller ColdStore. Den här parametern i frågan definierar vilket lager frågan ska köras på. Om den inte har definierats körs frågan i det kalla arkivet. För att köra frågor mot det varma arkivet måste storeType vara inställt på WarmStore. Om den inte har definierats körs frågan mot det kalla arkivet. Gen2

Nästa steg

  • För exempelkod som anropar Gen1 Azure Time Series Insights-API:et läser du Query Gen1-data med C#.

  • För exempelkod som anropar Kodexempel för Gen2 Azure Time Series Insights API läser du Query Gen2-data med C#.

  • Information om API-referens finns i referensdokumentationen för Fråge-API.