Ochrana rozhraní API

Když jako vývojář chráníte své rozhraní API, zaměřte se na autorizaci. Aby bylo potřeba volat rozhraní API vašeho prostředku, musí aplikace získat autorizaci aplikací. Prostředek vynucuje autorizaci. V tomto článku se naučíte osvědčené postupy pro dosažení cílů nulové důvěryhodnosti . Popisuje, jak chránit rozhraní API prostřednictvím registrace, oprávnění a definice souhlasu a vynucení přístupu.

Registrace chráněného rozhraní API

Pokud chcete rozhraní API chránit pomocí Microsoft Entra ID (Microsoft Entra ID), zaregistrujte své rozhraní API. Pak můžete spravovat registrovaná rozhraní API. V Microsoft Entra ID je API aplikace, která má specifická nastavení registrace, jež ji definují jako zdroj nebo rozhraní API, ke kterému má přístup jiná aplikace. V Centru pro správu Microsoft Entra jsou Microsoft Identity Developer, registrace aplikací rozhraní API, která jsou v tenantovi buď jako čistě podniková rozhraní API, nebo služby od poskytovatelů Softwaru jako služby (SaaS), které mají rozhraní API, která chrání ID Microsoft Entra.

Během registrace definujete, jak volání aplikací odkazuje na vaše rozhraní API a jeho delegovanáoprávnění a oprávnění aplikace. Registrace aplikace může představovat řešení, které má klientské aplikace i rozhraní API. V tomto článku se ale zabýváme scénářem, kdy samostatný prostředek zveřejňuje rozhraní API.

Za normálních okolností rozhraní API neprovádí ověřování ani přímo žádá o autorizaci. Rozhraní API ověří token, který volající aplikace prezentuje. Rozhraní API nemají interaktivní přihlášení, takže nemusíte registrovat nastavení, jako je identifikátor URI přesměrování nebo typ aplikace. Rozhraní API získají své tokeny z aplikací, které tato rozhraní API volají, nikoli interakcí s ID Microsoft Entra. Pro webová rozhraní API použijte pro autorizaci přístupové tokeny OAuth2. Webová rozhraní API ověřují nosné tokeny pro autorizaci volajících. Nepřijme tokeny ID jako doklad o oprávnění.

Ve výchozím nastavení Microsoft Entra ID přidá User.Read do oprávnění rozhraní API jakékoli nové registrace aplikace. Toto oprávnění odeberete pro většinu webových rozhraní API. Microsoft Entra ID vyžaduje oprávnění rozhraní API pouze v případech, kdy rozhraní API volá jiné rozhraní API. Pokud vaše rozhraní API nevolá jiné rozhraní API, odeberte User.Read oprávnění při registraci rozhraní API.

Potřebujete jedinečný identifikátor rozhraní API, který se označuje jako identifikátor URI ID aplikace, aby klientské aplikace, které potřebují přístup k rozhraní API, požádaly o oprávnění volat vaše rozhraní API. Identifikátor URI ID aplikace musí být jedinečný pro všechny tenanty Microsoft Entra. Můžete použít api://<clientId> (výchozí návrh na portálu), kde <clientId> je ID aplikace registrovaného rozhraní API.

Pokud chcete vývojářům, kteří volají vaše rozhraní API, poskytnout uživatelsky přívětivější název, můžete jako identifikátor URI ID aplikace použít adresu svého rozhraní API. Můžete například použít https://API.yourdomain.com , kde yourdomain.com je nakonfigurovaná doména vydavatele ve vašem tenantovi Microsoft Entra. Microsoft ověří, že máte vlastnictví domény, abyste ji mohli použít jako jedinečný identifikátor vašeho rozhraní API. Na této adrese nemusíte mít kód. Rozhraní API může být všude, kde chcete, ale je vhodné použít https adresu rozhraní API jako identifikátor URI ID aplikace.

Definování delegovaných oprávnění s nejnižšími oprávněními

Pokud aplikace, které mají uživatele, budou volat vaše rozhraní API, definujte aspoň jedno delegovaná oprávnění (viz Přidání oboru pro registraci aplikace – Zveřejnění rozhraní API).

Rozhraní API, která poskytují přístup k úložištům dat organizace, můžou upoutat pozornost špatných herců, kteří chtějí získat přístup k datům. Místo toho, abyste měli jenom jedno delegovaná oprávnění, navrhněte svá oprávnění principem nulové důvěryhodnosti přístupu s nejnižšími oprávněními . Pokud všechny klientské aplikace začínají úplným privilegovaným přístupem, může být obtížné se později dostat k nejméně privilegovanému modelu.

Vývojáři často mají tendenci používat jedno oprávnění, jako přístup jako uživatel nebo zosobnění uživatele (což je běžná technicky nepřesná fráze). Jedno oprávnění, jako jsou tato, umožňují pouze úplný privilegovaný přístup k vašemu rozhraní API.

Deklarujte oprávnění podle principu nejnižších privilegií, aby vaše aplikace nebyly zranitelné nebo používány k provádění úkolu, který jste nikdy nezamýšleli. Definujte více oborů v oprávněních rozhraní API. Například oddělené obory od čtení a aktualizace dat a zvažte možnost nabízet oprávnění jen pro čtení. Přístup k zápisu zahrnuje oprávnění pro operace vytvoření, aktualizace a odstranění. Klient by nikdy neměl vyžadovat přístup k zápisu pouze ke čtení dat.

Při práci s citlivými daty zvažte standardní a úplná přístupová oprávnění. Omezte citlivé vlastnosti tak, aby standardní oprávnění nepovolovalo přístup (například Resource.Read). Pak implementujte úplné přístupové oprávnění (například Resource.ReadFull), které vrací vlastnosti a citlivé informace.

Vždy vyhodnoťte oprávnění, která požadujete, abyste zajistili, že hledáte absolutně nejméně privilegovanou sadu potřebnou k vykonání úlohy. Vyhněte se vyžádání vyšších oprávnění. Místo toho vytvořte jednotlivá oprávnění pro každý základní scénář. Informace o vhodných příkladech tohoto přístupu najdete v referenčních informacích k oprávněním Microsoft Graphu . Vyhledejte a použijte správný počet oprávnění k řešení vašich potřeb.

V rámci definic oboru rozhodněte, jestli rozsah operací, který se dá provést s konkrétním oborem, vyžaduje souhlas správce.

Jako návrhář rozhraní API můžete poskytnout pokyny k tomu, které obory můžou bezpečně vyžadovat pouze souhlas uživatele. Správci tenantů ale můžou tenanta nakonfigurovat tak, aby všechna oprávnění vyžadovala souhlas správce. Pokud definujete obor, který vyžaduje souhlas správce, oprávnění vždy vyžaduje souhlas správce.

Při rozhodování o souhlasu uživatele nebo správce máte tyto hlavní aspekty:

  • Určuje, jestli rozsah operací za oprávněním ovlivňuje více než jednoho uživatele. Pokud oprávnění umožňuje uživateli zvolit, která aplikace má přístup jenom k vlastním informacím, může být souhlas uživatele vhodný. Uživatel může například souhlasit s výběrem preferované aplikace pro e-mail. Pokud ale operace za oprávněním zahrnují více než jednoho uživatele (například zobrazení úplných profilů uživatelů jiných uživatelů), definujte toto oprávnění jako vyžadování souhlasu správce.

  • Určuje, zda operace spjaté s oprávněním mají širokou působnost. Široký rozsah je například v případě, že oprávnění aplikaci umožní změnit všechno v tenantovi nebo udělat něco, co by mohlo být nevratné. Široký rozsah označuje, že místo souhlasu uživatele vyžadujete souhlas správce.

Když si nejste jistí, jednejte raději opatrně a žádejte o souhlas správce. Jasně a výstižně popište důsledky souhlasu v řetězcích oprávnění. Předpokládejme, že jednotlivec, který čte vaše popisové řetězce, nemá žádnou znalost vašich rozhraní API nebo produktu.

Vyhněte se přidávání rozhraní API k existujícím oprávněním způsobem, který mění sémantiku oprávnění. Přetížení stávajících oprávnění zředí odůvodnění, na kterém klienti dříve udělili souhlas.

Definování oprávnění aplikace

Při vytváření neuživatelových aplikací nemáte uživatele, kterého můžete vyzvat k zadání uživatelského jména a hesla nebo vícefaktorového ověřování (MFA). Pokud aplikace bez uživatelů (jako jsou úlohy, služby a démony) volají vaše rozhraní API, definujte oprávnění aplikace pro vaše rozhraní API. Při definování oprávnění aplikace místo použití oborů použijte roli aplikace .

Stejně jako u delegovaných oprávnění poskytujete podrobná oprávnění aplikace, aby úlohy, které volají vaše rozhraní API, mohly dodržovat přístup s nejnižšími oprávněními a v souladu s principy nulové důvěryhodnosti. Vyhněte se publikování jenom jedné role aplikace (oprávnění aplikace) a jednoho oboru (delegovaného oprávnění) nebo vystavení všech operací každému klientovi.

Úlohy se ověřují pomocí přihlašovacích údajů klienta a požadují token s .default oborem , jak je znázorněno v následujícím ukázkovém kódu.

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

Oprávnění vyžadují souhlas správce, pokud před aplikací není žádný uživatel a když oprávnění aplikace umožňuje širokou škálu operací.

Vynucení přístupu

Ujistěte se, že vaše rozhraní API vynucují přístup tím, že ověřují a interpretují přístupové tokeny, které volající aplikace poskytují jako nosné tokeny v https autorizační hlavičce požadavku. Vynucujte přístup ověřováním tokenů, správou aktualizace metadat a vynucováním oborů a rolí, jak je popsáno v následujících částech.

Ověření tokenů

Jakmile vaše rozhraní API obdrží token, ujistěte se, že token ověří. Ověření zajišťuje, že token pochází od správného vystavitele v nezměněné podobě. Zkontrolujte podpis, protože token nezískáte přímo z ID Microsoft Entra, jak to uděláte s tokeny ID. Ověřte podpis po přijetí tokenu z nedůvěryhodného zdroje v síti.

Vzhledem k tomu, že kolem ověřování podpisu webového tokenu JSON existují známá ohrožení zabezpečení, použijte dobře udržovanou a zavedenou standardní ověřovací knihovnu tokenů. Knihovny ověřování (například Microsoft.Identity.Web) používají správné kroky a zmírňují známé chyby zabezpečení.

Volitelně můžete rozšířit ověření tokenu. Pomocí deklarace tenant ID (tid) omezte na tenanty, ve kterých může vaše rozhraní API získat token. Pomocí nároků azp a appid můžete filtrovat aplikace, které můžou volat vaše rozhraní API. Pomocí deklarace IDENTITY objektu (oid) můžete dále zúžit přístup k jednotlivým uživatelům.

Správa aktualizace metadat

Vždy se ujistěte, že vaše knihovna ověřování tokenů efektivně spravuje požadovaná metadata. V tomto případě jsou metadata veřejnými klíči, dvojicí privátních klíčů, kterou Microsoft používá k podepisování tokenů Microsoft Entra. Když vaše knihovny tyto tokeny ověří, získají náš publikovaný seznam veřejných podpisových klíčů z dobře známé internetové adresy. Ujistěte se, že hostitelské prostředí má správné načasování pro získání těchto klíčů.

Například starší knihovny byly někdy pevně zakódované tak, aby tyto veřejné podpisové klíče aktualizovaly každých 24 hodin. Zvažte, kdy Microsoft Entra ID musí tyto klíče rychle obměnit a klíče, které jste stáhli, nezahrnují nově obměněné klíče. Vaše rozhraní API může být offline po dobu jednoho dne, než čeká na cyklus aktualizace metadat. Odkazujte na konkrétní pokyny k aktualizaci metadat, abyste metadata správně získali. Pokud používáte knihovnu, ujistěte se, že zpracovává tato metadata v rozumném čase.

Vynucení oborů a rolí

Po ověření tokenu se vaše rozhraní API podívá na deklarace identity v tokenu a určí, jak má fungovat.

U delegovaných tokenů oprávnění přimějte svoje rozhraní API zkontrolovat nárok oboru (scp) a zjistit, k čemu má aplikace oprávnění. Zkontrolujte ID objektu () nebo klíč subjektu (oidsub) a zobrazte uživatele, jehož jménem aplikace pracuje.

Pak zkontrolujte rozhraní API a ujistěte se, že má uživatel také přístup k požadované operaci. Pokud vaše rozhraní API definuje role pro přiřazování uživatelům a skupinám, požádejte rozhraní API, aby v tokenu hledaly deklarace identity rolí a chovaly se odpovídajícím způsobem. Tokeny oprávnění aplikace nemají deklaraci oboru (scp). Namísto toho nechte své rozhraní API zkontrolovat nároky rolí, aby určilo, jaká oprávnění aplikace pracovní úkol obdržel.

Jakmile vaše rozhraní API ověří token a obory a zpracuje ID objektu (oid), klíč subjektu (sub) a deklarace identity rolí, může vaše rozhraní API vrátit výsledky.

Další kroky

  • Last updated on