Skydda API:er

  • Artikel

När du som utvecklare skyddar ditt API fokuserar du på auktorisering. För att anropa resursens API måste program hämta programauktorisering. Själva resursen måste framtvinga auktoriseringen. I den här artikeln får du lära dig metodtips för att skydda ditt API genom registrering, definiera behörigheter och medgivande och framtvinga åtkomst för att uppnå dina Nolltillit mål.

Registrera ditt skyddade API

För att skydda ditt API med Microsoft Entra ID (Microsoft Entra ID) registrerar du först ditt API, varefter du kan hantera dina registrerade API:er. I Microsoft Entra-ID är ett API en app med specifika appregistreringsinställningar som definierar den som en resurs eller ett API som ett annat program kan ha behörighet att komma åt. I administrationscentret för Microsoft Entra är Microsoft Identity Developer Appregistreringar API:er som finns i klientorganisationen antingen som verksamhetsspecifika API:er eller tjänster från SaaS-leverantörer som har API:er som Microsoft Entra-ID skyddar.

Under registreringen definierar du hur anropande program ska referera till ditt API och dess delegerade behörigheter och programbehörigheter. En appregistrering kan representera en lösning som har både klientprogram och API:er. I den här artikeln tar vi dock upp scenariot där en fristående resurs exponerar ett API.

Normalt utför inte ett API autentisering eller ber direkt om auktorisering. API:et verifierar en token som presenteras av den anropande appen. API:er har inte interaktiva inloggningar, så du behöver inte registrera inställningar som omdirigerings-URI eller programtyp. API:er får sina token från de program som anropar dessa API:er, inte genom att interagera med Microsoft Entra-ID. För webb-API:er använder du OAuth2-åtkomsttoken för auktorisering. Webb-API:er validerar ägartoken för att auktorisera anropare. Acceptera inte ID-token som ett behörighetsbevis.

Som standard lägger User.Read Microsoft Entra-ID till API-behörigheterna för alla nya appregistreringar. Du tar bort den här behörigheten för de flesta webb-API:er. Microsoft Entra-ID kräver endast API-behörigheter när ett API anropar ett annat API. Om ditt API inte anropar ett annat API tar du bort behörigheten User.Read när du registrerar ditt API.

Du behöver en unik identifierare för ditt API, som kallas program-ID-URI, som klientappar som behöver komma åt ditt API ber om behörighet att anropa ditt API. Program-ID-URI:n måste vara unik för alla Microsoft Entra-klienter. Du kan använda api://<clientId> (standardförslaget i portalen), där <clientId> är program-ID:t för ditt registrerade API.

Om du vill ge utvecklare som anropar ditt API ett mer användarvänligt namn kan du använda API:ets adress som program-ID-URI. Du kan till exempel använda https://API.yourdomain.com var yourdomain.com måste vara en konfigurerad utgivardomän i din Microsoft Entra-klientorganisation. Microsoft verifierar att du har ägarskap för domänen så att du kan använda den som unik identifierare för ditt API. Du behöver inte ha kod på den här adressen. API:et kan vara var du vill att det ska vara, men det är en bra idé att använda HTTPS-adressen för API:et som program-ID-URI.

Definiera delegerade behörigheter med minst behörighet

Om ditt API ska anropas av program som har användare måste du definiera minst en delegerad behörighet (se Lägg till ett omfång för appregistreringen Exponera ett API).

API:er som ger åtkomst till organisationens datalager kan uppmärksammas av angripare som vill komma åt dessa data. I stället för att bara ha en delegerad behörighet utformar du dina behörigheter med Nolltillit princip för åtkomst med minst behörighet i åtanke. Det kan vara svårt att komma in i en modell med minst privilegier senare om alla klientappar börjar med fullständig privilegierad åtkomst.

Ofta hamnar utvecklare i ett mönster för att använda en enda behörighet som "åtkomst som användare" eller "användarpersonifiering" (vilket är en vanlig fras även om det är tekniskt felaktigt). Enskilda behörigheter som dessa tillåter endast fullständig, privilegierad åtkomst till ditt API.

Deklarera minsta behörighetsomfång så att dina program inte är sårbara för intrång eller används för att utföra en uppgift som du aldrig avsåg. Definiera flera omfång i API-behörigheter. Du kan till exempel separera omfång från att läsa och uppdatera data och överväga att erbjuda skrivskyddade behörigheter. "Skrivåtkomst" innehåller behörigheter för att skapa, uppdatera och ta bort åtgärder. En klient ska aldrig kräva skrivåtkomst till endast läsdata.

Överväg "standard" och "fullständig" åtkomstbehörighet när ditt API fungerar med känsliga data. Begränsa de känsliga egenskaperna så att en standardbehörighet inte tillåter åtkomst (till exempel Resource.Read). Implementera sedan en "fullständig" åtkomstbehörighet (till exempel Resource.ReadFull) som returnerar egenskaper och känslig information.

Utvärdera alltid behörigheter som du begär för att säkerställa att du söker den absolut minst privilegierade uppsättningen för att få jobbet gjort. Undvik att begära behörigheter med högre behörighet. Skapa i stället en enskild behörighet för varje kärnscenario. I referensen för Microsoft Graph-behörigheter finns bra exempel på den här metoden. Leta upp och använd precis rätt antal behörigheter för att uppfylla dina behov.

Som en del av omfångsdefinitionerna bestämmer du om det åtgärdsintervall som kan utföras med ett visst omfång kräver administratörsmedgivande.

Som API-designer kan du ge vägledning om vilka omfång som på ett säkert sätt endast kan kräva användarmedgivande. Klientadministratörer kan dock konfigurera en klientorganisation så att alla behörigheter kräver administratörsmedgivande. Om du definierar ett omfång som kräver administratörsmedgivande kräver behörigheten alltid administratörsmedgivande.

När du beslutar om användar- eller administratörsmedgivande har du två huvudsakliga överväganden:

  1. Om intervallet för åtgärder bakom behörigheten påverkar mer än en enskild användare. Om behörighet tillåter användaren att välja vilket program som endast kan komma åt sin egen information kan användarens medgivande vara lämpligt. Användaren kan till exempel samtycka till att välja önskat program för e-post. Men om åtgärderna bakom behörigheten omfattar mer än en enskild användare (till exempel att visa fullständiga användarprofiler för andra användare) definierar du behörigheten som att kräva administratörsmedgivande.

  2. Om intervallet för åtgärder bakom behörigheten har ett brett omfång. Ett brett omfång är till exempel när en behörighet gör det möjligt för en app att ändra allt i en klientorganisation eller att göra något som kan vara oåterkalleligt. Ett brett omfång anger att du behöver administratörsmedgivande i stället för användarmedgivande.

Fel på den konservativa sidan och kräver administratörsmedgivande om du är osäker. Beskriv tydligt och koncist konsekvenserna av medgivande i dina behörighetssträngar. Anta att den person som läser beskrivningssträngarna inte känner till dina API:er eller produkt.

Undvik att lägga till dina API:er i befintliga behörigheter på ett sätt som ändrar behörighetens semantik. Överlagring av befintliga behörigheter späder ut det resonemang som klienter tidigare gav medgivande till.

Definiera programbehörigheter

När du skapar icke-användarprogram har du ingen användare som du kan fråga efter användarnamn och lösenord eller multifaktorautentisering (MFA). Om ditt API anropas av program utan användare (till exempel arbetsbelastningar, tjänster och daemoner) måste du definiera programbehörigheter för ditt API. När du definierar en programbehörighet använder du en programroll i stället för att använda omfång.

Precis som med delegerade behörigheter tillhandahåller du detaljerade programbehörigheter så att arbetsbelastningar som anropar ditt API kan följa lägsta behörighetsåtkomst och följa Nolltillit principer. Undvik att bara publicera en approll (appbehörighet) och ett omfång (delegerad behörighet) eller exponera alla åtgärder för varje klient.

Arbetsbelastningar autentiserar med klientautentiseringsuppgifter och begär en token med hjälp av omfånget .default enligt följande exempelkod.

// 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");
}

Behörigheter kräver administratörsmedgivande när det inte finns någon användare framför appen och när programbehörigheten möjliggör ett brett spektrum av åtgärder.

Framtvinga åtkomst

Se till att dina API:er framtvingar åtkomst genom att verifiera och tolka åtkomsttoken som anropar programmet tillhandahåller som ägartoken i HTTPS-begärans auktoriseringshuvud. Du kan framtvinga åtkomst genom att validera token, hantera metadatauppdatering och framtvinga omfång och roller enligt beskrivningen i följande avsnitt.

Validera token

När api:et har fått en token måste den verifiera token. Validering säkerställer att token kommer från rätt utfärdare som ostämplad och oförändrad. Kontrollera signaturen eftersom du inte får token direkt från Microsoft Entra-ID som du gör med ID-token. Verifiera signaturen när ditt API tar emot en token från en ej betrodd källa i nätverket.

Eftersom det finns kända sårbarheter kring verifiering av JSON-webbtokensignatur använder du ett väl underhållet och etablerat standardverifieringsbibliotek för token. Autentiseringsbibliotek (till exempel Microsoft.Identity.Web eller Passport, om du skapar en nod) använder rätt steg och åtgärdar kända säkerhetsproblem.

Du kan också utöka tokenverifieringen. Använd klientorganisations-ID-anspråket (tid) för att begränsa klientorganisationer där ditt API kan hämta en token. Använd anspråken azp och appid för att filtrera appar som kan anropa ditt API. Använd objekt-ID-anspråket (oid) för att ytterligare begränsa åtkomsten till enskilda användare.

Hantera metadatauppdatering

Se alltid till att valideringsbiblioteket för token effektivt hanterar nödvändiga metadata. I det här fallet är metadata de offentliga nycklarna, paret med privata nycklar, som Microsoft använder för att signera Microsoft Entra-token. När dina bibliotek validerar dessa token får de vår publicerade lista över offentliga signeringsnycklar från en välkänd Internetadress. Se till att värdmiljön har rätt tid för att hämta nycklarna.

Till exempel hårdkodades äldre bibliotek ibland för att uppdatera de offentliga signeringsnycklarna var 24:e timme. Tänk på när Microsoft Entra-ID:t snabbt måste rotera dessa nycklar och de nycklar som du laddade ned inte innehåller de nya roterade nycklarna. Ditt API kan vara offline en dag medan det väntar på uppdateringscykeln för metadata. Referera till specifika riktlinjer för metadatauppdatering för att se till att du får metadata korrekt. Om du använder ett bibliotek ska du se till att det behandlar dessa metadata inom rimlig tid.

Framtvinga omfång och roller

När du har verifierat din token tittar API:et på anspråken i token för att avgöra hur den ska fungera.

För delegerade behörighetstoken måste ditt API inspektera omfångsanspråket (scp) för att se vad programmet har medgivande att göra. Granska objekt-ID:t (oid) eller ämnesnyckeln (sub) anspråk för att se användaren för vars räkning programmet fungerar.

Be sedan API-kontrollen att se till att användaren också har åtkomst till den begärda åtgärden. Om ditt API har definierade roller för att tilldela till användare och grupper ska du låta API:et söka efter eventuella rollanspråk i token och bete sig därefter. För programbehörighetstoken finns det inget omfångsanspråk (scp). Låt i stället API:et avgöra vilka programbehörigheter arbetsbelastningen har fått genom att granska rollanspråket.

När api:et har verifierat token och omfång och bearbetat objekt-ID :t (oid), ämnesnyckeln (sub) och rollanspråken kan ditt API returnera resultatet.

Nästa steg