Sdílet prostřednictvím

Autorizace a role v Tvůrci rozhraní DATA API

  • Článek

Tvůrce rozhraní API pro data používá pracovní postup autorizace na základě role. Každý příchozí požadavek, ověřený nebo ne, se přiřadí k roli. Role můžou být systémové role nebo role uživatelů. Přiřazená role se pak zkontroluje podle definovaných oprávnění zadaných v konfiguračním souboru , abyste zjistili, jaké akce, pole a zásady jsou pro danou roli v požadované entitě k dispozici.

Role

Role nastavují kontext oprávnění, ve kterém se má požadavek spustit. Pro každou entitu definovanou v konfiguraci modulu runtime můžete definovat sadu rolí a přidružených oprávnění, které určují, jak lze k entitě přistupovat v koncových bodech REST i GraphQL.

Tvůrce rozhraní API data vyhodnocuje požadavky v kontextu jedné role:

  • anonymous pokud se nezobrazí žádný přístupový token.
  • authenticated při předložení platného přístupového tokenu.
  • <CUSTOM_USER_ROLE>při předložení platného přístupového tokenu X-MS-API-ROLEa zahrnutí hlavičky HTTP určující roli uživatele, která je také součástí deklarace identity přístupového roles tokenu.

Role nejsou sčítá, což znamená, že uživatel, který je členem obou Role1 rolí a Role2 nedědí oprávnění přidružená k oběma rolím.

Systémové role

Systémové role jsou předdefinované role rozpoznané tvůrcem rozhraní Data API. Role systému se automaticky přiřadí žadateli bez ohledu na členství v roli žadatele označené v jeho přístupových tokenech. Existují dvě systémové role: anonymous a authenticated.

Anonymní role systému

Role anonymous systému je přiřazena k požadavkům spuštěným neověřenými uživateli. Pokud je požadovaný neověřený přístup, musí entity definované v konfiguraci modulu runtime obsahovat oprávnění pro anonymous roli.

Příklad

Následující konfigurace modulu runtime nástroje Data API Builder ukazuje explicitní konfiguraci role anonymous systému tak, aby zahrnovala přístup pro čtení k entitě Book:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ]
        }
    ]
}

Když klientská aplikace odešle žádost o přístup k entitě Book jménem neověřeného uživatele, neměla by tato aplikace obsahovat hlavičku Authorization HTTP.

Ověřená role systému

Role authenticated systému je přiřazena k žádostem spuštěným ověřenými uživateli.

Příklad

Následující konfigurace modulu runtime nástroje Data API Builder ukazuje explicitní konfiguraci role authenticated systému tak, aby zahrnovala přístup pro čtení k entitě Book:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "authenticated",
            "actions": [ "read" ]
        }
    ]
}

Role uživatelů

Role uživatelů jsou nesystémové role, které jsou přiřazené uživatelům v rámci zprostředkovatele identity, který jste nastavili v konfiguraci modulu runtime. Aby tvůrce rozhraní API dat vyhodnotil požadavek v kontextu role uživatele, musí být splněny dva požadavky:

  1. Přístupový token poskytnutý klientskou aplikací musí obsahovat deklarace identity rolí, které uvádějí členství v rolích uživatele.
  2. Klientská aplikace musí obsahovat hlavičku X-MS-API-ROLE HTTP s požadavky a nastavit její hodnotu jako požadovanou roli uživatele.

Příklad vyhodnocení rolí

Následující příklad ukazuje požadavky na entitu Book , která je nakonfigurovaná v konfiguraci modulu runtime tvůrce rozhraní Data API:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ]
        },
        {
            "role": "authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

Ve Static Web Apps je uživatel ve výchozím nastavení členem anonymní role. Pokud je uživatel ověřený, je členem rolí a anonymousauthenticated .

Když klientská aplikace odešle ověřený požadavek do Tvůrce rozhraní DATA API nasazeného pomocí Static Web Apps databázová připojení (Preview), klientská aplikace poskytne přístupový token, který Static Web Apps transformovat na JSON:

{
  "identityProvider": "azuread",
  "userId": "d75b260a64504067bfc5b2905e3b8182",
  "userDetails": "username",
  "userRoles": ["anonymous", "authenticated", "author"]
}

Vzhledem k tomu, že Tvůrce rozhraní API data vyhodnocuje požadavky v kontextu jedné role, vyhodnocuje požadavek ve výchozím nastavení v kontextu systémové role authenticated .

Pokud požadavek klientské aplikace obsahuje také hlavičku X-MS-API-ROLE HTTP s hodnotou author, vyhodnocuje se požadavek v kontextu author role. Příklad požadavku, včetně přístupového tokenu a X-MS-API-ROLE hlavičky HTTP:

curl -k -r GET -H 'Authorization: Bearer ey...' -H 'X-MS-API-ROLE: author' https://localhost:5001/api/Book

Důležité

Žádost klientské aplikace se odmítne, pokud deklarace identity zadaného přístupového roles tokenu neobsahuje roli uvedenou v hlavičce X-MS-API-ROLE .

Oprávnění

Popis oprávnění:

  • Kdo může vytvářet požadavky na entitu na základě členství v rolích?
  • Jaké akce (vytvoření, čtení, aktualizace, odstranění, spuštění) může uživatel provádět?
  • Která pole jsou pro konkrétní akci přístupná?
  • Jaká další omezení platí pro výsledky vrácené požadavkem?

Syntaxe pro definování oprávnění je popsaná v článku o konfiguraci modulu runtime.

Důležité

V rámci konfigurace oprávnění jedné entity může být definováno více rolí. Požadavek se ale vyhodnocuje pouze v kontextu jedné role:

  • Ve výchozím nastavení buď role systému anonymous , nebo authenticated
  • Pokud je součástí, role nastavená v hlavičce X-MS-API-ROLE HTTP.

Zabezpečení ve výchozím nastavení

Ve výchozím nastavení nemá entita nakonfigurovaná žádná oprávnění, což znamená, že k entitě nemá nikdo přístup. Tvůrce rozhraní Data API navíc ignoruje databázové objekty, pokud na tyto objekty v konfiguraci modulu runtime neodkazuje.

Oprávnění musí být explicitně nakonfigurovaná.

Pokud chcete povolit neověřený přístup k entitě anonymous , musí být role explicitně definována v oprávněních entity. Například oprávnění entity jsou explicitně nastavená tak, book aby umožňovala neověřený přístup ke čtení:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "anonymous",
    "actions": [ "read" ]
  }]
}

Pokud chcete zjednodušit definici oprávnění pro entitu, předpokládejme, že pokud pro authenticated roli neexistují žádná konkrétní oprávnění, použijí se oprávnění definovaná pro danou anonymous roli. Dříve zobrazená book konfigurace umožňuje anonymním nebo ověřeným uživatelům provádět operace čtení s entitou book .

Pokud by operace čtení měly být omezeny pouze na ověřené uživatele, měla by být nastavena následující konfigurace oprávnění, což vede k zamítnutí neověřených požadavků:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "authenticated",
    "actions": [ "read" ]
  }]
}

Entita nevyžaduje a není předem nakonfigurovaná s oprávněními pro anonymous role a authenticated . Jednu nebo více uživatelských rolí je možné definovat v rámci konfigurace oprávnění entity a všechny ostatní nedefinované role, systémové nebo uživatelem definované role se automaticky odepře přístup.

V následujícím příkladu je role administrator uživatele jedinou definovanou rolí pro entitu book . Aby uživatel fungoval book s entitou, musí být členem administrator role a zahrnout ji do hlavičky X-MS-API-ROLE HTTP:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "administrator",
    "actions": [ "*" ]
  }]
}

Poznámka

Pokud chcete vynutit řízení přístupu pro dotazy GraphQL při použití Tvůrce rozhraní DATA API se službou Azure Cosmos DB, musíte použít direktivu @authorize v zadaném souboru schématu GraphQL. U mutací a filtrů GraphQL v dotazech GraphQL se však řízení přístupu stále vynucuje konfigurací oprávnění, jak je popsáno výše.

Akce

Akce popisují přístupnost entity v rámci rozsahu role. Akce je možné zadat jednotlivě nebo pomocí zástupné zkratky: * (hvězdička). Zástupce se zástupným znakem představuje všechny akce podporované pro typ entity:

  • Tabulky a zobrazení: create, read, , updatedelete
  • Uložené procedury: execute

Další informace o akcích najdete v dokumentaci ke konfiguračnímu souboru .

Přístup k polím

Můžete nakonfigurovat, která pole mají být pro akci přístupná. Můžete například nastavit, která pole se mají zahrnout a vyloučit z read akce.

Následující příklad brání uživatelům v free-access roli v provádění operací čtení na Column3. Výsledkem odkazů na Column3 v požadavcích GET (koncový bod REST) nebo dotazech (koncový bod GraphQL) je zamítnutý požadavek:

    "book": {
      "source": "dbo.books",
      "permissions": [
        {
          "role": "free-access",
          "actions": [
            "create",
            "update",
            "delete",
            {
              "action": "read",
              "fields": {
                "include": [ "Column1", "Column2" ],
                "exclude": [ "Column3" ]
              }
            }
          ]
        }
      ]
    }

Poznámka

Pokud chcete vynutit řízení přístupu pro dotazy GraphQL při použití Tvůrce rozhraní DATA API se službou Azure Cosmos DB, musíte použít direktivu @authorize v zadaném souboru schématu GraphQL. U mutací a filtrů GraphQL v dotazech GraphQL se však řízení přístupu stále vynucuje konfigurací oprávnění, jak je popsáno tady.

Zabezpečení na úrovni položky

Výrazy zásad databáze umožňují ještě více omezit výsledky. Zásady databáze překládají výrazy na predikáty dotazů spuštěné v databázi. Výrazy zásad databáze se podporují pro následující akce:

  • vytvoření
  • čtení
  • update
  • delete

Upozornění

Akce spuštění používaná s uloženými procedurami nepodporuje zásady databáze.

Poznámka

CosmosDB for NoSQL v současné době nepodporuje zásady databáze.

Další informace o zásadách databáze najdete v dokumentaci ke konfiguračnímu souboru .

Příklad

Zásady databáze, které read omezují akci u role tak, consumer aby vracela jenom záznamy s názvem Ukázkový název.

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.title eq 'Sample Title'"
      }
    }
  ]
}

Související obsah