Verificatie en autorisatie voor Azure Time Series Insights-API

Afhankelijk van uw bedrijfsbehoeften kan uw oplossing een of meer clienttoepassingen bevatten die u gebruikt om te communiceren met de API's Azure Time Series Insights uw omgeving. Azure Time Series Insights voert verificatie uit met behulp van Azure AD-beveiligingstokens op basis van OAUTH 2.0. Als u uw client(s) wilt verifiëren, moet u een Bearer-token met de juiste machtigingen krijgen en dit samen met uw API-aanroepen doorgeven. In dit document worden verschillende methoden beschreven voor het verkrijgen van referenties die u kunt gebruiken om een Bearer-token op te halen en te verifiëren, waaronder het gebruik van beheerde identiteit en Azure Active Directory app-registratie.

Beheerde identiteiten

In de volgende secties wordt beschreven hoe u een beheerde identiteit van Azure Active Directory (Azure AD) gebruikt om toegang te krijgen tot Azure Time Series Insights API. In Azure elimineren beheerde identiteiten de noodzaak voor ontwikkelaars om referenties te beheren door een identiteit voor de Azure-resource in Azure AD op te geven en deze te gebruiken voor het verkrijgen van Azure Active Directory-tokens (Azure AD). Hier volgen enkele van de voordelen van het gebruik van beheerde identiteiten:

  • U hoeft geen referenties te beheren. Referenties zijn voor u zelfs niet toegankelijk.
  • U kunt de beheerde identiteiten gebruiken voor verificatie bij alle Azure-services die ondersteuning bieden voor Azure AD-verificatie, inclusief Key Vault.
  • Beheerde identiteiten kunnen worden gebruikt zonder extra kosten.

Lees Wat zijn beheerde identiteiten voor Azure-resources? voor meer informatie over de twee typen beheerde identiteiten.

U kunt beheerde identiteiten gebruiken van uw:

  • Azure-VM's
  • Azure App Services
  • Azure Functions
  • Azure Container Instances
  • en meer ...

Zie Azure-services die beheerde identiteiten voor Azure-resources ondersteunen voor de volledige lijst.

Azure Active Directory app registreren

Het is raadzaam om waar mogelijk beheerde identiteiten te gebruiken, zodat u geen referenties hoeft te beheren. Als uw clienttoepassing niet wordt gehost op een Azure-service die beheerde identiteiten ondersteunt, kunt u uw toepassing registreren bij een Azure AD-tenant. Wanneer u uw toepassing registreert bij Azure AD, maakt u een identiteitsconfiguratie voor uw toepassing waarmee deze kan worden geïntegreerd met Azure AD. Wanneer u een app registreert in de Azure Portal,kiest u of het een enkele tenant is (alleen toegankelijk in uw tenant) of meerdere tenants (toegankelijk in andere tenants) en kunt u desgewenst een omleidings-URI instellen (waar het toegangs token naar wordt verzonden).

Wanneer u de registratie van de app hebt voltooid, hebt u een wereldwijd uniek exemplaar van de app (het toepassingsobject) dat zich in uw basis-tenant of -directory behuist. U hebt ook een wereldwijd unieke id voor uw app (de app of client-id). In de portal kunt u vervolgens geheimen of certificaten en scopes toevoegen om uw app te laten werken, de huisstijl van uw app aan te passen in het aanmeldingsdialoogvenster en meer.

Als u een toepassing registreert in de portal, worden er automatisch een toepassingsobject en een service-principal-object gemaakt in uw basis-tenant. Als u een toepassing registreert/maakt met behulp van Microsoft Graph API's, is het maken van het service-principal-object een afzonderlijke stap. Een service-principal-object is vereist om tokens aan te vragen.

Controleer de controlelijst voor beveiliging voor uw toepassing. Als best practice moet u certificaatreferenties gebruiken,geen wachtwoordreferenties (clientgeheimen).

Zie Toepassings- en service-principalobjecten in Azure Active Directory voor meer informatie.

Stap 1: uw beheerde identiteit of app-registratie maken

Zodra u hebt vastgesteld of u een beheerde identiteit of app-registratie gebruikt, is de volgende stap het inrichten van een identiteit.

Beheerde identiteit

De stappen die u gebruikt om een beheerde identiteit te maken, variëren afhankelijk van waar uw code zich bevindt en of u een door het systeem toegewezen of door de gebruiker toegewezen identiteit maakt. Lees Beheerde identiteitstypen om het verschil te begrijpen. Nadat u uw identiteitstype hebt geselecteerd, zoekt en volgt u de juiste zelfstudie in de documentatie voor door Azure AD beheerde identiteiten. Hier vindt u instructies voor het configureren van beheerde identiteiten voor:

Een toepassing registreren

Volg de stappen in Een toepassing registreren.

  • Nadat u het juiste platform hebt geselecteerd in stap 4 van platform instellingen configureren , configureert u de omleidings-Uri's en toegangs tokens in het deel venster aan de rechter kant van de gebruikers interface.

    • Omleidings-uri's moeten overeenkomen met het adres dat is opgegeven door de verificatie aanvraag:

      • Voor apps die worden gehost in een lokale ontwikkel omgeving selecteert u open bare client (mobiele & bureau blad). Zorg ervoor dat de open bare client is ingesteld op Ja.
      • Selecteer Web voor Single-Page-apps die worden gehost op Azure app service.
    • Bepaal of een Afmeldings-URL geschikt is.

    • Schakel de impliciete toekennings stroom in door toegangs tokens of id-tokens te controleren.

    Omleidings-Uri's maken

    Klik op configureren en vervolgens op Opslaan.

  • Koppel uw Azure Active Directory-app-Azure Time Series Insights. Selecteer API-machtigingen > een machtigings > -api's toevoegen die mijn organisatie gebruikt.

    Een API koppelen aan uw Azure Active Directory-app

    Typ Azure Time Series Insights in de zoek balk en selecteer Azure Time Series Insights .

  • Geef vervolgens de type API-machtiging op die uw app vereist. Standaard worden gedelegeerde machtigingen gemarkeerd. Kies een machtigings type en selecteer vervolgens machtigingen toevoegen.

    Geef het type API-machtiging op dat voor uw app is vereist

  • Voeg referenties toe als de toepassing de api's van uw omgeving als zichzelf aanroept. Met referenties kan uw toepassing zichzelf verifiëren, waardoor er geen interactie van een gebruiker tijdens runtime nodig is.

Stap 2: Toegang verlenen

Wanneer uw Azure Time Series Insights een aanvraag ontvangt, wordt eerst het bearer-token van de aanroeper gevalideerd. Als de validatie is uitgevoerd, is de aanroeper geverifieerd en wordt er een andere controle uitgevoerd om ervoor te zorgen dat de aanroeper is gemachtigd om de aangevraagde actie uit te voeren. Als u een gebruiker of service-principal wilt machtigen, moet u deze eerst toegang verlenen tot de omgeving door deze de rol Lezer of Inzender toe te wijzen.

  • Als u toegang wilt verlenen via Azure Portal gebruikersinterface, volgt u de instructies in het artikel Gegevens toegang verlenen tot een omgeving. Wanneer u de gebruiker selecteert, kunt u zoeken naar de beheerde identiteit of app-registratie op naam of id.

  • Voer de volgende opdracht uit om toegang te verlenen met behulp van de Azure CLI. Bekijk hier de documentatie voor de volledige lijst met opdrachten die beschikbaar zijn voor het beheren van toegang.

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

Notitie

Voor de timeseriesinsights-extensie voor Azure CLI is versie 2.11.0 of hoger vereist. De extensie wordt automatisch geïnstalleerd wanneer u de opdracht az tsi access-policy voor het eerst hebt uitgevoerd. Meer informatie over extensies.

Stap 3: Tokens aanvragen

Zodra uw beheerde identiteit of app-registratie is ingericht en aan een rol is toegewezen, kunt u deze gaan gebruiken om OAuth 2.0-bearer-tokens aan te vragen. De methode die u gebruikt om een token te verkrijgen, is afhankelijk van waar uw code wordt gehost en de taal van uw keuze. Wanneer u de resource opgeeft (ook wel bekend als de 'doelgroep' van het token), kunt u deze Azure Time Series Insights url of GUID:

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

Belangrijk

Als u de URL als de resource-id gebruikt, moet het token exact worden uitgegeven aan https://api.timeseries.azure.com/ . De schuine streep erts is vereist.

  • Als u Postman gebruikt, is uw AuthURL daarom: https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default
  • https://api.timeseries.azure.com/ is geldig, maar https://api.timeseries.azure.com niet.

Beheerde identiteiten

Volg bij het openen Azure App Service of Functions de richtlijnen in Tokens voor Azure-resources verkrijgen.

Voor .NET-toepassingen en -functies is de eenvoudigste manier om met een beheerde identiteit te werken via de Azure Identity-clientbibliotheek voor .NET. Deze clientbibliotheek is populair vanwege de eenvoud en beveiligingsvoordelen. Ontwikkelaars kunnen één keer code schrijven en de clientbibliotheek laten bepalen hoe verificatie moet worden uitgevoerd op basis van de toepassingsomgeving, of dit nu op een ontwikkelaarswerkstation is met behulp van een ontwikkelaarsaccount of in Azure is geïmplementeerd met behulp van een beheerde service-identiteit. Lees AppAuthentication to Azure.Identity Migration Guidance(Richtlijnen voor Migratie van AppAuthentication naar Azure.Identity) voor hulp bij de migratie van de voorganger AppAuthentication-bibliotheek.

Vraag een token aan voor Azure Time Series Insights C# en de Azure Identity-clientbibliotheek voor .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-registratie

MSAL kan worden gebruikt in veel toepassingsscenario's, waaronder, maar niet beperkt tot:

Voor C#-voorbeeldcode die laat zien hoe u een token kunt verkrijgen als een app-registratie en gegevens opvraagt uit een Gen2-omgeving, bekijkt u de voorbeeld-app op GitHub

Algemene headers en parameters

In deze sectie worden veelgebruikte HTTP-aanvraagheaders en -parameters beschreven die worden gebruikt om query's uit te Azure Time Series Insights gen1- en Gen2-API's. API-specifieke vereisten worden uitvoeriger behandeld in de Azure Time Series Insights REST API referentiedocumentatie.

Tip

Lees de Naslag voor Azure REST API voor meer informatie over het gebruik van REST API's, het maken van HTTP-aanvragen en het verwerken van HTTP-antwoorden.

HTTP-headers

Vereiste aanvraagheaders worden hieronder beschreven.

Vereiste aanvraagheader Beschrijving
Autorisatie Voor verificatie met Azure Time Series Insights moet een geldig OAuth 2.0 Bearer-token worden doorgegeven in de autorisatie-header.

Tip

Lees de voorbeeldvisualisatie van de gehoste Azure Time Series Insights client-SDK voor meer informatie over het programmatisch verifiëren met de Azure Time Series Insights-API's met behulp van de JavaScript Client SDK, samen met grafieken en grafieken.

Optionele aanvraagheaders worden hieronder beschreven.

Optionele aanvraagheader Beschrijving
Inhoudstype alleen application/json wordt ondersteund.
x-ms-client-request-id Een clientaanvraag-id. De service registreert deze waarde. Hiermee kan de service de werking van services traceren.
x-ms-client-session-id Een clientsessie-id. De service registreert deze waarde. Hiermee kan de service een groep gerelateerde bewerkingen in services traceren.
x-ms-client-application-name Naam van de toepassing die deze aanvraag heeft gegenereerd. De service registreert deze waarde.

Hieronder worden optionele maar aanbevolen antwoordheaders beschreven.

Antwoordheader Beschrijving
Inhoudstype Alleen application/json wordt ondersteund.
x-ms-request-id Door de server gegenereerde aanvraag-id. Kan worden gebruikt om contact op te nemen met Microsoft om een aanvraag te onderzoeken.
x-ms-property-not-found-behavior Ga-API optionele antwoordheader. Mogelijke waarden zijn ThrowError (standaard) of UseNull .

HTTP-parameters

Tip

Meer informatie over vereiste en optionele querygegevens vindt u in de referentiedocumentatie.

Vereiste url-queryreeksparameters zijn afhankelijk van de API-versie.

Release API-versiewaarden
Gen1 api-version=2016-12-12
Gen2 api-version=2020-07-31

Optionele parameters voor URL-queryreeksen omvatten het instellen van een time-out voor uitvoeringstijden van HTTP-aanvragen.

Optionele queryparameter Beschrijving Versie
timeout=<timeout> Time-out aan serverzijde voor het uitvoeren van HTTP-aanvragen. Alleen van toepassing op de API's Omgevingsgebeurtenissen op halen en Omgevingsaggregaten op halen. De time-outwaarde moet bijvoorbeeld de ISO 8601-duurnotatie hebben en "PT20S" moet binnen het bereik 1-30 s zijn. De standaardwaarde is 30 s. Gen1
storeType=<storeType> Voor Gen2-omgevingen waarin warm-opslag is ingeschakeld, kan de query worden uitgevoerd op WarmStore de of ColdStore . Deze parameter in de query definieert op welke opslag de query moet worden uitgevoerd. Als deze niet is gedefinieerd, wordt de query uitgevoerd in de koude opslag. Als u een query wilt uitvoeren op de warme opslag, moet storeType worden ingesteld op WarmStore . Als dit niet is gedefinieerd, wordt de query uitgevoerd op basis van de koude opslag. Gen2

Volgende stappen

  • Lees Query Gen1-gegevens met C# voor voorbeeldcode die de Gen1 Azure Time Series Insights API aanroept.

  • Lees Query Gen2-gegevens met C# voor voorbeeldcode die de Gen2 Azure Time Series Insights API-codevoorbeelden aanroept.

  • Lees de naslagdocumentatie over de Query-API voor naslaginformatie over de API.