Veilige toegang tot producten en API's met Microsoft Entra-toepassingen

VAN TOEPASSING OP: ontwikkelaar | Basic | Standard | Premium

API Management ondersteunt nu ingebouwde op OAuth 2.0 gebaseerde toegang tot product-API's met behulp van de clientreferentiestroom. Met deze functie kunnen API-beheerders Microsoft Entra ID-toepassingen registreren en beveiligde API-toegang stroomlijnen voor ontwikkelaars via OAuth 2.0-autorisatie.

Opmerking

Toepassingen zijn momenteel in beperkte preview. Vul dit formulier in om u aan te melden.

Met deze functie:

• API-beheerders stellen een producteigenschap in om toegang op basis van toepassingen mogelijk te maken.
• API-managers registreren clienttoepassingen in Microsoft Entra-id om de toegang tot specifieke producten te beperken.
• Met behulp van de OAuth 2.0-clientreferentiestroom verkrijgen ontwikkelaars of apps tokens die ze kunnen opnemen in API-aanvragen
• Tokens die worden weergegeven in API-aanvragen worden gevalideerd door de API Management-gateway om toegang tot de API's van het product te autoriseren.

Vereiste voorwaarden

• Een API Management-exemplaar dat is geïmplementeerd in de Premium-, Standard-, Basic- of Developer-laag . Zie Een API Management-service-exemplaar maken als u een exemplaar wilt implementeren.

• Ten minste één product in uw API Management-exemplaar, waaraan ten minste één API is toegewezen.

  • Het product moet de status Gepubliceerd hebben, zodat het toegankelijk is voor ontwikkelaars via de ontwikkelaarsportal.
  • Voor het testen kunt u het standaard Starter-product en de Echo-API gebruiken die eraan wordt toegevoegd.
  • Als u een product wilt maken, raadpleegt u Een product maken en publiceren.

• Voldoende machtigingen in uw Microsoft Entra-tenant om de rol Toepassingsbeheerder toe te wijzen. Hiervoor is ten minste de rol Beheerder van bevoorrechte rol vereist.

• Voeg eventueel een of meer gebruikers toe aan uw API Management-exemplaar.

• Als u ervoor kiest om Azure PowerShell lokaal te gebruiken:
  • Installeer de nieuwste versie van de Az PowerShell-module.
  • Maak verbinding met uw Azure-account met de cmdlet Connect-AzAccount.
• Als u ervoor kiest om Azure Cloud Shell te gebruiken:
  • Raadpleeg Overzicht van Azure Cloud Shell voor meer informatie.

Beheerde identiteit configureren

1. Schakel een door het systeem toegewezen beheerde identiteit in voor API Management in uw API Management-exemplaar.

2. Wijs de identiteit toe aan de RBAC-rol van de toepassingsbeheerder in Microsoft Entra-id. De rol toewijzen:

   1. Meld u aan bij de portal en navigeer naar Microsoft Entra-id.
   2. Selecteer in het linkermenu Beheren>rollen en beheerders.
   3. Selecteer Toepassingsbeheerder.
   4. Selecteer Beheren>Opdrachten>+ Opdrachten toevoegen in het linkermenu.
   5. Zoek op de pagina Toewijzingen toevoegen naar de beheerde identiteit van het API Management-exemplaar op naam (de naam van het API Management-exemplaar). Selecteer de beheerde identiteit en selecteer vervolgens Toevoegen.

Toegang op basis van toepassingen inschakelen voor product

Volg deze stappen om toegang op basis van toepassingen in te schakelen voor een product. Een product moet deze instelling ingeschakeld hebben om later aan een clienttoepassing te worden gekoppeld.

In het volgende voorbeeld wordt het Starter-product gebruikt, maar kiest u een gepubliceerd product waaraan ten minste één API is toegewezen.

1. Meld u aan bij de portal en navigeer naar uw API Management-exemplaar.
2. Selecteer Producten in het linkermenu onder API's.
3. Kies het product dat u wilt configureren, zoals het Starter-product .
4. Selecteer Eigenschappen in het linkermenu onder Product.
5. Schakel in de sectie Toegang op basis van toepassingen de OAuth 2.0-tokeninstelling (meest veilig) in.
6. Schakel desgewenst de instelling Abonnementssleutel in. Als u zowel op toepassingen gebaseerde toegang als een abonnementsvereiste inschakelt, kan de API Management-gateway een OAuth 2.0-token of een abonnementssleutel accepteren voor toegang tot de API's van het product.
7. Selecteer Opslaan.

Aanbeveling

U kunt ook de OAuth 2.0-tokeninstelling inschakelen bij het maken van een nieuw product.

Als u toegang op basis van toepassingen inschakelt, maakt u een back-end-bedrijfstoepassing in Microsoft Entra-id die het product vertegenwoordigt. De id van de back-endtoepassing wordt weergegeven op de pagina Eigenschappen van het product.

Opmerking

Deze toepassings-id wordt ingesteld als de doelgroepwaarde bij het maken van een clienttoepassing voor toegang tot het product. Gebruik deze waarde ook bij het genereren van een token om de product-API aan te roepen.

(Optioneel) Instellingen voor producttoepassingen controleren in Microsoft Entra-id

Controleer eventueel de instellingen van de back-end-bedrijfstoepassing die is gemaakt in Microsoft Entra-id om het product weer te geven.

De toepassing heeft de volgende indeling: APIMProductApplication-productnaam<>. Als de productnaam bijvoorbeeld Starter is, is de naam van de toepassing APIMProductApplicationStarter. De toepassing heeft een app-rol gedefinieerd.

Toepassingsinstellingen controleren in app-registraties:

1. Meld u aan bij de portal en navigeer naar Microsoft Entra ID>App-registraties>.
2. Selecteer Alle toepassingen.
3. Zoek en selecteer de toepassing die is gemaakt door API Management.
4. Selecteer app-rollen in het linkermenu onder Beheren.
5. Bevestig de toepassingsrol die is ingesteld door Azure API Management, zoals wordt weergegeven in de volgende schermopname:

Clienttoepassing registreren voor toegang tot product

Registreer nu een clienttoepassing die de toegang tot een of meer producten beperkt.

• Voor een product moet toegang op basis van toepassingen zijn ingeschakeld om aan een clienttoepassing te kunnen worden gekoppeld.
• Elke clienttoepassing heeft één gebruiker (eigenaar) in het API Management-exemplaar. Een eigenaar heeft toegang tot product-API's via de toepassing.
• Een product kan worden gekoppeld aan meer dan één clienttoepassing.

1. Meld u aan bij de portal en navigeer naar uw API Management-exemplaar.

2. Selecteer in het linkermenu, onder API's, de toepassing Applications>+ Register.

3. Voer op de pagina Een toepassing registreren de volgende toepassingsinstellingen in:

   • Naam: Voer een naam in voor de toepassing.
   • Eigenaar: Selecteer de eigenaar van de toepassing in de vervolgkeuzelijst met gebruikers in het API Management-exemplaar.
   • Toegang verlenen tot geselecteerde producten: Selecteer een of meer producten in het API Management-exemplaar dat eerder was ingeschakeld voor toegang op basis van toepassingen.
   • Beschrijving: Voer desgewenst een beschrijving in.

   

4. Selecteer Registreren.

De toepassing wordt toegevoegd aan de lijst met toepassingen op de pagina Toepassingen . Selecteer de toepassing om details weer te geven, zoals de client-id. U hebt deze id nodig om een token te genereren om de product-API aan te roepen.

Aanbeveling

• Nadat u een toepassing hebt gemaakt, kunt u deze eventueel koppelen aan andere producten. Selecteer de toepassing op de pagina Toepassingen en selecteer vervolgens Details>Producten>+ Product toevoegen.
• U kunt ook een toepassing maken of koppelen door een product te bewerken op de pagina Producten .

Clientgeheim genereren

Er moet een clientgeheim worden gegenereerd voor de clienttoepassing om de OAuth 2.0-clientreferentiestroom te kunnen gebruiken. Het geheim is één jaar geldig, maar kan op elk gewenst moment opnieuw worden gegenereerd.

1. Selecteer op de pagina Toepassingen de toepassing die u hebt gemaakt.

2. Selecteer Op de overzichtspagina van de toepassing, naast Clientgeheim, de optie Geheim toevoegen.

3. Selecteer Genereren op de pagina Nieuw clientgeheim.

   Er wordt een clientgeheim gegenereerd en weergegeven in het veld Clientgeheim . Zorg ervoor dat u de geheime waarde kopieert en veilig opslaat. U kunt deze niet meer ophalen nadat u de pagina hebt gesloten.

4. Selecteer Sluitaf.

(Optioneel) Instellingen voor clienttoepassingen controleren in Microsoft Entra-id

Controleer eventueel de instellingen van de clienttoepassing in Microsoft Entra-id.

De toepassing heeft de volgende indeling: APIMApplication-productnaam<>. Als de productnaam bijvoorbeeld Starter is, is de naam van de toepassing vergelijkbaar met APIMApplicationStarter.

Toepassingsinstellingen controleren in app-registraties:

1. Meld u aan bij de portal en navigeer naar Microsoft Entra ID>App-registraties>.

2. Selecteer Alle toepassingen.

3. Zoek en selecteer de clienttoepassing die is gemaakt door API Management.

4. Selecteer API-machtigingen in het linkermenu onder Beheren.

5. Controleer of de toepassing machtigingen heeft voor toegang tot de back-endproducttoepassing(en).

   Als de clienttoepassing bijvoorbeeld toegang verleent tot het Starter-product , heeft de toepassing Product.Starter.All-machtigingen voor toegang tot de APIMProductApplicationStarter-toepassing .

   

Token maken en gebruiken met API-aanroep

Nadat u toegang op basis van toepassingen voor een product hebt ingeschakeld en een clienttoepassing hebt geregistreerd, kan een ontwikkelaar of app een token genereren om de API's van het product aan te roepen. Het token moet worden opgenomen in de Authorization header van een aanvraag.

Een ontwikkelaar of app kan bijvoorbeeld de volgende Azure PowerShell-scripts uitvoeren om de clienttoepassing aan te roepen om een token te genereren en vervolgens het token te gebruiken om een product-API aan te roepen in API Management.

Waarschuwing

De volgende scripts zijn alleen voorbeelden voor testdoeleinden. Gebruik in productie een veilige methode om het clientgeheim op te slaan en op te halen.

Clienttoepassing aanroepen om token te genereren

# Replace placeholder values with your own values.

$clientId = "00001111-aaaa-2222-bbbb-3333cccc4444" # Client (application) ID of client application
$clientSecret = "******" # Retrieve secret of client application in developer portal
$scopeOfOtherApp = "api://55556666-ffff-7777-aaaa-8888bbbb9999/.default" # Value of Audience in product properties
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Directory (tenant) ID in Microsoft Entra ID

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = $scopeOfOtherApp
}
$response = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -ContentType "application/x-www-form-urlencoded" -Body $body
$token = $response.access_token

Product-API aanroepen met behulp van token

Het token dat in de vorige stap is gegenereerd, wordt gebruikt om een product-API aan te roepen. Het token wordt doorgegeven in de autorisatieheader van de aanvraag. Het API Management-exemplaar valideert het token en autoriseert toegang tot de API.

In het volgende script ziet u een voorbeeld van een aanroep naar de echo-API.

# Gatewate endpoint to call. Update with URI of API operation you want to call.
$uri = "https://<gateway-hostname>/echo/resource?param1=sample"
$headers = @{
   "Authorization" = "Bearer $token"  # $token is the token generated in the previous script.
}
$body = @{
    "hello" = "world"
} | ConvertTo-Json -Depth 5

$getresponse = Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/x-www-form-urlencoded" -Headers $headers -Body $body
Write-Host "Response:"
$getresponse | ConvertTo-Json -Depth 5

Verwante inhoud

• Een product maken en publiceren
• Verificatie en autorisatie voor API's in API Management