Freigeben über

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

  • Artikel

Hinweis

Der Time Series Insights-Dienst wird am 7. Juli 2024 eingestellt. Erwägen Sie, vorhandene Umgebungen so bald wie möglich zu alternativen Lösungen zu migrieren. Weitere Informationen zur Einstellung und Migration finden Sie in unserer Dokumentation.

Je nach Ihren geschäftlichen Anforderungen kann Ihre Lösung eine oder mehrere Clientanwendungen enthalten, über die Sie mit den APIs Ihrer Azure Time Series Insights-Umgebung interagieren. Die Authentifizierung erfolgt in Azure Time Series Insights über OAuth 2.0-basierte Microsoft Entra-Sicherheitstoken. Zum Authentifizieren Ihrer Clients müssen Sie ein Bearertoken mit den richtigen Berechtigungen abrufen und es bei Ihren API-Aufrufen übergeben. In diesem Dokument werden verschiedene Methoden beschrieben, mit denen Sie Anmeldeinformationen zum Abrufen von Bearertoken und zum Authentifizieren erhalten können, einschließlich der Verwendung einer verwalteten Identität und der Microsoft Entra-App-Registrierung.

Verwaltete Identitäten

In den folgenden Abschnitten wird beschrieben, wie Sie mithilfe einer verwalteten Identität in Microsoft Entra ID auf die Azure Time Series Insights-API zugreifen. Bei Azure machen verwaltete Identitäten die Verwaltung von Anmeldeinformationen für Entwickler überflüssig, indem sie eine Identität für die Azure-Ressource in Microsoft Entra ID bereitstellen und diese verwenden, um Microsoft Entra-Tokens zu erhalten. Nachstehend sind einige Vorteile der Verwendung von verwalteten Identitäten beschrieben:

  • Sie brauchen keine Anmeldeinformationen zu verwalten. Sie haben nicht einmal Zugriff auf die Anmeldeinformationen.
  • Mit verwalteten Identitäten kann die Authentifizierung bei jedem Azure-Dienst erfolgen, der die Microsoft Entra-Authentifizierung unterstützt, einschließlich Azure Key Vault.
  • Die Nutzung von verwalteten Identitäten verursacht keine zusätzlichen Kosten.

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

Sie können verwaltete Identitäten über folgende Instanzen verwenden:

  • Virtuelle Azure-Computer
  • Azure App Services
  • Azure Functions
  • Azure Container Instances
  • und viele weitere

Eine vollständige Liste finden Sie unter Azure-Dienste mit Unterstützung für verwaltete Identitäten für Azure-Ressourcen.

Registrierung von Microsoft Entra-Apps

Es wird empfohlen, nach Möglichkeit verwaltete Identitäten zu verwenden, damit Sie keine Anmeldeinformationen verwalten müssen. Wenn Ihre Clientanwendung in einem Azure-Dienst gehostet wird, der keine verwalteten 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, die die Integration in Microsoft Identity ID ermöglicht. Wenn Sie eine App im Azure-Portal registrieren, wählen Sie aus, ob es sich um einen Mandanten (Zugriff nur in Ihrem Mandanten möglich) oder um mehrere Mandanten (Zugriff in anderen Mandanten möglich) handelt. Optional können Sie auch einen Umleitungs-URI festlegen, an den 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 in Ihrem Basismandanten oder -verzeichnis befindet. Außerdem verfügen Sie über eine global eindeutige ID für Ihre App (App- oder Client-ID). Im Portal können Sie dann Geheimnisse oder Zertifikate und Geltungsbereiche hinzufügen, damit Ihre App funktioniert. Sie können auch 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 Basismandanten erstellt. Wenn Sie eine Anwendung mit den Microsoft Graph-APIs registrieren/erstellen, wird das Dienstprinzipalobjekt in einem separaten Schritt erstellt. Ein Dienstprinzipalobjekt ist erforderlich, um Token anzufordern.

Denken Sie daran, die Sicherheitscheckliste noch einmal für Ihre Anwendung durchzugehen. Es hat sich bewährt, die Zertifikatanmeldeinformationen zu verwenden, nicht die Kennwortanmeldeinformationen (Clientgeheimnisse).

Ausführlichere Informationen finden Sie unter Anwendungs- und Dienstprinzipalobjekte in Microsoft Entra ID.

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

Nachdem Sie festgestellt haben, ob Sie eine verwaltete Identität oder eine App-Registrierung verwenden werden, besteht der nächste Schritt in der Bereitstellung einer verwalteten Identität oder App-Registrierung.

Verwaltete Identität

Die Schritte für die Erstellung einer verwalteten Identität hängen davon ab, wo Ihr Code gehostet wird und ob Sie eine system- oder benutzerseitig zugewiesene Identität erstellen. Ausführlichere Informationen zum Unterschied finden Sie unter Typen verwalteter Identitäten. Nachdem Sie einen Identitätstyp ausgewählt haben, suchen Sie in der Dokumentation zu verwalteten Microsoft Entra-Identitäten das richtige Tutorial, und befolgen Sie die darin beschriebenen Schritte. Sie enthalten Anweisungen zur Konfiguration von verwalteten Identitäten für:

Anwendungsregistrierung

Befolgen Sie die Anleitung unter Registrieren einer Anwendung.

  • Konfigurieren Sie nach der Auswahl der geeigneten Plattform in Schritt 4 der Einstellungen zu Plattform konfigurieren die Umleitungs-URIs und Zugriffstoken im Seitenpanel rechts auf der Benutzeroberfläche.

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

      • Wählen Sie für Anwendungen, die in einer lokalen Entwicklungsumgebung gehostet werden, Öffentlicher Client (Mobilgerät und Desktop) aus. Stellen Sie sicher, dass Öffentlicher Client auf Ja festgelegt ist.
      • Wählen Sie für in Azure App Service gehostete Einzelseiten-Apps Web aus.

    • Legen Sie fest, ob eine Abmelde-URL geeignet ist.

    • Aktivieren Sie den Ablauf für die implizite Genehmigung, indem Sie die Option Zugriffstoken oder ID-Token aktivieren.

    Erstellen von Umleitungs-URIs

    Klicken Sie auf Konfigurieren und dann auf Speichern.

  • Ordnen Sie Azure Time Series Insights Ihre Microsoft Entra-App zu. Wählen Sie API-Berechtigungen>Berechtigung hinzufügen>Von meiner Organisation verwendete APIs aus.

    Zuordnen einer API zu Ihrer Microsoft Entra-App

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

  • Geben Sie als Nächstes die Art von API-Berechtigung an, die Ihre App benötigt. Standardmäßig ist Delegierte Berechtigungen hervorgehoben. Wählen Sie einen Berechtigungstyp und dann Berechtigungen hinzufügen.

    Angeben der Art der von Ihrer App benötigten API-Berechtigung

  • Fügen Sie Anmeldeinformationen hinzu, wenn die Anwendung selbst die APIs Ihrer Umgebung aufruft. Mit den Anmeldeinformationen kann sich Ihre Anwendung selbst authentifizieren und benötigt zur Laufzeit keine Interaktion durch einen Benutzer.

Schritt 2: Gewähren des Zugriffs

Wenn Ihre Azure Time Series Insights-Umgebung eine Anforderung empfängt, wird zuerst das Bearertoken des Aufrufers überprüft. Wenn die Überprüfung erfolgreich verläuft, wurde der Aufrufer authentifiziert, und es wird eine weitere Überprüfung durchgeführt, um sicherzustellen, dass der Aufrufer zur Durchführung der angeforderten Aktion auch autorisiert ist. Wenn Sie einen Benutzer oder Dienstprinzipal autorisieren möchten, müssen Sie ihm zuerst Zugriff auf die Umgebung erteilen, indem Sie ihm entweder die Rolle „Leser“ oder „Mitwirkender“ zuweisen.

  • Zugriff über das Azure-Portal erteilen: Befolgen Sie die Anleitung im Artikel Gewähren von Datenzugriff auf eine Umgebung. Wenn Sie den Benutzer auswählen, können Sie über den Namen oder die ID nach der verwalteten Identität bzw. App-Registrierung suchen.

  • Zugriff über die Azure CLI erteilen: Führen Sie den folgenden Befehl aus. Eine vollständige Liste der für die Zugriffsverwaltung verfügbaren Befehle finden Sie in der Dokumentation.

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

Hinweis

Die Erweiterung „timeseriesinsights“ für die Azure CLI erfordert Version 2.11.0 oder höher. Die Erweiterung wird automatisch installiert, wenn Sie einen „az tsi access-policy“-Befehl zum ersten Mal ausführen. Weitere Informationen zu Erweiterungen

Schritt 3: Anfordern von Token

Nachdem die verwaltete Identität oder App-Registrierung bereitgestellt und mit einer Rolle versehen wurde, können Sie damit OAuth 2.0-Bearertoken anfordern. Die Methode, mit der Sie ein Token abrufen, hängt davon ab, wo Ihr Code gehostet wird und welche Sprache Sie auswählen. Wenn Sie die Ressource angeben (auch die „Zielgruppe“ des Tokens genannt), können Sie Azure Time Series Insights anhand der URL oder der 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 für https://api.timeseries.azure.com/ ausgestellt werden. Der nachstehende Schrägstrich ist erforderlich.

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

Verwaltete Identitäten

Wenn der Zugriff über Azure App Service oder Azure Functions erfolgt, befolgen Sie die Anweisungen unter Abrufen von Token für Azure-Ressourcen.

In .NET-Anwendungen und -Funktionen ist es am einfachsten, über die Azure Identity-Clientbibliothek mit einer verwalteten Identität zu arbeiten. Die Clientbibliothek ist aufgrund ihrer Einfachheit und ihrer Sicherheitsvorteile beliebt. Entwickler können Code einmal schreiben und die Clientbibliothek auf Grundlage der Anwendungsumgebung über die Authentifizierung bestimmen lassen. Entscheidend ist, ob die Umgebung über ein Entwicklerkonto auf einer Entwicklungsarbeitsstation oder mithilfe einer verwalteten Dienstidentität in Azure bereitgestellt wurde. Eine Migrationsanleitung zur Vorgängerbibliothek „AppAuthentication“ finden Sie unter Leitfaden für die Migration von AppAuthentication zu Azure.Identity.

Fordern Sie mit C# und der Azure Identity-Clientbibliothek für .NET ein Token für Azure Time Series Insights an:

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 Anwendungsszenarios verwendet werden, unter anderem:

C#-Beispielcode zum Abrufen eines Tokens als App-Registrierung und zum Abfragen von Daten aus einer Gen2-Umgebung finden Sie in der Beispiel-App auf GitHub.

Wichtig

Wenn Sie die Active Directory-Authentifizierungsbibliothek (ADAL) verwenden, migrieren Sie zu MSAL.

Allgemeine Parameter und Header

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

Tipp

Weitere Informationen zum Nutzen von REST-APIs, Ausführen von HTTP-Anforderungen und Verarbeiten von HTTP-Antworten finden Sie in der Azure-Rest-API-Referenz.

HTTP-Kopfzeilen

Erforderliche Anforderungsheader werden nachfolgend beschrieben.

Erforderlicher Anforderungsheader Beschreibung
Autorisierung Für die Authentifizierung bei Azure Time Series Insights muss im Autorisierungsheader ein gültiges OAuth 2.0-Bearertoken übergeben werden.

Tipp

Weitere Informationen zur programmgesteuerten Authentifizierung mit den APIs von Azure Time Series Insights unter Verwendung des JavaScript Client SDK zusammen mit Diagrammen und Grafiken finden Sie in der gehosteten Beispielvisualisierung des Azure Time Series Insights-Client-SDK.

Optionale Anforderungsheader werden nachfolgend beschrieben.

Optionaler Anforderungsheader. Beschreibung
Inhaltstyp Nur application/json wird unterstützt.
x-ms-client-request-id Eine Clientanforderungs-ID. Der Dienst zeichnet diesen Wert auf. Ermöglicht es dem Dienst, den Vorgang dienstübergreifend nachzuverfolgen.
x-ms-client-session-id Eine Clientsitzungs-ID. Der Dienst zeichnet diesen Wert auf. Ermöglicht es dem Dienst, eine Gruppe verwandter Vorgänge dienstübergreifend nachzuverfolgen.
x-ms-client-application-name Der Name der Anwendung, die diese Anforderung generiert hat. Der Dienst zeichnet diesen Wert auf.

Optionale, aber empfohlene Antwortheader werden unten beschrieben.

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

HTTP-Parameter

Tipp

Weitere Informationen zu erforderlichen und optionalen Abfrageinformationen finden Sie in der Referenzdokumentation.

Die erforderlichen URL-Abfragezeichenfolgenparameter hängen von der API-Version ab.

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

Optionale URL-Abfragezeichenfolgen-Parameter umfassen das Festlegen eines Timeouts für die HTTP-Anforderungsausführungszeiten.

Optionaler Abfrageparameter Beschreibung Version
timeout=<timeout> Das serverseitige Timeout für die Ausführung der HTTP-Anforderung. Gilt nur für die APIs zum Abrufen von Umgebungsereignissen und Abrufen von Umgebungsaggregaten. Der Timeoutwert muss das ISO 8601-Format für die Dauer aufweisen (z.B. "PT20S") und sollte im Bereich 1-30 s liegen. Der Standardwert ist 30 s. Gen1
storeType=<storeType> Für Gen2-Umgebungen mit aktiviertem Warm Storage kann die Abfrage entweder für den WarmStore oder den ColdStore ausgeführt werden. Dieser Parameter in der Abfrage definiert, in welchem Speicher die Abfrage ausgeführt werden soll. Wenn nicht definiert, wird die Abfrage im kalten Speicher ausgeführt. Um den warmen Speicher abzufragen, muss storeType auf WarmStore festgelegt werden. Wenn nicht definiert, wird die Abfrage im kalten Speicher ausgeführt. Gen2

Nächste Schritte