Chráněné webové rozhraní API: Registrace aplikace

  • Článek

Tento článek vysvětluje specifika registrace aplikace pro chráněné webové rozhraní API.

Běžné kroky registrace aplikace najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.

Přijatá verze tokenu

Platforma Microsoft Identity Platform může vydávat tokeny v1.0 a tokeny v2.0. Další informace o těchto tokenech najdete v tématu Přístupové tokeny.

Verze tokenu, kterou vaše rozhraní API může přijmout, závisí na výběru podporovaných typů účtů při vytváření registrace aplikace webového rozhraní API na webu Azure Portal.

  • Pokud je hodnota podporovaných typůúčtů Účty v libovolném organizačním adresáři a osobních účtech Microsoft (např. Skype, Xbox, Outlook.com), musí být verze přijatého tokenu verze 2.0.
  • V opačném případě může být verze přijatého tokenu verze 1.0.

Po vytvoření aplikace můžete určit nebo změnit přijatou verzi tokenu pomocí následujícího postupu:

  1. Na webu Azure Portal vyberte aplikaci a pak vyberte Manifest.
  2. Vyhledejte vlastnost accessTokenAcceptedVersion v manifestu.
  3. Hodnota určuje Microsoft Entra, která verze tokenu, kterou webové rozhraní API přijímá.
    • Pokud je hodnota 2, webové rozhraní API přijímá tokeny v2.0.
    • Pokud je hodnota null, webové rozhraní API přijímá tokeny v1.0.
  4. Pokud jste změnili verzi tokenu, vyberte Uložit.

Webové rozhraní API určuje, jakou verzi tokenu přijímá. Když klient požádá o token pro webové rozhraní API z platformy Microsoft Identity Platform, klient získá token, který označuje verzi tokenu, kterou webové rozhraní API přijímá.

Žádný identifikátor URI přesměrování

Webová rozhraní API nemusí registrovat identifikátor URI přesměrování, protože žádný uživatel není interaktivně přihlášený.

Vystavené rozhraní API

Další nastavení specifická pro webová rozhraní API jsou vystavené rozhraní API a vystavené obory nebo role aplikací.

Obory a identifikátor URI ID aplikace

Obory obvykle mají formulář resourceURI/scopeName. Pro Microsoft Graph mají obory klávesové zkratky. Jedná se například User.Read o zástupce pro https://graph.microsoft.com/user.read.

Během registrace aplikace definujte tyto parametry:

  • Identifikátor URI prostředku
  • Jeden nebo více oborů
  • Jedna nebo více rolí aplikací

Ve výchozím nastavení portál pro registraci aplikací doporučuje použít identifikátor URI api://{clientId}prostředku . Tento identifikátor URI je jedinečný, ale není čitelný člověkem. Pokud změníte identifikátor URI, ujistěte se, že je nová hodnota jedinečná. Portál pro registraci aplikací zajistí, že používáte nakonfigurovanou doménu vydavatele.

U klientských aplikací se obory zobrazují jako delegovaná oprávnění a role aplikací se zobrazují jako oprávnění aplikace pro webové rozhraní API.

Obory se také zobrazí v okně souhlasu, které se zobrazí uživatelům vaší aplikace. Proto zadejte odpovídající řetězce, které popisují obor:

  • Jak je vidět uživatelem.
  • Jak je vidět správce tenanta, který může udělit souhlas správce.

Role aplikací nemůžou udělit souhlas s uživatelem (protože je používá aplikace, která volá webové rozhraní API jménem sebe). Správce tenanta bude muset souhlasit s klientskými aplikacemi vašeho webového rozhraní API, které zpřístupňuje role aplikací. Podrobnosti najdete v Správa souhlasu.

Zveřejnění delegovaných oprávnění (oborů)

Pokud chcete vystavit delegovaná oprávnění nebo obory, postupujte podle kroků v části Konfigurace aplikace pro zveřejnění webového rozhraní API.

Pokud sledujete společně se scénářem webového rozhraní API popsaným v této sadě článků, použijte tato nastavení:

  • Identifikátor URI ID aplikace: Přijměte navrhovaný identifikátor URI ID aplikace (api://< clientId>) (pokud se zobrazí výzva)
  • Název oboru: access_as_user
  • Kdo může souhlasit: Správa a uživatelé
  • Správa zobrazovaný název souhlasu: Access TodoListService jako uživatel
  • Správa popis souhlasu: Přistupuje k webovému rozhraní API TodoListService jako uživatel.
  • Zobrazovaný název souhlasu uživatele: Access TodoListService jako uživatel
  • Popis souhlasu uživatele: Přístup k webovému rozhraní API TodoListService jako uživatel
  • Stav: Povoleno

Tip

Pro identifikátor URI ID aplikace máte možnost ji nastavit na fyzickou autoritu rozhraní API, například https://graph.microsoft.com. To může být užitečné, pokud je známá adresa URL rozhraní API, které je potřeba volat.

Pokud se vaše webové rozhraní API volá službou nebo aplikací démon

Zpřístupnit oprávnění aplikace místo delegovaných oprávnění, pokud k vašemu rozhraní API mají přistupovat démoni, služby nebo jiné neinteraktivní (lidské) aplikace. Vzhledem k tomu, že aplikace démona a aplikace typu služby spouštějí bezobslužné ověřování a ověřují se pomocí vlastní identity, neexistuje žádný uživatel, který by "delegoval" své oprávnění.

Zveřejnění oprávnění aplikace (role aplikací)

Pokud chcete zpřístupnit oprávnění aplikace, postupujte podle kroků v části Přidání rolí aplikace do aplikace.

V podokně Vytvořit roli aplikace v části Povolené typy členů vyberte Aplikace. Nebo přidejte roli pomocí editoru manifestu aplikace, jak je popsáno v článku.

Omezenípřístupch

Role aplikací jsou mechanismus, který vývojář aplikací používá ke zveřejnění oprávnění aplikace. Kód webového rozhraní API by měl zkontrolovat role aplikace v přístupových tokenech, které přijímá od volajících.

Pokud chcete přidat další vrstvu zabezpečení, může správce tenanta Microsoft Entra nakonfigurovat svého tenanta, aby platforma Microsoft Identity Platform vydá tokeny zabezpečení jenom klientským aplikacím, které schválil pro přístup k rozhraní API.

Pokud chcete zvýšit zabezpečení tím, že omezíte vystavování tokenů jenom klientským aplikacím, které mají přiřazené role aplikací:

  1. V Centru pro správu Microsoft Entra vyberte aplikaci v části Aplikace> identit>Registrace aplikací.
  2. Na stránce přehledu aplikace vyberte její spravovanou aplikaci v odkazu na místní adresář a přejděte na stránku Přehled podnikových aplikací.
  3. V části Spravovat vyberte Vlastnosti.
  4. Nastavit požadované přiřazení? na Ano.
  5. Zvolte Uložit.

ID Microsoft Entra teď zkontroluje přiřazení rolí aplikací klientských aplikací, které požadují přístupové tokeny pro vaše webové rozhraní API. Pokud klientská aplikace nepřiřadila žádné role aplikace, vrátí ID Microsoft Entra chybovou zprávu klientovi podobné invalid_client: AADSTS501051: Název> aplikace <není přiřazen k roli webového <rozhraní API>.

Upozorňující

NEPOUŽÍVEJTE kódy chyb AADSTS nebo jejich řetězce zpráv jako literály v kódu vaší aplikace. Kódy chyb "AADSTS" a řetězce chybových zpráv vrácené id Microsoft Entra nejsou neměnné a společnost Microsoft je může kdykoli a bez vašich znalostí změnit. Pokud v kódu rozhodujete o větvení na základě hodnot kódů AADSTS nebo jejich řetězců zpráv, riskujete funkčnost a stabilitu aplikace.

Další kroky

Dalším článkem této série je konfigurace kódu aplikace.