Delen via

API-beveiliging

Wanneer u, als ontwikkelaar, uw API beveiligt, richt u zich op autorisatie. Als u de API van uw resource wilt aanroepen, moeten toepassingen toepassingsautorisatie verkrijgen. De resource dwingt de autorisatie af. In dit artikel leert u aanbevolen procedures om uw Zero Trust-doelen te bereiken. Hierin wordt beschreven hoe u uw API beveiligt via registratie, machtiging en toestemmingsdefinitie en toegang afdwingen.

Uw beveiligde API registreren

Registreeruw API om uw API te beveiligen met Microsoft Entra ID (Microsoft Entra ID). Vervolgens kunt u uw geregistreerde API's beheren. In Microsoft Entra ID is een API een app met specifieke app-registratie-instellingen die deze definiëren als een resource of API waartoe een andere toepassing toegang heeft. In het Microsoft Entra-beheercentrum zijn Microsoft Identity Developerapp-registraties API's die zich in de tenant bevinden als API's voor lijngebonden activiteiten of als diensten van SaaS-providers (Software-as-a-Service) 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 entoepassingsmachtigingen. 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 voegt standaard User.Read toe 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> de toepassings-id van uw geregistreerde API is.

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 is in uw Microsoft Entra-tenant. 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 van de toepassings-id.

Gedelegeerde machtigingen met minimale bevoegdheid definiëren

Als toepassingen met gebruikers uw API gaan aanroepen, definieert u ten minste één gedelegeerde machtiging (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 slechte actoren die toegang willen krijgen 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 (wat een veelgebruikte maar technisch onnauwkeurige term is). Eén machtiging zoals deze staat alleen volledige bevoegde toegang tot uw API toe.

Declareer minimale bevoegdheden voor uw toepassingsbereiken, zodat uw toepassingen niet kwetsbaar zijn voor compromittering of worden gebruikt om een taak uit te voeren die u nooit hebt bedoeld. Definieer uw meerdere scopes in API-machtigingen. Scheid bijvoorbeeld toepassingsbereiken voor het lezen en schrijven van gegevens, en overweeg om alleen-lezenmachtigingen aan te bieden. Schrijftoegang omvat rechten om te maken, bij te werken en te verwijderen. 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 geven over welke scopes veilig alleen gebruikerstoestemming kunnen vereisen. 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.

Wanneer u besluit om toestemming van de gebruiker of beheerder, hebt u de volgende belangrijke overwegingen:

  • 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 (zoals het weergeven van volledige gebruikersprofielen van andere gebruikers), definieert u die machtiging als u beheerderstoestemming nodig hebt.

  • Of de omvang van de operaties achter de machtiging breed is. 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, definieert u toepassingsmachtigingen voor uw API. Wanneer u een toepassingsmachtiging definieert, gebruikt u een toepassingsrol in plaats van scopes.

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 het .default bereik, zoals gedemonstreerd in de voorbeeldcode hieronder.

// 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 de toegang afdwingen door de toegangstokens te valideren en te interpreteren die de aanroepende toepassingen als bearertokens in de autorisatieheader van de https aanvraag verstrekken. Toegang afdwingen door tokens te valideren, het vernieuwen van metagegevens te beheren en scopes en rollen af te dwingen, zoals beschreven in de volgende secties.

Tokens valideren

Nadat uw API een token heeft ontvangen, moet u ervoor zorgen dat het token wordt gevalideerd. Validatie garandeert dat het token afkomstig is van de juiste uitgever, ongewijzigd en onaangeroerd. 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 roteren en de sleutels die u hebt gedownload, de nieuwe geroteerde 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.

Reikwijdten 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 uw API het bereik (scp) controleren om te zien waar de toepassing toestemming voor heeft gekregen. 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 applicatie-autorisaties hebben geen claim voor bereik (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 scopes heeft gevalideerd en de object-id (oid), de onderwerpsleutel (sub) en rolclaims heeft verwerkt, kan uw API de resultaten retourneren.

Volgende stappen 

  • Last updated on