Ochrana rozhraní API

  • Článek

Když jako vývojář chráníte své rozhraní API, zaměřujete se na autorizaci. Aby bylo potřeba volat rozhraní API vašeho prostředku, musí aplikace získat autorizaci aplikací. Samotný prostředek musí vynutit autorizaci. V tomto článku se dozvíte osvědčené postupy pro ochranu rozhraní API prostřednictvím registrace, definování oprávnění a souhlasu a vynucování přístupu k dosažení nulová důvěra (Zero Trust) cílů.

Registrace chráněného rozhraní API

Pokud chcete rozhraní API chránit pomocí Microsoft Entra ID (Microsoft Entra ID ), nejprve zaregistrujete své rozhraní API, po kterém můžete spravovat registrovaná rozhraní API. V Microsoft Entra ID je rozhraní API aplikací s konkrétními nastaveními registrace aplikace, která ji definují jako prostředek nebo rozhraní API, ke kterému může mít jiná aplikace oprávnění pro přístup. V Centru pro správu Microsoft Entra jsou rozhraní API microsoft Identity Developer, Registrace aplikací, rozhraní API, která jsou v tenantovi buď jako obchodní rozhraní API, nebo služby od poskytovatelů SaaS, kteří mají rozhraní API, která microsoft Entra ID chrání.

Během registrace definujete, jak budou volající aplikace odkazovat 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 budeme zabývat 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 prezentovaný volající aplikací. Rozhraní API nebudou mít 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. Id Microsoft Entra 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.

Budete potřebovat jedinečný identifikátor vašeho 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 musí být 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 adresu HTTPS rozhraní API jako identifikátor URI ID aplikace.

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

Pokud se vaše rozhraní API bude volat aplikacemi, které mají uživatele, musíte definovat aspoň jedno delegované oprávnění (viz Přidání oboru registrace aplikace – Zveřejnění rozhraní API).

Rozhraní API, která poskytují přístup k úložištům dat organizace, můžou upoutat pozornost útočníků, 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í pomocí zásady nulová důvěra (Zero Trust) 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 spadají do vzoru použití jednoho oprávnění, jako je "přístup jako uživatel" nebo "zosobnění uživatele" (což je běžná fráze, i když technicky nepřesná). Jedno oprávnění, jako jsou tato, umožňují pouze úplný privilegovaný přístup k vašemu rozhraní API.

Deklarujte obory nejnižších oprávnění, aby vaše aplikace byly ohroženy ohrožením zabezpečení nebo používány k provádění úlohy, kterou 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.

Pokud vaše rozhraní API pracuje 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í privilegovanou sadu pro dokončení ú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, bude oprávnění vždy vyžadovat souhlas správce.

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

  1. 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 pouze 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.

  2. Určuje, jestli rozsah operací za oprávněním má široký rozsah. Š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.

Rr na konzervativní straně a požadovat souhlas správce, pokud máte pochybnosti. 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í aplikací bez uživatele 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 vaše rozhraní API bude volat aplikace bez uživatelů (jako jsou úlohy, služby a démony), musíte definovat oprávnění aplikace pro vaše rozhraní API. Když definujete oprávnění aplikace, použijete místo oborů roli aplikace.

Stejně jako u delegovaných oprávnění poskytnete podrobná oprávnění aplikace, aby úlohy, které volají vaše rozhraní API, mohly sledovat přístup s nejnižšími oprávněními a v souladu s principy nulová důvěra (Zero Trust). 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 pomocí .default oboru , 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 ověřováním a interpretací přístupových tokenů, které volající aplikaci poskytují jako nosné tokeny v autorizační hlavičce požadavku HTTPS. Přístup můžete vynutit 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ěřování tokenů

Jakmile vaše rozhraní API obdrží token, musí token ověřit. Ověření zajišťuje, že token pochází od správného vystavitele jako neopravovaného a neupraveného. 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 nebo Passport, pokud vytváříte uzel), používají správné kroky a zmírňují známé chyby zabezpečení.

Volitelně můžete rozšířit ověření tokenu. Pomocí deklarace IDENTITY tenanta (tid) omezte tenanty, ve kterých může vaše rozhraní API získat token. azp Pomocí deklarací appid identity 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 dobře známé internetové adresy dostanou náš publikovaný seznam veřejných podpisových klíčů. 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 musí ID Microsoft Entra tyto klíče rychle otočit a klíče, které jste stáhli, nezahrnou nové otočené klíče. Vaše rozhraní API může být offline po dobu jednoho dne, než čeká na cyklus aktualizace metadat. Provázejte konkrétní pokyny k aktualizaci metadat, abyste měli jistotu, že metadata správně získáte. Pokud používáte knihovnu, ujistěte se, že tato metadata zachází s rozumným načasováním.

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í požádejte vaše rozhraní API o kontrolu deklarace oboru (scp) a zjistěte, co má aplikace souhlasit. 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 má vaše rozhraní API definované role pro přiřazování uživatelům a skupinám, požádejte vaše rozhraní API, aby v tokenu vyhledávají deklarace identity rolí a chovají se odpovídajícím způsobem. Pro tokeny oprávnění aplikace nebude k dispozici žádná deklarace oboru (scp). Místo toho rozhraní API určete, jaká oprávnění aplikace úloha přijala, kontrolou deklarací identity rolí.

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