Freigeben über

Authentifizierung und Autorisierung für die Azure Time Series Insights-API

  • Artikel

Anmerkung

Der Time Series Insights-Dienst wird am 7. Juli 2024 eingestellt. Erwägen Sie, vorhandene Umgebungen so schnell wie möglich zu alternativen Lösungen zu migrieren. Weitere Informationen zum Veraltungsprozess und über Migration finden Sie in der Dokumentation.

Je nach Ihren Geschäftlichen Anforderungen enthält Ihre Lösung möglicherweise eine oder mehrere Clientanwendungen, die Sie für die Interaktion mit den -APIs Ihrer Azure Time Series Insights-Umgebungverwenden. Azure Time Series Insights führt die Authentifizierung mit Microsoft Entra-Sicherheitstoken basierend auf OAUTH 2.0aus. Um Ihren/Ihre Clients zu authentifizieren, müssen Sie ein Bearer-Token mit den richtigen Berechtigungen abrufen und es zusammen mit Ihren API-Aufrufen weitergeben. In diesem Dokument werden mehrere Methoden beschrieben, mit denen Sie Anmeldeinformationen abrufen können, um ein Bearer-Token zu erhalten und sich zu authentifizieren, einschließlich der Nutzung von Managed Identity und der Registrierung von Microsoft Entra Apps.

Verwaltete Identitäten

In den folgenden Abschnitten wird beschrieben, wie Sie eine verwaltete Identität von Microsoft Entra-ID verwenden, um auf die Azure Time Series Insights-API zuzugreifen. Bei Azure beseitigen verwaltete Identitäten die Notwendigkeit, dass Entwickler Anmeldeinformationen verwalten müssen, indem sie eine Identität für die Azure-Ressource in Microsoft Entra ID bereitstellen und diese zum Abrufen von Microsoft Entra-Token verwenden. Hier sind einige der Vorteile der Verwendung von verwalteten Identitäten:

  • Sie müssen keine Anmeldeinformationen verwalten. Sie haben nicht einmal Zugriff auf Anmeldeinformationen.
  • Sie können verwaltete Identitäten verwenden, um sich bei jedem Azure-Dienst zu authentifizieren, der die Microsoft Entra-Authentifizierung unterstützt, einschließlich Azure Key Vault.
  • Verwaltete Identitäten können ohne zusätzliche Kosten verwendet werden.

Weitere Informationen zu den beiden Arten von verwalteten Identitäten finden Sie unter Was sind verwaltete Identitäten für Azure-Ressourcen?

Sie können verwaltete Identitäten von Ihren verwenden.

  • Azure-VMs
  • Azure App Services
  • Azure-Funktionen
  • Azure-Containerinstanzen
  • und mehr ...

Die vollständige Liste finden Sie unter Azure-Dienste, die verwaltete Identitäten für Azure-Ressourcen unterstützen.

Microsoft Entra-App-Registrierung

Es wird empfohlen, verwaltete Identitäten nach Möglichkeit zu verwenden, damit Sie keine Anmeldeinformationen verwalten müssen. Wenn Ihre Clientanwendung nicht in einem Azure-Dienst gehostet wird, der verwaltete Identitäten unterstützt, können Sie Ihre Anwendung bei einem Microsoft Entra-Mandanten registrieren. Wenn Sie Ihre Anwendung bei Microsoft Entra ID registrieren, erstellen Sie eine Identitätskonfiguration für Ihre Anwendung, mit der sie in Microsoft Entra ID integriert werden kann. Wenn Sie eine App im Azure-Portalregistrieren, wählen Sie, ob es sich um einen einzelnen Mandanten (nur in Ihrem Mandanten zugänglich) oder um mehrere Mandanten (zugänglich in mehreren Mandanten) handelt und können optional einen Umleitungs-URI festlegen, an die das Zugriffstoken gesendet wird.

Wenn Sie die App-Registrierung abgeschlossen haben, verfügen Sie über eine global eindeutige Instanz der App (das Anwendungsobjekt), die sich innerhalb Ihres Heimmandanten oder Verzeichnisses befindet. Außerdem verfügen Sie über eine global eindeutige ID für Ihre App (die App oder Client-ID). Im Portal können Sie dann geheime Schlüssel oder Zertifikate und Bereiche hinzufügen, damit Ihre App funktioniert, das Branding Ihrer App im Anmeldedialogfeld anpassen und vieles mehr.

Wenn Sie eine Anwendung im Portal registrieren, werden automatisch ein Anwendungsobjekt sowie ein Dienstprinzipalobjekt in Ihrem Heimmandanten erstellt. Wenn Sie eine Anwendung mithilfe der Microsoft Graph-APIs registrieren/erstellen, ist das Erstellen des Dienstprinzipalobjekts ein separater Schritt. Zum Anfordern von Token ist ein Dienstprinzipalobjekt erforderlich.

Überprüfen Sie unbedingt die Sicherheitscheckliste für Ihre Anwendung. Als empfohlene Vorgehensweise sollten Sie Zertifikatsdatenund nicht kennwortbasierte Anmeldeinformationen (Client-Geheimnisse) verwenden.

Weitere Informationen finden Sie unter Anwendungs- und Dienstprinzipalobjekte in Microsoft Entra ID.

Schritt 1: Erstellen Ihrer verwalteten Identität oder App-Registrierung

Nachdem Sie festgestellt haben, ob Sie eine verwaltete Identität oder eine App-Registrierung verwenden, besteht der nächste Schritt darin, diese bereitzustellen.

Verwaltete Identität

Die Schritte, die Sie zum Erstellen einer verwalteten Identität verwenden, variieren je nachdem, wo sich Ihr Code befindet und ob Sie eine zugewiesene System- oder Benutzeridentität erstellen. Lesen Sie Managed Identity Types, um den Unterschied zu verstehen. Nachdem Sie Ihren Identitätstyp ausgewählt haben, suchen Und folgen Sie dem richtigen Lernprogramm in der von Microsoft Entra verwalteten Identitäten Dokumentation. Dort finden Sie Anweisungen zum Konfigurieren verwalteter Identitäten für:

Anwendungsregistrierung

Führen Sie die unter Registrieren einer Anwendungaufgeführten Schritte aus.

  • Nachdem Sie die entsprechende Plattform in Schritt 4 von Konfigurieren von Plattform--Einstellungen ausgewählt haben, konfigurieren Sie Ihre Umleitungs-URIs und Zugriffstoken rechts neben der Benutzeroberfläche.

    • Umleitungs-URIs müssen mit der von der Authentifizierungsanforderung angegebenen Adresse übereinstimmen:

      • Wählen Sie für Apps, die in einer lokalen Entwicklungsumgebung gehostet werden, den Öffentlichen Client (mobiler & Desktop)aus. Stellen Sie sicher, dass öffentlicher Client auf Jafestgelegt ist.
      • Wählen Sie für Single-Page Apps, die in Azure App Service gehostet werden, Webaus.

    • Ermitteln Sie, ob eine Abmelde-URL geeignet ist.

    • Aktivieren Sie den impliziten Genehmigungsfluss, indem Sie Zugriffstoken oder ID-Tokenüberprüfen.

    Erstellen von Umleitungs-URIs

    Klicken Sie auf Konfigurieren, dann auf Speichern.

  • Ordnen Sie Ihre Microsoft Entra-App Azure Time Series Insights zu. Wählen Sie API-Berechtigungen>Eine Berechtigung hinzufügen>APIs, die meine Organisation verwendet.

    Zuordnen einer API zu Ihrer Microsoft Entra-App

    Geben Sie Azure Time Series Insights in die Suchleiste ein, und wählen Sie dann Azure Time Series Insightsaus.

  • Geben Sie als Nächstes die Art der API-Berechtigung an, die Ihre App benötigt. Standardmäßig werden delegierte Berechtigungen hervorgehoben. Wählen Sie dann einen Berechtigungstyp aus, und wählen Sie Berechtigungen hinzufügenaus.

    Geben Sie die Art der API-Berechtigung an, die Ihre App benötigt

  • Fügen Sie Anmeldeinformationen hinzu, wenn die Anwendung die APIs Ihrer Umgebung in eigenem Namen aufruft. Anmeldeinformationen ermöglichen es Ihrer Anwendung, sich als sich selbst zu authentifizieren, ohne dass eine Interaktion von einem Benutzer zur Laufzeit erforderlich ist.

Schritt 2: Gewähren von Zugriff

Wenn Ihre Azure Time Series Insights-Umgebung eine Anforderung empfängt, wird zuerst das Bearertoken des Aufrufers überprüft. Wenn die Überprüfung erfolgreich ist, wurde der Aufrufer authentifiziert, und dann wird eine weitere Überprüfung durchgeführt, um sicherzustellen, dass der Anrufer berechtigt ist, die angeforderte Aktion auszuführen. Um einen Beliebigen Benutzer- oder Dienstprinzipal zu autorisieren, müssen Sie ihm zuerst Zugriff auf die Umgebung gewähren, indem Sie ihm entweder die Rolle "Leser" oder "Mitwirkender" zuweisen.

  • Um Zugriff über die Azure-Portal UI zu gewähren, folgen Sie den Anweisungen im Artikel Gewähren des Datenzugriffs auf eine Umgebung. Wenn Sie den Benutzer auswählen, können Sie anhand des Namens oder der ID nach der verwalteten Identität oder App-Registrierung suchen.

  • Führen Sie den folgenden Befehl aus, um zugriff über die Azure CLI zu gewähren. Lesen Sie die Dokumentation hier, um die vollständige Liste der Befehle zu erhalten, die zum Verwalten des Zugriffs verfügbar sind.

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

Anmerkung

Die Timeseriesinsights-Erweiterung für Azure CLI erfordert Version 2.11.0 oder höher. Die Erweiterung wird automatisch installiert, wenn Sie einen az tsi-Zugriffsrichtlinienbefehl zum ersten Mal ausführen. Erfahren Sie mehr über Erweiterungen.

Schritt 3: Token anfordern

Nachdem Ihre verwaltete Identität oder App-Registrierung bereitgestellt und eine Rolle zugewiesen wurde, können Sie damit beginnen, OAuth 2.0-Bearertoken anzufordern. Die Methode, die Sie zum Abrufen eines Tokens verwenden, unterscheidet sich je nachdem, wo Ihr Code gehostet wird und welche Sprache Sie auswählen. Wenn Sie die Ressource (auch als "Zielgruppe" des Tokens bezeichnet) angeben, können Sie Azure Time Series Insights anhand der URL oder GUID identifizieren:

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

Wichtig

Wenn Sie die URL als Ressourcen-ID verwenden, muss das Token genau an https://api.timeseries.azure.com/vergeben werden. Der abschließende Schrägstrich ist erforderlich.

  • Wenn Sie Postman verwenden, lautet Ihre AuthURL daher wie folgt: https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default
  • https://api.timeseries.azure.com/ ist gültig, aber https://api.timeseries.azure.com nicht.

Verwaltete Identitäten

Wenn Sie aus dem Azure App Service oder Azure Functions zugreifen, folgen Sie der Anleitung im Abschnitt Abrufen von Tokens für Azure-Ressourcen.

Für .NET-Anwendungen und -Funktionen besteht die einfachste Möglichkeit, mit einer verwalteten Identität zu arbeiten, über die Azure Identity-Clientbibliothek für .NET. Diese Clientbibliothek ist aufgrund ihrer Einfachheit und sicherheitsrelevanten Vorteile beliebt. Entwickler können Code einmal schreiben und der Clientbibliothek überlassen, wie sie die Authentifizierung basierend auf der Anwendungsumgebung durchführt – sei es auf einer Entwicklerarbeitsstation, die das Konto eines Entwicklers verwendet, oder in Azure, wo eine verwaltete Dienstidentität genutzt wird. Informationen zum Migrationsleitfaden von der Vorgänger-Bibliothek AppAuthentication lesen Sie unter AppAuthentication zu Azure.Identity Migration Guidance.

Anfordern eines Tokens für Azure Time Series Insights mit C# und der Azure Identity-Clientbibliothek 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;

App-Registrierung

MSAL kann in vielen Anwendungsszenarien verwendet werden, einschließlich, aber nicht beschränkt auf:

Für C#-Beispielcode, der zeigt, wie ein Token als App-Registrierung erfasst und Daten aus einer Gen2-Umgebung abgefragt werden, sehen Sie sich die Beispiel-App auf GitHub an.

Wichtig

Wenn Sie die Azure Active Directory-Authentifizierungsbibliothek (ADAL) verwenden, zu MSALmigrieren.

Allgemeine Kopfzeilen und Parameter

In diesem Abschnitt werden allgemeine HTTP-Anforderungsheader und Parameter beschrieben, mit denen Abfragen für die Azure Time Series Insights Gen1- und Gen2-APIs ausgeführt werden. API-spezifische Anforderungen werden ausführlicher in der Azure Time Series Insights REST API-Referenzdokumentationbehandelt.

Tipp

Lesen Sie die Azure REST-API-Referenz, um mehr darüber zu erfahren, wie REST-APIs verwendet, HTTP-Anforderungen gesendet und HTTP-Antworten behandelt werden.

HTTP-Header

Die erforderlichen Anforderungsheader werden unten beschrieben.

Erforderlicher Anforderungsheader Beschreibung
Ermächtigung Um sich mit Azure Time Series Insights zu authentifizieren, muss ein gültiges OAuth 2.0 Bearer-Token im Authorization-Headerübergeben werden.

Tipp

Sehen Sie sich die gehostete Beispielvisualisierung des Azure Time Series Insights-Client-SDK an, um zu lernen, wie man sich mit den Azure Time Series Insights-APIs programmgesteuert mithilfe des JavaScript Client SDK zusammen mit Diagrammen und Grafiken authentifiziert.

Optionale Anforderungsheader werden unten beschrieben.

Optionaler Anforderungsheader Beschreibung
Inhaltstyp nur application/json wird unterstützt.
x-ms-client-request-id Eine Kundenanforderungs-ID. Der Dienst zeichnet diesen Wert auf. Ermöglicht dem Dienst das Nachverfolgen des Vorgangs über Dienste hinweg.
x-ms-client-session-id Eine Clientsitzungs-ID. Der Dienst zeichnet diesen Wert auf. Ermöglicht dem Dienst die Ablaufverfolgung einer Gruppe zusammengehörender Vorgänge über Dienste hinweg.
x-ms-client-application-name Name der Anwendung, die diese Anforderung generiert hat. Der Dienst zeichnet diesen Wert auf.

Optionale, aber empfohlene Antwortheader werden unten beschrieben.

Antwortkopfzeile Beschreibung
Inhaltstyp Nur application/json wird unterstützt.
x-ms-request-id Vom Server generierte Anforderungs-ID. Kann verwendet werden, um Microsoft zu kontaktieren, um eine Anfrage zu untersuchen.
x-ms-property-not-found-behavior (Eigenschaft-nicht-gefunden-Verhalten) Optionaler GA-API-Antwortheader. Mögliche Werte sind ThrowError (Standard) oder UseNull.

HTTP-Parameter

Trinkgeld

Weitere Details zu notwendigen und optionalen Abfrageparametern finden Sie in der Referenzdokumentation .

Erforderliche URL-Abfragezeichenfolgenparameter sind von der API-Version abhängig.

Freigabe API-Versionswerte
Gen1 api-version=2016-12-12
Gen2 api-version=2020-07-31

Optionale URL-Abfragezeichenfolgenparameter umfassen das Festlegen eines Timeouts für HTTP-Anforderungsausführungszeiten.

Optionaler Abfrageparameter Beschreibung Version
timeout=<timeout> Timeout auf Serverseite bei der Ausführung einer HTTP-Anforderung. Gilt nur für die APIs Get Environment Events und Get Environment Aggregates. Der Timeoutwert sollte im ISO 8601-Dauerformat vorliegen, z. B. "PT20S", und sollte sich im Bereich 1-30 sbefinden. Der Standardwert ist 30 s. Gen1
storeType=<storeType> Für Gen2-Umgebungen mit aktiviertem Warmspeicher kann die Abfrage entweder auf dem WarmStore oder ColdStoreausgeführt werden. Dieser Parameter in der Abfrage definiert, für welchen Speicher die Abfrage ausgeführt werden soll. Wenn sie nicht definiert ist, wird die Abfrage im Kaltspeicher ausgeführt. Um den warmen Speicher abzufragen, muss storeType- auf WarmStorefestgelegt werden. Wenn die Abfrage nicht definiert ist, wird sie gegen den Kaltspeicher ausgeführt. Gen2

Nächste Schritte