Zveřejnění oborů v chráněném webovém rozhraní API

Platí pro: Nájemníci z řad pracovní síly (další informace)

Tento článek vysvětluje, jak přidat obory do aplikace pro chráněné webové rozhraní API.

Požadavky

• Zaregistrujte novou aplikaci v Centru pro správu Microsoft Entra, která je nakonfigurovaná jenom pro účty v tomto organizačním adresáři. Další podrobnosti najdete v tématu Registrace aplikace . Na stránce Přehled aplikace si poznamenejte následující hodnoty pro pozdější použití:
  • ID aplikace (klienta)
  • ID adresáře (klienta)

Obory a identifikátor URI ID aplikace

Rozsahy obvykle mají tvar resourceURI/scopeName. Pro Microsoft Graph mají obory klávesové zkratky. Například User.Read je zkratka pro https://graph.microsoft.com/user.read.

Během registrace aplikace definujte tyto parametry:

• 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í zajišťuje, ž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.

Rozsahy 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.
• Z pohledu správce tenanta, který může udělit souhlas správce.

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

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 scénář webového API popsaný 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ávci a uživatelé
• Zobrazovaný název souhlasu správce: Přístup k todoListService jako uživatel
• Popis souhlasu správce: Přístup k webovému rozhraní API TodoListService jako uživatel
• Zobrazovaný název souhlasu uživatele: Přístup k TodoListService jako uživatel
• Popis souhlasu uživatele: Přístup k webovému rozhraní API TodoListService jako uživatel
• Stav: Povoleno

Návod

Identifikátor URI ID aplikace můžete 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 démonní aplikací

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émonového typu a typu služby běží bez uživatelského dohledu a ověřují se pomocí vlastní identity, neexistuje žádný uživatel, který by mohl "delegovat" své oprávnění.

Zpřístupnění oprávnění aplikace (role aplikace)

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.

Omezit přístupové tokeny na specifické klientské aplikace

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í pouze klientským aplikacím, které správce tenanta 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 svou aplikaci v částiRegistrace aplikace>.
2. Na stránce aplikace Přehled, v části Základy, vyhledejte a vyberte odkaz její Spravovaná aplikace v místním adresáři, abyste přešli na stránku Přehled podnikových aplikací.
3. V části Spravovat vyberte Vlastnosti.
4. Nastavit Požadováno přiřazení? na Ano.
5. Vyberte Uložit.

Microsoft Entra ID teď zkontroluje přiřazení rolí klientských aplikací, které požadují přístupové tokeny pro vaše webové API. Pokud klientská aplikace nepřiřadila žádné role aplikace, vrátí ID Microsoft Entra chybovou zprávu klientovi podobnému _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_.

Výstraha

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ší krok

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