Rychlý start: Konfigurace aplikace pro zveřejnění webového rozhraní API

  • Článek

V tomto rychlém startu zaregistrujete webové rozhraní API na platformě Microsoft Identity Platform a zpřístupníte ho klientským aplikacím přidáním oboru. Registrací webového rozhraní API a jejím zveřejněním prostřednictvím oborů přiřazováním role vlastníka a aplikace můžete poskytnout přístup na základě oprávnění k jeho prostředkům autorizovaným uživatelům a klientským aplikacím, které přistupují k vašemu rozhraní API.

Požadavky

Registrace webového rozhraní API

Přístup k rozhraním API vyžaduje konfiguraci oborů přístupu a rolí. Pokud chcete zpřístupnit webová rozhraní API aplikace prostředků klientským aplikacím, nakonfigurujte obory přístupu a role pro rozhraní API. Pokud chcete, aby klientská aplikace přistupovala k webovému rozhraní API, nakonfigurujte oprávnění pro přístup k rozhraní API v registraci aplikace.

Pokud chcete poskytnout omezený přístup k prostředkům ve webovém rozhraní API, musíte nejprve zaregistrovat rozhraní API na platformě Microsoft Identity Platform.

Proveďte kroky v části Registrace aplikace v rychlém startu: Registrace aplikace na platformě Microsoft Identity Platform.

Přeskočte část Identifikátor URI přesměrování (volitelné). Pro webové rozhraní API nemusíte konfigurovat identifikátor URI přesměrování, protože žádný uživatel není přihlášený interaktivně.

Přiřazení vlastníka aplikace

  1. V registraci aplikace v části Spravovat vyberte Vlastníci a Přidat vlastníky.
  2. V novém okně vyhledejte a vyberte vlastníky, které chcete přiřadit k aplikaci. Vybraní vlastníci se zobrazí na pravém panelu. Po dokončení potvrďte výběr. Vlastník aplikace se teď zobrazí v seznamu vlastníka.

Poznámka:

Ujistěte se, že aplikace API i aplikace, ke které chcete přidat oprávnění k oběma, mají vlastníka, jinak se rozhraní API při vyžádání oprávnění rozhraní API nezobrazí.

Přiřazení role aplikace

  1. V registraci aplikace v části Spravovat vyberte Role aplikace a Vytvořte roli aplikace.

  2. V dalším kroku zadejte atributy role aplikace v podokně Vytvořit roli aplikace. Pro účely tohoto návodu můžete použít ukázkové hodnoty nebo zadat vlastní.

    Pole Description Příklad
    Zobrazované jméno Název role aplikace Záznamy zaměstnanců
    Povolené typy členů Určuje, jestli se role aplikace dá přiřadit uživatelům, skupinám nebo aplikacím. Aplikace
    Hodnota Hodnota zobrazená v deklaraci identity "role" tokenu Employee.Records
    Popis Podrobnější popis role aplikace Aplikace mají přístup k záznamům zaměstnanců

  3. Zaškrtnutím políčka povolte roli aplikace.

S zaregistrovaným webovým rozhraním API přiřazenou rolí a vlastníkem aplikace můžete přidat obory do kódu rozhraní API, aby mohl uživatelům poskytovat podrobné oprávnění.

Přidat obor

Tip

Postup v tomto článku se může mírně lišit v závislosti na portálu, od který začínáte.

Kód v klientské aplikaci požaduje oprávnění k provádění operací definovaných vaším webovým rozhraním API předáním přístupového tokenu spolu s požadavky na chráněný prostředek (webové rozhraní API). Vaše webové rozhraní API pak provede požadovanou operaci pouze v případě, že přístupový token, který obdrží, obsahuje obory požadované pro operaci.

Nejprve následujícím postupem vytvořte ukázkový obor s názvem Employees.Read.All:

  1. Přihlaste se do Centra pro správu Microsoft Entra jako alespoň cloudová aplikace Správa istrator.

  2. Pokud máte přístup k více tenantům, pomocí ikony Nastavení v horní nabídce přepněte do tenanta, který obsahuje registraci aplikace z nabídky Adresáře a předplatná.

  3. Přejděte na Aplikace> identit>Registrace aplikací a pak vyberte registraci aplikace rozhraní API.

  4. Výběr možnosti Zveřejnit rozhraní API

  5. Pokud jste ho ještě nenakonfigurovali, vyberte Přidat vedle identifikátoru URI ID aplikace.

    Můžete použít výchozí hodnotu nebo jiný podporovaný vzor identifikátoru api://<application-client-id> URI ID aplikace. Identifikátor URI ID aplikace funguje jako předpona pro obory, na které budete odkazovat v kódu rozhraní API, a musí být globálně jedinečný.

  6. Vyberte Přidat obor:

    An app registration's Expose an API pane in the Azure portal

  7. Dále zadejte atributy oboru v podokně Přidat obor . Pro účely tohoto návodu můžete použít ukázkové hodnoty nebo zadat vlastní.

    Pole Description Příklad
    Název oboru Název vašeho oboru. Běžnou konvencí pojmenování oboru je resource.operation.constraint. Employees.Read.All
    Kdo může vyjádřit souhlas Bez ohledu na to, jestli tento rozsah můžou uživatelé udělit souhlas nebo jestli je vyžadován souhlas správce. Pro oprávnění s vyššími privilegii vyberte možnost Jen správci. Správa a uživatelé
    Zobrazovaný název souhlasu správce Stručný popis účelu oboru, který uvidí jenom správci. Read-only access to Employee records
    Popis souhlasu správce Podrobnější popis oprávnění uděleného oborem, který uvidí jenom správci. Allow the application to have read-only access to all Employee data.
    Zobrazovaný název souhlasu uživatele Stručný popis účelu oboru. Zobrazí se uživatelům jenom v případě, že nastavíte Kdo může udělit souhlas s Správa a uživateli. Read-only access to your Employee records
    Popis souhlasu uživatele Podrobnější popis oprávnění uděleného oborem. Zobrazí se uživatelům jenom v případě, že nastavíte Kdo může udělit souhlas s Správa a uživateli. Allow the application to have read-only access to your Employee data.

  8. Nastavte stav na Povoleno a pak vyberte Přidat obor.

  9. (Volitelné) Pokud chcete potlačit výzvu k vyjádření souhlasu uživatelům vaší aplikace s definovanými obory, můžete předběžně autorizovat klientskou aplikaci pro přístup k webovému rozhraní API. Předběžné autorizace pouze těch klientských aplikací, kterým důvěřujete, protože vaši uživatelé nebudou mít možnost odmítnout souhlas.

    1. V části Autorizované klientské aplikace vyberte Přidat klientskou aplikaci.
    2. Zadejte ID aplikace (klienta) klientské aplikace, kterou chcete předem autorizovat. Například webovou aplikaci, kterou jste předtím zaregistrovali.
    3. V části Autorizované obory vyberte obory, pro které chcete potlačit zobrazování výzev k vyjádření souhlasu, a pak vyberte Přidat aplikaci.

    Pokud jste postupovali podle tohoto volitelného kroku, klientská aplikace je teď předem autorizovanou klientskou aplikací (PCA) a uživatelům se při přihlášení k němu nezobrazí výzva k vyjádření souhlasu.

Dále přidejte další ukázkový obor s názvem Employees.Write.All , ke kterému můžou souhlasit jenom správci. Obory, které vyžadují souhlas správce, se obvykle používají k poskytování přístupu k operacím s vyššími oprávněními a často klientskými aplikacemi, které běží jako back-endové služby nebo démony, které se nepřihlašují interaktivně.

Pokud chcete přidat Employees.Write.All ukázkový obor, postupujte podle kroků v části Přidat obor a zadejte tyto hodnoty v podokně Přidat obor :

Pole Příklad hodnoty
Název oboru Employees.Write.All
Kdo může vyjádřit souhlas pouze Správa
Zobrazovaný název souhlasu správce Write access to Employee records
Popis souhlasu správce Allow the application to have write access to all Employee data.
Zobrazovaný název souhlasu uživatele Žádné (ponechejte prázdné)
Popis souhlasu uživatele Žádné (ponechejte prázdné)

Nastavte stav na Povoleno a pak vyberte Přidat obor.

Ověření vystavených oborů

Pokud jste úspěšně přidali oba ukázkové obory popsané v předchozích částech, zobrazí se v podokně Zveřejnit rozhraní API registrace aplikace vašeho webového rozhraní API , podobně jako na následujícím obrázku:

Screenshot of the Expose an API pane showing two exposed scopes.

Jak je znázorněno na obrázku, úplný řetězec oboru je zřetězení identifikátoru URI ID aplikace vašeho webového rozhraní API a názvu oboru.

Pokud je například identifikátor URI https://contoso.com/api ID aplikace vašeho webového rozhraní API a název oboru je Employees.Read.All, úplný obor je:

https://contoso.com/api/Employees.Read.All

Použití vystavených oborů

V dalším článku této řady nakonfigurujete registraci klientské aplikace s přístupem k webovému rozhraní API a rozsahy, které jste definovali podle kroků v tomto článku.

Po udělení oprávnění pro přístup k webovému rozhraní API je možné klientovi vydat přístupový token OAuth 2.0 platformou Identity Platform. Když klient volá webové rozhraní API, zobrazí přístupový token, jehož obor (scp) deklarace identity je nastavený na oprávnění, která jste zadali v registraci aplikace klienta.

Další obory můžete podle potřeby zveřejnit později. Vezměte v úvahu, že webové rozhraní API může vystavit více oborů přidružených k několika operacím. Váš prostředek může řídit přístup k webovému rozhraní API za běhu vyhodnocením deklarací oboru (scp) v přístupovém tokenu OAuth 2.0, který obdrží.

Další kroky

Teď, když jste zpřístupnili webové rozhraní API konfigurací jeho oborů, nakonfigurujte registraci klientské aplikace s oprávněním pro přístup k oborům.

Konfigurace registrace aplikace pro přístup k webovému rozhraní API