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 van uw Azure Time Series Insights-omgeving. Azure Time Series Insights voert verificatie uit met behulp van Microsoft Entra-beveiligingstokens op basis van OAUTH 2.0. Als u uw client(s) wilt verifiëren, moet u een Bearer-token met de juiste machtigingen ophalen en deze doorgeven samen met uw API-aanroepen. In dit document worden verschillende methoden beschreven voor het ophalen van referenties die u kunt gebruiken om een Bearer-token op te halen en te authenticeren, waaronder het gebruik van beheerde identiteit en Microsoft Entra-appregistratie.

Beheerde identiteiten

In de volgende secties wordt beschreven hoe u een beheerde identiteit van Microsoft Entra ID gebruikt voor toegang tot de 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 Microsoft Entra ID op te geven en deze te gebruiken voor het verkrijgen van Microsoft Entra-tokens. 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 beheerde identiteiten gebruiken om te verifiëren bij elke Azure-service die ondersteuning biedt voor Microsoft Entra-verificatie, inclusief Azure Key Vault.
• Beheerde identiteiten kunnen worden gebruikt zonder extra kosten.

Voor meer informatie over de twee typen beheerde identiteiten, lees Wat zijn beheerde identiteiten voor Azure-resources?

U kunt beheerde identiteiten gebruiken vanuit uw:

• Azure VMs
• Azure App Services
• Azure Functions
• Azure-containerinstanties
• en meer ...

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

Microsoft Entra app-registratie

We raden u aan 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 Microsoft Entra-tenant. Wanneer u uw toepassing registreert bij Microsoft Entra ID, maakt u een identiteitsconfiguratie voor uw toepassing waarmee deze kan worden geïntegreerd met Microsoft Entra ID. Wanneer u een app registreert in Azure Portal, kiest u of deze één tenant is (alleen toegankelijk in uw tenant) of meerdere tenants (toegankelijk in andere tenants) en kunt u eventueel een omleidings-URI instellen (waar het toegangstoken naartoe wordt verzonden).

Wanneer u de app-registratie hebt voltooid, hebt u een wereldwijd uniek exemplaar van de app (het toepassingsobject) dat zich in uw basistenant of map bevindt. 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 bereiken toevoegen om uw app te laten werken, de huisstijl van uw app aanpassen in het aanmeldingsdialoogvenster en meer.

Als u een toepassing registreert in de portal, worden er automatisch een toepassingsobject en een serviceprincipalobject gemaakt in uw thuistenant. Als u een toepassing registreert/maakt met behulp van de 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 beveiligingscontrolelijst voor uw toepassing. Als best practice moet u certificaatreferenties gebruiken, geen wachtwoordreferenties (clientgeheimen).

Zie Toepassings- en service-principalobjecten in Microsoft Entra ID voor meer informatie.

Stap 1: Uw beheerde identiteit of app-registratie maken

Nadat u hebt vastgesteld of u een beheerde identiteit of app-registratie gebruikt, moet u er een inrichten.

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 handleiding in de documentatie over door Microsoft Entra beheerde identiteiten. Hier vindt u instructies voor het configureren van beheerde identiteiten voor:

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

Applicatieregistratie

Volg de stappen in Een toepassing registreren.

• Nadat u het juiste platform hebt geselecteerd in stap 4 van Platforminstellingen configureren, configureert u uw omleidings-URI's en toegangstokens in het zijpaneel rechts van de gebruikersinterface.

  • Omleidings-URI's moeten overeenkomen met het adres dat is opgegeven door de verificatieaanvraag:

    • Selecteer Openbare client (mobiel en desktop) voor apps die worden gehost in een lokale ontwikkelomgeving. Zorg ervoor dat u 'openbare client' instelt op 'Ja'.
    • Selecteer Web voor apps met één pagina die worden gehost op Azure-app Service.

  • Bepaal of een afmeldings-URL geschikt is.

  • Schakel de impliciete toekenningsstroom in door toegangstokens of id-tokens te controleren.

  

  Klik op Configureren en vervolgens opslaan.

• Koppel uw Microsoft Entra-app Aan Azure Time Series Insights. Selecteer API-machtigingen>Voeg een machtigings-API>toe die door mijn organisatie wordt gebruikt.

  

  Typ Azure Time Series Insights in de zoekbalk en selecteer Azure Time Series Insights.

• Geef vervolgens de soort API-machtiging op die uw app nodig heeft. Gedelegeerde machtigingen worden standaard gemarkeerd. Kies vervolgens een machtigingstype en selecteer Machtigingen toevoegen.

  

• 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-omgeving een aanvraag ontvangt, wordt eerst het Bearer-token van de beller gevalideerd. Als de validatie is geslaagd, is de beller geverifieerd en wordt er nog een controle uitgevoerd om ervoor te zorgen dat de beller gemachtigd is om de aangevraagde actie uit te voeren. Als u een gebruiker of service-principal wilt autoriseren, moet u ze eerst toegang verlenen tot de omgeving door ze de rol Lezer of Inzender toe te wijzen.

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

• Voer de volgende opdracht uit om toegang te verlenen met behulp van de Azure CLI. Raadpleeg de documentatie hier 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"
  

Stap 3: Tokens aanvragen

Zodra uw beheerde identiteit of app-registratie is ingericht en 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, verschilt, afhankelijk van waar uw code wordt gehost en uw gewenste taal. Wanneer u de resource opgeeft (ook wel de 'doelgroep' van het token genoemd), kunt u Azure Time Series Insights identificeren op basis van de URL of GUID:

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

• 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

Wanneer u toegang krijgt vanuit Azure-app Service of Functions, volgt u de richtlijnen in het verkrijgen van tokens voor Azure-resources.

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 de beveiligingsvoordelen. Ontwikkelaars kunnen eenmaal code schrijven en de clientbibliotheek laten bepalen hoe verificatie moet worden uitgevoerd op basis van de toepassingsomgeving, ongeacht of op een ontwikkelaarswerkstation het account van een ontwikkelaar wordt gebruikt of geïmplementeerd in Azure met behulp van een beheerde service-id. Lees de migratierichtlijnen van de eerdere AppAuthentication-bibliotheek naar Azure.Identity.

Een token aanvragen voor Azure Time Series Insights met behulp van 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

• Gebruik de Microsoft Authentication Library (MSAL) om tokens voor app-registraties te verkrijgen.

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

• Toepassingen met één pagina (JavaScript)
• Webtoepassing die een gebruiker aanmeldt en web-API aanroept in naam van de gebruiker
• Web-API die een andere downstream web-API aanroept in naam van de aangemelde gebruiker
• Bureaubladtoepassing die ene web-API aanroept in naam van de aangemelde gebruiker
• Mobiele toepassing die een web-API aanroept in naam van de gebruiker die interactief is aangemeld.
• Bureaubladtoepassing/servicedaemontoepassing die een web-API namens zichzelf aanroept

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 veelvoorkomende HTTP-aanvraagheaders en -parameters beschreven die worden gebruikt om query's uit te voeren op de Azure Time Series Insights Gen1- en Gen2-API's. API-specifieke vereisten worden uitgebreid beschreven in de naslagdocumentatie voor Azure Time Series Insights REST API.

HTTP-kopteksten

Vereiste aanvraagheaders worden hieronder beschreven.

Optionele aanvraagheaders worden hieronder beschreven.

Optioneel, maar aanbevolen antwoordheaders worden hieronder beschreven.

HTTP-parameters

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

Optionele parameters voor URL-queryreeksen omvatten het instellen van een time-out voor http-aanvraaguitvoeringstijden.

Volgende stappen

• Voor voorbeeldcode die de Gen1 Azure Time Series Insights-API aanroept, lees Query Gen1-gegevens met C#.

• Lees Query Gen2-gegevens met C# voor voorbeeldcode waarmee de Gen2 Azure Time Series Insights-API-codevoorbeelden worden aangeroepen.

• Lees de Query API-referentie documentatie voor API-referentie-informatie.