Over API-referenties en referentiebeheer

VAN TOEPASSING OP: Alle API Management-lagen

Om u te helpen de toegang tot back-end-API's te beheren, bevat uw API Management-exemplaar een referentiebeheerder. Gebruik referentiebeheer voor het beheren, opslaan en beheren van toegang tot API-referenties vanuit uw API Management-exemplaar.

Beheerde verbindingen voor OAuth 2.0-API's

Met referentiebeheer kunt u het proces voor het verifiëren en autoriseren van gebruikers, groepen en service-principals aanzienlijk vereenvoudigen in een of meer back-end- of SaaS-services die gebruikmaken van OAuth 2.0. Met behulp van referentiebeheer van API Management kunt u eenvoudig OAuth 2.0 configureren, toestemming geven, tokens verkrijgen, tokens in een referentiearchief opslaan en tokens vernieuwen zonder één regel code te schrijven. Gebruik toegangsbeleid om verificatie te delegeren aan uw API Management-exemplaar, service-principals, gebruikers of groepen. Zie Microsoft Identity Platform en OAuth 2.0-autorisatiecodestroom voor achtergrondinformatie over OAuth 2.0.

Met deze functie kunnen API's worden weergegeven met of zonder een abonnementssleutel, OAuth 2.0-autorisaties gebruiken voor back-endservices en de ontwikkelingskosten verlagen bij het op gang brengen, implementeren en onderhouden van beveiligingsfuncties met service-integraties.

Gebruiksvoorbeelden

Met behulp van OAuth-verbindingen die worden beheerd in API Management, kunnen klanten eenvoudig verbinding maken met SaaS-providers of back-endservices die gebruikmaken van OAuth 2.0. Hieronder volgen een aantal voorbeelden:

• Eenvoudig verbinding maken met een SaaS-back-end door het opgeslagen autorisatietoken en proxyaanvragen te koppelen

• Proxyaanvragen naar een Azure-app Service-web-app of Azure Functions-back-end door het autorisatietoken toe te voegen, die later aanvragen kan verzenden naar een SaaS-back-end die transformatielogica toepast

• Proxyaanvragen voor GraphQL-federatieback-ends door meerdere toegangstokens toe te voegen om eenvoudig federatie uit te voeren

• Maak een eindpunt voor het ophalen van tokens beschikbaar, verwerf een token in de cache en roep een SaaS-back-end aan namens de gebruiker, bijvoorbeeld een console-app of Kubernetes-daemon. Combineer uw favoriete SaaS SDK in een ondersteunde taal.

• Scenario's zonder toezicht van Azure Functions bij het maken van verbinding met meerdere SaaS-back-ends.

• Durable Functions krijgt een stap dichter bij Logic Apps met SaaS-connectiviteit.

• Met OAuth 2.0-verbindingen kan elke API in API Management fungeren als een aangepaste Logic Apps-connector.

Hoe werkt referentiebeheer?

Tokenreferenties in referentiebeheer bestaan uit twee onderdelen: beheer en runtime.

• Het beheeronderdeel in referentiebeheer zorgt voor het instellen en configureren van een referentieprovider voor OAuth 2.0-tokens, het inschakelen van de toestemmingsstroom voor de id-provider en het instellen van een of meer verbindingen met de referentieprovider voor toegang tot de referenties. Zie Beheer van verbindingen voor meer informatie.

• Het runtime-onderdeel maakt gebruik van het get-authorization-context beleid om de toegangs- en vernieuwingstokens van de verbinding op te halen en op te slaan. Wanneer een aanroep binnenkomt in API Management en het get-authorization-context beleid wordt uitgevoerd, wordt eerst gevalideerd of het bestaande autorisatietoken geldig is. Als het autorisatietoken is verlopen, gebruikt API Management een OAuth 2.0-stroom om de opgeslagen tokens van de id-provider te vernieuwen. Vervolgens wordt het toegangstoken gebruikt om toegang tot de back-endservice te autoriseren. Zie Runtime van verbindingen voor meer informatie.

Wanneer gebruikt u referentiebeheer?

Hier volgen drie scenario's voor het gebruik van referentiebeheer.

Configuratiescenario

Nadat de referentieprovider en een verbinding zijn geconfigureerd, kan de API-beheerder de verbinding testen. De API Manager configureert een OAuth-testback-end-API om het get-authorization-context beleid te gebruiken met behulp van de beheerde identiteit van het exemplaar. Api Manager kan vervolgens de verbinding testen door de test-API aan te roepen.

Scenario zonder toezicht

Wanneer er een verbinding wordt gemaakt, worden een toegangsbeleid en verbinding vooraf geconfigureerd voor de beheerde identiteit van het API Management-exemplaar. Als u een dergelijke verbinding wilt gebruiken, kunnen verschillende gebruikers zich aanmelden bij een clienttoepassing, zoals een statische web-app, die vervolgens een back-end-API aanroept die beschikbaar wordt gesteld via API Management. Om deze aanroep te maken, worden verbindingen toegepast met behulp van het get-authorization-context beleid. Omdat de API-aanroep gebruikmaakt van een vooraf geconfigureerde verbinding die niet is gerelateerd aan de gebruikerscontext, worden dezelfde gegevens geretourneerd naar alle gebruikers.

Bijgewoond scenario (door de gebruiker gedelegeerd)

Als u een vereenvoudigde verificatie-ervaring wilt inschakelen voor gebruikers van clienttoepassingen, zoals statische web-apps, die back-end SaaS-API's aanroepen waarvoor een gebruikerscontext is vereist, kunt u toegang tot een verbinding inschakelen namens een Microsoft Entra-gebruikers- of groepsidentiteit. In dit geval moet een geconfigureerde gebruiker zich slechts één keer aanmelden en toestemming geven. Daarna maakt en beheert het API Management-exemplaar de verbinding. Wanneer API Management een binnenkomende aanroep ontvangt die moet worden doorgestuurd naar een externe service, wordt het toegangstoken vanuit de verbinding met de aanvraag gekoppeld. Dit is ideaal voor wanneer API-aanvragen en -antwoorden zijn gericht op een persoon (bijvoorbeeld het ophalen van gebruikersspecifieke profielgegevens).

Referentiebeheer configureren

Vereisten

• Beheerde door het systeem toegewezen identiteit moet zijn ingeschakeld voor het API Management-exemplaar.

• API Management-exemplaar moet uitgaande connectiviteit hebben met internet op poort 443 (HTTPS).

Beschikbaarheid

• Alle API Management-servicelagen

• Niet ondersteund in zelf-hostende gateway

• Niet ondersteund in onafhankelijke clouds of in de volgende regio's: australiacentral, australiacentral2, indiacentral

Stapsgewijze voorbeelden

• Referentiebeheer configureren - GitHub-API
• Referentiebeheer configureren - Microsoft Graph API
• Referentiebeheer configureren - door de gebruiker gedelegeerde toegang

Beveiligingsoverwegingen

Het toegangstoken en andere geheimen (bijvoorbeeld clientgeheimen) worden versleuteld met een envelopversleuteling en opgeslagen in een interne, multitenant-opslag. De gegevens worden versleuteld met AES-128 met behulp van een sleutel die uniek is per gegevens. Deze sleutels worden asymmetrisch versleuteld met een hoofdcertificaat dat is opgeslagen in Azure Key Vault en elke maand wordt gedraaid.

Limieten

Veelgestelde vragen

Wanneer worden de toegangstokens vernieuwd?

Voor een verbinding van type autorisatiecode worden toegangstokens als volgt vernieuwd: Wanneer het get-authorization-context beleid tijdens runtime wordt uitgevoerd, controleert API Management of het opgeslagen toegangstoken geldig is. Als het token is verlopen of bijna is verlopen, gebruikt API Management het vernieuwingstoken om een nieuw toegangstoken en een nieuw vernieuwingstoken op te halen van de geconfigureerde id-provider. Als het vernieuwingstoken is verlopen, wordt er een fout gegenereerd en moet de verbinding opnieuw worden geverifieerd voordat het werkt.

Wat gebeurt er als het clientgeheim verloopt bij de id-provider?

Tijdens runtime kan API Management geen nieuwe tokens ophalen en treedt er een fout op.

• Als de verbinding van het type autorisatiecode is, moet het clientgeheim worden bijgewerkt op referentieproviderniveau.

• Als de verbinding van het type clientreferenties is, moet het clientgeheim worden bijgewerkt op het verbindingsniveau.

Wordt deze functie ondersteund met API Management die wordt uitgevoerd in een VNet?

Ja, zolang uitgaande connectiviteit op poort 443 is ingeschakeld voor de servicetag Azure Verbinding maken ors. Zie de naslaginformatie over de configuratie van virtuele netwerken voor meer informatie.

Wat gebeurt er wanneer een referentieprovider wordt verwijderd?

Alle onderliggende verbindingen en toegangsbeleid worden ook verwijderd.

Worden de toegangstokens in de cache opgeslagen door API Management?

In de klassieke en v2-servicelagen wordt het toegangstoken in de cache opgeslagen door het API Management-exemplaar tot 3 minuten voor de verlooptijd van het token. Als het toegangstoken minder dan 3 minuten verwijderd is van de vervaldatum, is de tijd in de cache totdat het toegangstoken verloopt.

Toegangstokens worden niet in de cache opgeslagen in de verbruikslaag.

Gerelateerde inhoud

• Referentieproviders configureren voor verbindingen
• Een verbinding configureren en gebruiken voor de Microsoft Graph API of de GitHub-API
• Een verbinding configureren voor door de gebruiker gedelegeerde toegang
• Meerdere verbindingen configureren voor een referentieprovider