Delen via

API-beveiliging

  • Artikel

Wanneer u, als ontwikkelaar, uw API beveiligt, is uw focus op autorisatie. Als u de API van uw resource wilt aanroepen, moeten toepassingen toepassingsautorisatie verkrijgen. De resource zelf moet de autorisatie afdwingen. In dit artikel leert u aanbevolen procedures voor het beveiligen van uw API via registratie, het definiëren van machtigingen en toestemming en het afdwingen van toegang om uw Zero Trust-doelen te bereiken.

Uw beveiligde API registreren

Als u uw API wilt beveiligen met Microsoft Entra ID (Microsoft Entra ID), registreert u eerst uw API, waarna u uw geregistreerde API's kunt beheren. In Microsoft Entra ID is een API een app met specifieke app-registratie-instellingen die deze definiëren als een resource of API die een andere toepassing kan worden geautoriseerd voor toegang. In het Microsoft Entra-beheercentrum zijn Microsoft Identity Developer, App-registraties, API's die zich in de tenant bevinden als line-of-business-API's of services van SaaS-providers die API's hebben die door Microsoft Entra ID worden beveiligd.

Tijdens de registratie definieert u hoe aanroepende toepassingen verwijzen naar uw API en de gedelegeerde en toepassingsmachtigingen. Een app-registratie kan een oplossing vertegenwoordigen die zowel clienttoepassingen als API's bevat. In dit artikel behandelen we echter het scenario waarin een zelfstandige resource een API beschikbaar maakt.

Normaal gesproken voert een API geen verificatie uit of vraagt deze rechtstreeks om autorisatie. De API valideert een token dat door de aanroepende app wordt weergegeven. API's hebben geen interactieve aanmeldingen, dus u hoeft geen instellingen te registreren, zoals omleidings-URI of toepassingstype. API's halen hun tokens op uit de toepassingen die deze API's aanroepen, niet door interactie met Microsoft Entra-id. Voor web-API's gebruikt u OAuth2-toegangstokens voor autorisatie. Web-API's valideren bearertokens om bellers te autoriseren. Accepteer geen id-tokens als bewijs van toestemming.

Microsoft Entra-id wordt standaard toegevoegd User.Read aan de API-machtigingen van elke nieuwe app-registratie. U verwijdert deze machtiging voor de meeste web-API's. Microsoft Entra ID vereist alleen API-machtigingen wanneer een API een andere API aanroept. Als uw API geen andere API aanroept, verwijdert u de User.Read machtiging wanneer u uw API registreert.

U hebt een unieke id nodig voor uw API, ook wel de URI van de toepassings-id genoemd, die client-apps die toegang nodig hebben tot uw API, vragen om toestemming om uw API aan te roepen. De URI van de toepassings-id moet uniek zijn in alle Microsoft Entra-tenants. U kunt (de standaardsuggesties in de portal) gebruiken api://<clientId> , waar <clientId> is de toepassings-id van uw geregistreerde API.

Als u ontwikkelaars wilt bieden die uw API aanroepen met een gebruiksvriendelijkere naam, kunt u het adres van uw API gebruiken als uw URI voor de toepassings-id. U kunt bijvoorbeeld gebruiken https://API.yourdomain.com waar yourdomain.com een geconfigureerd uitgeverdomein in uw Microsoft Entra-tenant moet zijn. Microsoft valideert dat u eigenaar bent van het domein, zodat u het kunt gebruiken als de unieke id voor uw API. U hoeft geen code op dit adres te hebben. De API kan overal zijn waar u deze wilt, maar het is een goede gewoonte om het HTTPS-adres van de API te gebruiken als de URI voor de toepassings-id.

Gedelegeerde machtigingen met minimale bevoegdheid definiëren

Als uw API wordt aangeroepen door toepassingen die gebruikers hebben, moet u ten minste één gedelegeerde machtiging definiëren (zie Een bereik toevoegen voor de app-registratie een API beschikbaar maken).

API's die toegang bieden tot gegevensarchieven van organisaties, kunnen de aandacht trekken van aanvallers die toegang willen tot die gegevens. In plaats van slechts één gedelegeerde machtiging te hebben, ontwerpt u uw machtigingen met het Zero Trust-principe van toegang met minimale bevoegdheden in gedachten. Het kan lastig zijn om later in een model met minimale bevoegdheden te komen als alle client-apps beginnen met volledige bevoegde toegang.

Ontwikkelaars vallen vaak in een patroon van het gebruik van één machtiging, zoals 'toegang als gebruiker' of 'gebruikersimitatie' (dit is een algemene woordgroep, hoewel technisch onnauwkeurig). Eén machtiging zoals deze staat alleen volledige, bevoegde toegang tot uw API toe.

Declareer bereiken met minimale bevoegdheden, zodat uw toepassingen niet kwetsbaar zijn voor inbreuk of worden gebruikt om een taak uit te voeren die u nooit hebt bedoeld. Definieer uw meerdere bereiken in API-machtigingen. Scheid bijvoorbeeld bereiken van het lezen en bijwerken van gegevens en overweeg om alleen-lezenmachtigingen aan te bieden. Schrijftoegang bevat bevoegdheden voor het maken, bijwerken en verwijderen van bewerkingen. Een client mag nooit schrijftoegang vereisen voor alleen leesgegevens.

Overweeg 'standaard' en 'volledige' toegangsmachtigingen wanneer uw API werkt met gevoelige gegevens. Beperk de gevoelige eigenschappen zodat een standaardmachtiging geen toegang toestaat (bijvoorbeeld Resource.Read). Implementeer vervolgens een machtiging voor volledige toegang (bijvoorbeeld Resource.ReadFull) die eigenschappen en gevoelige informatie retourneert.

Evalueer altijd machtigingen die u aanvraagt om ervoor te zorgen dat u de absolute minst bevoegde set zoekt om de taak uit te voeren. Vermijd het aanvragen van machtigingen voor hogere bevoegdheden. Maak in plaats daarvan een afzonderlijke machtiging voor elk kernscenario. Raadpleeg de naslaginformatie over Microsoft Graph-machtigingen voor goede voorbeelden van deze aanpak. Zoek en gebruik alleen het juiste aantal machtigingen om aan uw behoeften te voldoen.

Als onderdeel van uw bereikdefinities moet u bepalen of het bereik van de bewerking die met een bepaald bereik kan worden uitgevoerd, beheerderstoestemming vereist.

Als API-ontwerper kunt u richtlijnen opgeven voor welke bereiken alleen gebruikerstoestemming is vereist. Tenantbeheerders kunnen echter een tenant configureren, zodat alle machtigingen beheerderstoestemming vereisen. Als u een bereik definieert als beheerderstoestemming vereisen, is voor de machtiging altijd beheerderstoestemming vereist.

Bij het bepalen van toestemming van de gebruiker of beheerder hebt u twee belangrijke overwegingen:

  1. Of het bereik van bewerkingen achter de machtiging meer dan één gebruiker beïnvloedt. Als de gebruiker met toestemming kan kiezen welke toepassing alleen toegang heeft tot hun eigen gegevens, is gebruikerstoestemming mogelijk geschikt. De gebruiker kan bijvoorbeeld toestemming geven voor het kiezen van de gewenste toepassing voor e-mail. Als de bewerkingen achter de machtiging echter meer dan één gebruiker omvatten (bijvoorbeeld het weergeven van volledige gebruikersprofielen van andere gebruikers), definieert u die machtiging als het vereisen van beheerderstoestemming.

  2. Of het bereik van bewerkingen achter de machtiging een breed bereik heeft. Een breed bereik is bijvoorbeeld wanneer een machtiging een app in staat stelt om alles in een tenant te wijzigen of iets te doen dat mogelijk niet ongedaan kan worden. Een breed bereik geeft aan dat u beheerderstoestemming nodig hebt in plaats van toestemming van de gebruiker.

Err aan de conservatieve kant en vereist beheerderstoestemming als u twijfelt. Beschrijf duidelijk en beknopt de gevolgen van toestemming in uw machtigingstekenreeksen. Stel dat de persoon die uw beschrijvingstekenreeksen leest, geen vertrouwdheid heeft met uw API's of product.

Voeg uw API's niet toe aan bestaande machtigingen op een manier die de semantiek van de machtiging wijzigt. Het overbelasten van bestaande machtigingen verdunt de redenering waarop clients eerder toestemming hebben verleend.

Toepassingsmachtigingen definiëren

Wanneer u niet-gebruikerstoepassingen bouwt, hebt u geen gebruiker die u kunt vragen om een gebruikersnaam en wachtwoord of Meervoudige verificatie (MFA). Als toepassingen zonder gebruikers (zoals workloads, services en daemons) uw API aanroepen, moet u toepassingsmachtigingen voor uw API definiëren. Wanneer u een toepassingsmachtiging definieert, gebruikt u een toepassingsrol in plaats van bereiken.

Net als bij gedelegeerde machtigingen biedt u gedetailleerde toepassingsmachtigingen, zodat workloads die uw API aanroepen, toegang tot minimale bevoegdheden kunnen volgen en in overeenstemming zijn met zero Trust-principes. Vermijd het publiceren van slechts één app-rol (app-machtiging) en één bereik (gedelegeerde machtiging) of het blootstellen van alle bewerkingen aan elke client.

Workloads worden geverifieerd met clientreferenties en vragen een token aan met behulp van het .default bereik , zoals wordt gedemonstreerd in de volgende voorbeeldcode.

// With client credentials flows the scopes is ALWAYS of the shape "resource/.default", as the 
// application permissions need to be set statically (in the portal or by PowerShell), 
// and then granted by a tenant administrator
string[] scopes = new string[] { "https://kkaad.onmicrosoft.com/webapi/.default" };
 
AuthenticationResult result = null;
try
{
  result = await app.AcquireTokenForClient(scopes)
    .ExecuteAsync();
  Console.WriteLine("Token acquired \n");
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
  // Invalid scope. The scope has to be of the form "https://resourceurl/.default"
  // Mitigation: change the scope to be as expected
  Console.WriteLine("Scope provided is not supported");
}

Voor machtigingen is beheerderstoestemming vereist wanneer er geen gebruiker voor de app is en wanneer de toepassingsmachtiging een breed scala aan bewerkingen mogelijk maakt.

Toegang afdwingen

Zorg ervoor dat uw API's toegang afdwingen door toegangstokens te valideren en te interpreteren die toepassingen aanroepen als bearertokens in de autorisatieheader van de HTTPS-aanvraag. U kunt toegang afdwingen door tokens te valideren, het vernieuwen van metagegevens te beheren en bereiken en rollen af te dwingen, zoals beschreven in de volgende secties.

Tokens valideren

Nadat uw API een token heeft ontvangen, moet het token worden gevalideerd. Validatie zorgt ervoor dat het token afkomstig is van de juiste uitgever als niet-gehard en ongewijzigd. Controleer de handtekening omdat u het token niet rechtstreeks van Microsoft Entra-id krijgt, net als bij id-tokens. Valideer de handtekening nadat uw API een token ontvangt van een niet-vertrouwde bron in het netwerk.

Omdat er bekende beveiligingsproblemen zijn rond verificatie van JSON-webtokenhandtekening, gebruikt u een goed onderhouden en gevestigde standaardtokenvalidatiebibliotheek. Verificatiebibliotheken (zoals Microsoft.Identity.Web) gebruiken de juiste stappen en beperken voor bekende beveiligingsproblemen.

U kunt ook de tokenvalidatie uitbreiden. Gebruik de tenant-id (tid)-claim om de tenants te beperken waarin uw API een token kan verkrijgen. Gebruik de azp en appid claims om apps te filteren die uw API kunnen aanroepen. Gebruik de claim object-id (oid) om de toegang tot afzonderlijke gebruikers verder te beperken.

Vernieuwen van metagegevens beheren

Zorg er altijd voor dat uw tokenvalidatiebibliotheek de vereiste metagegevens effectief beheert. In dit geval zijn de metagegevens de openbare sleutels, het paar persoonlijke sleutels, dat Microsoft gebruikt om Microsoft Entra-tokens te ondertekenen. Wanneer uw bibliotheken deze tokens valideren, krijgen ze onze gepubliceerde lijst met openbare ondertekeningssleutels van een bekend internetadres. Zorg ervoor dat de hostingomgeving de juiste timing heeft om deze sleutels op te halen.

Oudere bibliotheken zijn bijvoorbeeld af en toe hard gecodeerd om die openbare ondertekeningssleutels om de 24 uur bij te werken. Overweeg wanneer Microsoft Entra ID deze sleutels snel moet draaien en de sleutels die u hebt gedownload, de nieuwe gedraaide sleutels niet bevatten. Uw API kan een dag offline zijn terwijl er wordt gewacht op de cyclus voor het vernieuwen van metagegevens. Raadpleeg de richtlijnen voor het vernieuwen van specifieke metagegevens om ervoor te zorgen dat u de metagegevens op de juiste manier krijgt. Als u een bibliotheek gebruikt, moet u ervoor zorgen dat deze metagegevens binnen redelijke tijd worden behandeld.

Bereiken en rollen afdwingen

Nadat u uw token hebt gevalideerd, kijkt uw API naar de claims in het token om te bepalen hoe het moet werken.

Voor gedelegeerde machtigingstokens moet u de API het bereik (scp) laten inspecteren om te zien wat de toepassing moet doen. Inspecteer de object-id (oid) of de onderwerpsleutel (sub) claims om de gebruiker te zien namens wie de toepassing werkt.

Controleer vervolgens uw API om ervoor te zorgen dat de gebruiker ook toegang heeft tot de aangevraagde bewerking. Als uw API rollen definieert voor het toewijzen aan gebruikers en groepen, moet u uw API controleren op rollenclaims in het token en zich dienovereenkomstig gedragen. Tokens voor toepassingsmachtigingen hebben geen bereikclaim (scp). Laat uw API in plaats daarvan de rollenclaim inspecteren om te bepalen welke toepassingsmachtigingen de workload heeft ontvangen.

Nadat uw API het token en de bereiken heeft gevalideerd en de object-id (oid), de onderwerpsleutel (sub) en rolclaims heeft verwerkt, kan uw API de resultaten retourneren.

Volgende stappen