Sdílet prostřednictvím

Autorizace a role v Tvůrci rozhraní Data API

Tvůrce rozhraní Data API používá pracovní postup autorizace na základě role. Každému příchozímu požadavku, ověřenému nebo ne, je přiřazena role. Role můžou být systémové role nebo role uživatelů. Přiřazená role se pak kontroluje proti definovaným oprávněním zadaným v konfiguraci, abyste pochopili, jaké akce, pole a zásady jsou pro danou roli pro požadovanou entitu k dispozici.

Obrázek toho, jak Tvůrce rozhraní Data API vybere roli a vyhodnotí oprávnění pro požadavek

Určení role uživatele

Žádná role nemá výchozí oprávnění. Jakmile tvůrce rozhraní Data API určí roli, musí entita permissions pro danou roli definovat actions , aby žádost byla úspěšná.

Následující matice vyhodnocení role se vztahuje na poskytovatele JWT bearer (například EntraID/AzureAD a Custom), kde klient odesílá Authorization: Bearer <token>.

Poskytnutý nosný token X-MS-API-ROLE Poskytnuto Požadovaná role je uvedena v nároku tokenu roles Efektivní role nebo výsledek
Ne Ne N/A Anonymous
Ano (platné) Ne N/A Authenticated
Ano (platné) Ano Ne Odmítnuto (403 Zakázáno)
Ano (platné) Ano Ano X-MS-API-ROLE hodnota
Ano (neplatné) Jakýkoliv N/A Odmítnuto (401 Neautorizováno)

Chcete-li použít jinou roli než Anonymous nebo Authenticated, je požadována hlavička X-MS-API-ROLE .

Poznámka:

Požadavek může být spojený s mnoha rolemi v ověřeném subjektu. Tvůrce rozhraní Data API ale vyhodnocuje oprávnění a zásady v kontextu přesně jedné efektivní role. Po zadání X-MS-API-ROLE záhlaví vybere, která role se použije.

Poznámky zprostředkovatele:

  • Zprostředkovatelé EasyAuth (například AppService): Ověřování je možné vytvořit pomocí hlaviček injektovaných platformou (například X-MS-CLIENT-PRINCIPAL) místo nosných tokenů.
  • Simulator: Požadavky se považují za ověřené pro vývoj/testování bez ověření skutečného tokenu.

Systémové role

Systémové role jsou předdefinované role rozpoznané tvůrcem rozhraní DATA API. Systémová role se automaticky přiřadí žadateli bez ohledu na členství v roli žadatele označeného v přístupových tokenech. Existují dvě systémové role: Anonymous a Authenticated.

Role anonymního systému

Role Anonymous systému je přiřazena k žádostem spuštěným neověřenými uživateli. Pokud se vyžaduje neověřený přístup, musí definované entity modulu runtime obsahovat oprávnění pro Anonymous roli.

Příklad

Následující konfigurace modulu runtime pro nástroj pro tvorbu rozhraní Data API ukazuje explicitní nastavení systémové role Anonymous, aby zahrnovala přístup k čtení pro entitu Kniha:

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

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

Ověřená systémová role

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 pro nástroj pro tvorbu rozhraní Data API ukazuje explicitní nastavení systémové role Authenticated, aby zahrnovala přístup k čtení pro entitu Kniha:

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

Role uživatelů

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

  1. Autentizovaný subjekt musí obsahovat nároky, které uvádějí role uživatele (například nárok JWT roles).
  2. Klientská aplikace musí obsahovat hlavičku X-MS-API-ROLE HTTP s požadavky a nastavit hodnotu hlavičky jako požadovanou roli uživatele.

Příklad vyhodnocení role

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

"Book": {
    "source": "books",
    "permissions": [
        {
      "role": "Anonymous",
            "actions": [ "read" ]
        },
        {
      "role": "Authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

Tvůrce rozhraní Data API vyhodnocuje požadavky v kontextu jedné efektivní role. Pokud se požadavek ověří a nezadá se žádná X-MS-API-ROLE hlavička, tvůrce rozhraní Data API ve výchozím nastavení vyhodnocuje požadavek v kontextu Authenticated systémové role.

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

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

Důležité

Požadavek klientské aplikace se odmítne, když deklarace identity zadaného roles přístupového tokenu neobsahuje roli uvedenou v X-MS-API-ROLE hlavičce.

Povolení

Oprávnění popisují:

  • Kdo může na základě členství v roli podávat žádosti ohledně entity?
  • 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í existují u výsledků vrácených požadavkem?

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

Důležité

V konfiguraci 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í je buď role systému Anonymous, nebo Authenticated
  • Pokud je zahrnuta, nastaví se role v hlavičce HTTP X-MS-API-ROLE.

Ve výchozím nastavení zabezpečeno

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 nejsou odkazovány v konfiguraci modulu runtime.

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 jsou oprávnění entity explicitně nastavena tak, aby umožňovala neověřený přístup pro čtení: book

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

Pokud chcete, aby k přístupu měli přístup jak neověření, tak ověření uživatelé, explicitně udělte oprávnění jak systémovým rolím (Anonymous tak Authenticated).

Pokud by operace čtení měly být omezené jenom na ověřené uživatele, měla by se nastavit 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í s oprávněními předem nakonfigurovaná pro role Anonymous a Authenticated. Jedna 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ém nebo uživatelem definované, přístup se automaticky odepře.

V následujícím příkladu je role administrator uživatele jedinou definovanou rolí pro entitu book . Aby uživatel mohl pracovat s entitou administrator, musí být členem role X-MS-API-ROLE a tuto roli zahrnout do book hlavičky 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. Při použití mutací a filtrů v dotazech GraphQL se však stále vynucuje řízení přístupu, jak je popsáno výše.

Akce

Akce popisují přístupnost entity v rámci oboru role. Akce lze zadat jednotlivě nebo pomocí zástupné zkratky: * (hvězdička). Zástupný znak představuje všechny akce podporované pro typ entity.

  • Tabulky a zobrazení: create, read, update, delete
  • 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 pole, která mají být zahrnuta a vyloučena z read akce.

Následující příklad zabraňuje uživatelům v roli free-access provádět operace čtení na Column3. Odkazy na Column3 požadavky GET (koncový bod REST) nebo dotazy (koncový bod GraphQL) mají za následek odmí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. V případě grafqlových mutací a filtrů v dotazech GraphQL ale konfigurace oprávnění stále vynucuje řízení přístupu, jak je popsáno zde.

Zabezpečení na úrovni položek

Zásady databáze umožňují filtrovat výsledky na úrovni řádků. Zásady se překládají na predikáty dotazů, které databáze vyhodnocuje a zajišťují, že uživatelé přistupují pouze k autorizovaným záznamům.

Podporované akce Není podporováno
read, updatedelete create, execute

Poznámka:

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

Podrobné kroky konfigurace, referenční informace o syntaxi a příklady najdete v tématu Konfigurace zásad databáze.

Stručný příklad
{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.ownerId eq @claims.userId"
      }
    }
  ]
}

Související obsah

  • Last updated on