De testconsole van de ontwikkelaarsportal autoriseren door OAuth 2.0-gebruikersautorisatie te configureren

VAN TOEPASSING OP: Ontwikkelaar | Basic | Basic v2 | Standaard | Standard v2 | Premium

Veel API's ondersteunen OAuth 2.0 om de API te beveiligen en ervoor te zorgen dat alleen geldige gebruikers toegang hebben en dat ze alleen toegang hebben tot resources waartoe ze recht hebben. Als u de interactieve ontwikkelaarsconsole van Azure API Management wilt gebruiken met dergelijke API's, kunt u met de service een externe provider configureren voor OAuth 2.0-gebruikersautorisatie.

Het configureren van OAuth 2.0-gebruikersautorisatie in de testconsole van de ontwikkelaarsportal biedt ontwikkelaars een handige manier om een OAuth 2.0-toegangstoken te verkrijgen. Vanuit de testconsole wordt het token vervolgens doorgegeven aan de back-end met de API-aanroep. Tokenvalidatie moet afzonderlijk worden geconfigureerd: met behulp van een JWT-validatiebeleid of in de back-endservice.

Vereisten

In dit artikel leest u hoe u uw API Management-service-exemplaar configureert voor het gebruik van OAuth 2.0-autorisatie in de testconsole van de ontwikkelaarsportal, maar u ziet niet hoe u een OAuth 2.0-provider configureert.

Zie Een API Management-service-exemplaar maken als u nog geen API Management-service-exemplaar hebt gemaakt.

Overzicht van scenario

Als u OAuth 2.0-gebruikersautorisatie configureert in API Management, kan de testconsole van de ontwikkelaarsportal (en de testconsole in Azure Portal) alleen als client een token verkrijgen van de autorisatieserver. De configuratie voor elke OAuth 2.0-provider is anders, hoewel de stappen vergelijkbaar zijn en de vereiste gegevens die worden gebruikt hetzelfde zijn voor het configureren van OAuth 2.0 in uw API Management service-exemplaar. In dit artikel ziet u een voorbeeld van het gebruik van Microsoft Entra-id als een OAuth 2.0-provider.

Hier volgen de configuratiestappen op hoog niveau:

1. Registreer een toepassing (back-end-app) in Microsoft Entra ID om de API te vertegenwoordigen.

2. Registreer een andere toepassing (client-app) in Microsoft Entra ID om een clienttoepassing te vertegenwoordigen die de API moet aanroepen. In dit geval is de testconsole van de ontwikkelaarsportal.

   Machtigingen verlenen in Microsoft Entra ID om de client-app toe te staan de back-end-app op te roepen.

3. Configureer de testconsole in de ontwikkelaarsportal om een API op te roepen met behulp van de OAuth 2.0-gebruikersautorisatie.

4. Een API configureren voor het gebruik van OAuth 2.0-gebruikersautorisatie.

5. Voeg een beleid toe om het OAuth 2.0-token vooraf te autoriseren voor elke binnenkomende aanvraag. U kunt het validate-jwt beleid gebruiken voor elke OAuth 2.0-provider.

Deze configuratie ondersteunt de volgende OAuth-stroom:

1. De ontwikkelaarsportal vraagt een token van Microsoft Entra ID aan met behulp van de referenties van de client-app.

2. Na een geslaagde validatie geeft Microsoft Entra ID het toegangs-/vernieuwingstoken uit.

3. Een ontwikkelaar (gebruiker van de ontwikkelaarsportal) maakt een API-aanroep met de autorisatieheader.

4. Het token wordt gevalideerd met behulp van het validate-jwt beleid in API Management door Microsoft Entra ID.

5. Op basis van het validatieresultaat ontvangt de ontwikkelaar het antwoord in de ontwikkelaarsportal.

Typen autorisatietoestemming

Azure API Management ondersteunt de volgende OAuth 2.0-toekenningstypen (stromen). Een toekenningstype verwijst naar een manier voor een clienttoepassing (in deze context de testconsole in de ontwikkelaarsportal) om een toegangstoken voor uw back-end-API te verkrijgen. U kunt een of meer toekenningstypen configureren, afhankelijk van uw OAuth 2.0-provider en -scenario's.

Hier volgt een samenvatting op hoog niveau. Zie het OAuth 2.0-autorisatieframework en OAuth-toekenningstypen voor meer informatie over toekenningstypen.

Toekenningstype	Beschrijving	Scenario's
Autorisatiecode	Autorisatiecode voor token uitwisselen	Apps aan de serverzijde, zoals web-apps
Autorisatiecode + PKCE	Verbeteringen aan autorisatiecodestroom die een codevraag maakt die wordt verzonden met autorisatieaanvraag	Mobiele en openbare clients die geen geheim of token kunnen beveiligen
Impliciet (afgeschaft)	Retourneert het toegangstoken onmiddellijk zonder een extra autorisatiecode-uitwisselingsstap	Clients die geen geheim of token kunnen beveiligen, zoals mobiele apps en apps met één pagina Over het algemeen niet aanbevolen vanwege inherente risico's van het retourneren van toegangstoken in HTTP-omleiding zonder bevestiging dat het wordt ontvangen door de client
Wachtwoord van resource-eigenaar	Gebruikersreferenties (gebruikersnaam en wachtwoord) aanvragen, meestal met behulp van een interactief formulier	Voor gebruik met zeer vertrouwde toepassingen Mag alleen worden gebruikt wanneer andere, veiligere stromen niet kunnen worden gebruikt
Clientreferenties	Verifieert en autoriseert een app in plaats van een gebruiker	Machine-naar-machinetoepassingen waarvoor geen specifieke gebruikersmachtigingen nodig zijn voor toegang tot gegevens, zoals CLIs, daemons of services die worden uitgevoerd op uw back-end

Beveiligingsoverwegingen

Bedenk hoe het toekenningstype een token, het bereik van het token genereert en hoe het token kan worden weergegeven. Een gekraakt token kan worden gebruikt door een kwaadwillende actor om toegang te krijgen tot extra resources binnen het bereik van het token.

Bij het configureren van OAuth 2.0-gebruikersautorisatie in de testconsole van de ontwikkelaarsportal:

• Beperk het bereik van het token tot het minimum dat ontwikkelaars nodig hebben om de API's te testen. Beperk het bereik tot de testconsole of tot de betrokken API's. De stappen voor het configureren van het tokenbereik zijn afhankelijk van uw OAuth 2.0-provider.

  Afhankelijk van uw scenario's kunt u meer of minder beperkende tokenbereiken configureren voor andere clienttoepassingen die u maakt voor toegang tot back-end-API's.

• Zorg er extra voor als u de clientreferentiestroom inschakelt. De testconsole in de ontwikkelaarsportal vraagt niet om referenties wanneer u met de stroom Clientreferenties werkt. Een toegangstoken kan per ongeluk worden blootgesteld aan ontwikkelaars of anonieme gebruikers van de ontwikkelaarsconsole.

Belangrijke informatie bijhouden

In deze zelfstudie wordt u gevraagd om belangrijke informatie vast te leggen waarnaar u later kunt verwijzen:

• Id van back-endtoepassing (client): de GUID van de toepassing die de back-end-API vertegenwoordigt
• Back-endtoepassingsbereiken: een of meer bereiken die u kunt maken voor toegang tot de API. De bereikindeling is api://<Backend Application (client) ID>/<Scope Name> (bijvoorbeeld api://1764e900-1827-4a0b-9182-b2c1841864c2/Read)
• Clienttoepassings-id (client): de GUID van de toepassing die de ontwikkelaarsportal vertegenwoordigt
• Waarde van clienttoepassingsgeheim: de GUID die fungeert als het geheim voor interactie met de clienttoepassing in Microsoft Entra-id

Toepassingen registreren bij de OAuth-server

U moet twee toepassingen registreren bij uw OAuth 2.0-provider: één vertegenwoordigt de back-end-API die moet worden beveiligd en een tweede vertegenwoordigt de clienttoepassing die de API aanroept, in dit geval de testconsole van de ontwikkelaarsportal.

Hier volgen voorbeeldstappen met behulp van Microsoft Entra-id als de OAuth 2.0-provider. Zie quickstart: Een toepassing configureren om een web-API beschikbaar te maken voor meer informatie over app-registratie.

Een toepassing registreren in Microsoft Entra-id om de API weer te geven

1. Zoek in de Azure-portalApp-registraties en selecteer deze optie.

2. Selecteer Nieuwe registratie.

3. Wanneer de pagina Een toepassing registreren wordt weergegeven, voert u de registratiegegevens van uw toepassing in:

   • Voer in de sectie Naam een beschrijvende toepassingsnaam in die wordt weergegeven aan gebruikers van de app, zoals back-end-app.
   • Selecteer in de sectie Ondersteunde accounttypen een optie die bij uw scenario past.

4. Laat de sectie Omleidings-URI leeg. Later voegt u een omleidings-URI toe die is gegenereerd in de OAuth 2.0-configuratie in API Management.

5. Selecteer Registreren om de toepassing te maken.

6. Zoek de waarde Toepassings-id (client) op de app-pagina Overzicht en noteer deze voor later.

7. Selecteer in de sectie Beheren van het zijmenu een API beschikbaar maken en stel de URI van de toepassings-id in met de standaardwaarde. Noteer deze waarde voor later.

8. Selecteer de knop Een bereik toevoegen om de pagina Een bereik toevoegen weer te geven:

   1. Voer een bereiknaam in voor een bereik dat wordt ondersteund door de API (bijvoorbeeld Files.Read).
   2. Maak in Wie toestemming?, maak een selectie voor uw scenario, zoals Beheer s en gebruikers. Selecteer Beheer alleen voor scenario's met hogere bevoegdheden.
   3. Voer Beheer weergavenaam van toestemming in en Beheer beschrijving van toestemming.
   4. Zorg ervoor dat de bereikstatus Ingeschakeld is geselecteerd.

9. Selecteer de knop Bereik toevoegen om het bereik te maken.

10. Herhaal de vorige twee stappen om alle bereiken toe te voegen die door uw API worden ondersteund.

11. Zodra de bereiken zijn gemaakt, noteert u deze voor gebruik in een volgende stap.

Een andere toepassing registreren in Microsoft Entra-id om een clienttoepassing weer te geven

Registreer elke clienttoepassing die de API aanroept als een toepassing in Microsoft Entra-id.

1. Zoek in de Azure-portalApp-registraties en selecteer deze optie.

2. Selecteer Nieuwe registratie.

3. Wanneer de pagina Een toepassing registreren wordt weergegeven, voert u de registratiegegevens van uw toepassing in:

   • Voer in de sectie Naam een beschrijvende toepassingsnaam in die wordt weergegeven aan gebruikers van de app, zoals client-app.
   • Selecteer in de sectie Ondersteunde accounttypen een optie die bij uw scenario past.

4. Selecteer web in de sectie Omleidings-URI en laat het URL-veld voorlopig leeg.

5. Selecteer Registreren om de toepassing te maken.

6. Zoek de waarde Toepassings-id (client) op de app-pagina Overzicht en noteer deze voor later.

7. Maak een clientgeheim voor deze toepassing voor gebruik in een volgende stap.

   1. Selecteer Onder de sectie Beheren van het zijmenu certificaten en geheimen.
   2. Onder Clientgeheimen selecteert u + Nieuw clientgeheim.
   3. Geef onder Een clientgeheim toevoegen een beschrijving op en kies wanneer de sleutel moet verlopen.
   4. Selecteer Toevoegen.

Wanneer het geheim wordt gemaakt, noteert u de sleutelwaarde voor gebruik in een volgende stap. U hebt geen toegang meer tot het geheim in de portal.

Machtigingen verlenen in Microsoft Entra-id

Nu u twee toepassingen hebt geregistreerd die de API en de testconsole vertegenwoordigen, verleent u machtigingen om de client-app toe te staan de back-end-app aan te roepen.

1. Zoek in de Azure-portalApp-registraties en selecteer deze optie.

2. Kies uw client-app. Selecteer vervolgens API-machtigingen in het zijmenu.

3. Selecteer + Een machtiging toevoegen.

4. Selecteer onder Selecteer een API mijn API's en zoek en selecteer vervolgens uw back-end-app.

5. Selecteer Gedelegeerde machtigingen en selecteer vervolgens de juiste machtigingen voor uw back-end-app.

6. Selecteer Machtigingen toevoegen.

Optioneel:

1. Navigeer naar de api-machtigingenpagina van uw client-app.

2. Selecteer Beheerderstoestemming verlenen voor <de naam> van uw tenant om toestemming te verlenen namens alle gebruikers in deze directory.

Een OAuth 2.0-autorisatieserver configureren in API Management

1. Blader in Azure Portal naar uw API Management-exemplaar.

2. Selecteer onder Ontwikkelaarsportal in het zijmenu OAuth 2.0 + OpenID Verbinding maken.

3. Selecteer + Toevoegen op het tabblad OAuth 2.0.

   

4. Voer een naam en een optionele beschrijving in de velden Naam en Beschrijving in.

   Notitie

   Deze velden identificeren de OAuth 2.0-autorisatieserver binnen de huidige API Management-service. Hun waarden komen niet van de OAuth 2.0-server.

5. Voer de URL van de pagina Clientregistratie in, https://contoso.com/loginbijvoorbeeld. Op deze pagina kunnen gebruikers hun accounts maken en beheren als uw OAuth 2.0-provider gebruikersbeheer van accounts ondersteunt. De pagina is afhankelijk van de gebruikte OAuth 2.0-provider.

   Als uw OAuth 2.0-provider geen gebruikersbeheer van accounts heeft geconfigureerd, voert u hier een tijdelijke aanduiding in, zoals de URL van uw bedrijf of een URL zoals http://localhost.

   

6. De volgende sectie van het formulier bevat de autorisatietoestemmingstypen, de URL van het autorisatie-eindpunt en de instellingen voor de autorisatieaanvraagmethode.

   • Selecteer een of meer gewenste autorisatietoestemmingstypen. Voor dit voorbeeld selecteert u Autorisatiecode (de standaardinstelling). Meer informatie

   • Voer de URL van het autorisatie-eindpunt in. U kunt de eindpunt-URL verkrijgen op de pagina Eindpunten van een van uw app-registraties. Voor een app met één tenant in Microsoft Entra-id is deze URL vergelijkbaar met een van de volgende URL's, waarbij {aad-tenant} deze wordt vervangen door de id van uw Microsoft Entra-tenant.

     Het gebruik van het v2-eindpunt wordt aanbevolen; API Management ondersteunt echter zowel v1- als v2-eindpunten.

     https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/authorize (v2)

     https://login.microsoftonline.com/{aad-tenant}/oauth2/authorize (v1)

   • De autorisatieaanvraagmethode geeft aan hoe de autorisatieaanvraag naar de OAuth 2.0-server wordt verzonden. Selecteer POST.

   

7. Geef de eindpunt-URL van het token, methoden voor clientverificatie, de verzendmethode van het toegangstoken en het standaardbereik op.

   • Voer de eindpunt-URL van het token in. Voor één tenant-app in Microsoft Entra-id is deze vergelijkbaar met een van de volgende URL's, waarbij {aad-tenant} deze wordt vervangen door de id van uw Microsoft Entra-tenant. Gebruik dezelfde eindpuntversie (v2 of v1) die u eerder hebt gekozen.

     https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/token (v2)

     https://login.microsoftonline.com/{aad-tenant}/oauth2/token (v1)

   • Als u v1-eindpunten gebruikt, voegt u een hoofdtekstparameter toe:
     * Naam: resource.
     * Waarde: de toepassings-id van de back-end-app (client).

   • Als u v2-eindpunten gebruikt:
     * Voer het bereik van de back-end-app in dat u hebt gemaakt in het veld Standaardbereik .
     * Stel de waarde voor de accessTokenAcceptedVersion eigenschap 2 in het toepassingsmanifest in voor zowel de back-end-app als de client-app-registraties.

   • Accepteer de standaardinstellingen voor clientverificatiemethoden en de verzendmethode van het Access-token.

8. Voer in clientreferenties de client-id en het clientgeheim in die u hebt verkregen tijdens het maken en configureren van uw client-app.

9. Nadat de client-id en het clientgeheim zijn opgegeven, wordt de omleidings-URI voor de autorisatiecode gegenereerd. Deze URI wordt gebruikt om de omleidings-URI te configureren in de OAuth 2.0-serverconfiguratie.

   In de ontwikkelaarsportal heeft het achtervoegsel van de URI de volgende vorm:

   • /signin-oauth/code/callback/{authServerName} stroom voor het verlenen van autorisatiecode
   • /signin-oauth/implicit/callback voor impliciete toekenningsstroom

   

   Kopieer de juiste omleidings-URI naar de verificatiepagina van uw client-app-registratie. Selecteer in de app-registratie Verificatie>+ Een platformweb> toevoegen en voer vervolgens de omleidings-URI in.

10. Als autorisatietoekenningen zijn ingesteld op het wachtwoord van de resource-eigenaar, wordt de sectie Wachtwoordreferenties van de resource-eigenaar gebruikt om deze referenties op te geven. Anders kunt u deze leeg laten.

11. Selecteer Maken om de configuratie van de API Management OAuth 2.0-autorisatieserver op te slaan.

12. Publiceer de ontwikkelaarsportal opnieuw.

    Belangrijk

    Wanneer u OAuth 2.0-gerelateerde wijzigingen aanbrengt, moet u de ontwikkelaarsportal na elke wijziging opnieuw publiceren als relevante wijzigingen (bijvoorbeeld bereikwijziging) anders niet in de portal kunnen worden doorgegeven en vervolgens worden gebruikt bij het uitproberen van de API's.

Een API configureren voor het gebruik van OAuth 2.0-gebruikersautorisatie

Nadat u de OAuth 2.0-serverconfiguratie hebt opgeslagen, configureert u een API of API's om deze configuratie te gebruiken.

Belangrijk

• Als u OAuth 2.0-gebruikersautorisatie-instellingen voor een API configureert, kan API Management een token verkrijgen van de autorisatieserver wanneer u de testconsole gebruikt in de Azure-portal of in de ontwikkelaarsportal. De autorisatieserverinstellingen worden ook toegevoegd aan de API-definitie en -documentatie.
• Voor OAuth 2.0-autorisatie tijdens runtime moet de client-app het token verkrijgen en presenteren en moet u tokenvalidatie configureren in API Management of de back-end-API. Zie Een API beveiligen in Azure API Management met behulp van OAuth 2.0-autorisatie met Microsoft Entra-id voor een voorbeeld.

1. Selecteer API's in het menu API Management aan de linkerkant.

2. Selecteer de naam van de gewenste API en selecteer het tabblad Instellingen. Schuif naar de sectie Beveiliging en selecteer vervolgens OAuth 2.0.

3. Selecteer de gewenste autorisatieserver in de vervolgkeuzelijst en selecteer Opslaan.

   

Ontwikkelaarsportal: de OAuth 2.0-gebruikersautorisatie testen

Nadat u uw OAuth 2.0-autorisatieserver hebt geconfigureerd en uw API hebt geconfigureerd voor het gebruik van die server, kunt u deze testen door naar de ontwikkelaarsportal te gaan en een API aan te roepen.

1. Selecteer de ontwikkelaarsportal in het bovenste menu op de overzichtspagina van uw Azure API Management-exemplaar.

2. Blader naar een bewerking onder de API in de ontwikkelaarsportal.

3. Selecteer Probeer het om u naar de ontwikkelaarsconsole te brengen.

4. Noteer een nieuw item in de sectie Autorisatie , die overeenkomt met de autorisatieserver die u zojuist hebt toegevoegd.

5. Selecteer Autorisatiecode in de vervolgkeuzelijst autorisatie.

   

6. Meld u aan bij de Microsoft Entra-tenant nadat u hierom wordt gevraagd.

   • Als u al bent aangemeld bij het account, wordt u mogelijk niet gevraagd.

7. Nadat de aanmelding is geslaagd, wordt er een Authorization header toegevoegd aan de aanvraag, met een toegangstoken van Microsoft Entra-id. Hier volgt een afgekort voorbeeldtoken (Base64 gecodeerd):

   Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA
   

8. Configureer de gewenste waarden voor de resterende parameters en selecteer Verzenden om de API aan te roepen.

Een JWT-validatiebeleid configureren om aanvragen vooraf te autoriseren

In de configuratie tot nu toe valideert API Management het toegangstoken niet. Het token wordt alleen doorgegeven in de autorisatieheader aan de back-end-API.

Als u aanvragen vooraf wilt autoriseren, configureert u een validatie-jwt-beleid om het toegangstoken van elke binnenkomende aanvraag te valideren. Als een aanvraag geen geldig token heeft, blokkeert API Management dit.

Het volgende voorbeeldbeleid, wanneer dit wordt toegevoegd aan de <inbound> beleidssectie, controleert de waarde van de doelgroepclaim in een toegangstoken dat is verkregen van Microsoft Entra-id die wordt weergegeven in de autorisatieheader. Er wordt een foutbericht geretourneerd als het token ongeldig is. Configureer dit beleid op een beleidsbereik dat geschikt is voor uw scenario.

• In de openid-config URL is dit de aad-tenant tenant-id in Microsoft Entra-id. Zoek deze waarde in Azure Portal, bijvoorbeeld op de overzichtspagina van uw Microsoft Entra-resource. In het voorbeeld wordt ervan uitgegaan dat een Microsoft Entra-app met één tenant en een v2-configuratie-eindpunt wordt gebruikt.
• De waarde van het claim bestand is de client-id van de back-end-app die u hebt geregistreerd in Microsoft Entra-id.

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Notitie

De voorgaande openid-config URL komt overeen met het v2-eindpunt. Gebruik https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configurationvoor het v1-eindpunt openid-config .

Zie Beleidsregels instellen of bewerken voor meer informatie over het configureren van beleidsregels. Raadpleeg de referentie validate-jwt voor meer aanpassingen in JWT-validaties. Api Management biedt ook het validate-azure-ad-token beleid om een JWT te valideren die is geleverd door de Microsoft Entra-service.

Gerelateerde inhoud

• Zie Een web-API-back-end in Azure API Management beveiligen met OAuth 2.0-autorisatie met Microsoft Entra-id voor meer informatie over het gebruik van OAuth 2.0 en API Management.

• Meer informatie over het Microsoft Identity Platform en de OAuth 2.0-autorisatiecodestroom