Přehled autorizace

Autorizace určuje, co můžou ověření uživatelé dělat v aplikaci Tvůrce rozhraní Data API. Ověřování sice ověřuje , kdo je uživatel, ale autorizace určuje, k čemu má přístup a co může upravovat.

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.

Klíčové koncepty autorizace

Oprávnění entity

Řízení operací CRUD (Create, Read, Update, Delete) na úrovni entity. Každá role může být udělena nebo odepřena možnost provádět konkrétní akce na konkrétních entitách.

Řízení přístupu založené na rolích

Přiřaďte uživatele k rolím a udělte oprávnění na základě členství v rolích. Role zjednodušují správu velkých skupin uživatelů s podobnými vzory přístupu.

Zabezpečení na úrovni řádků (RLS)

Filtrování dat na základě identity uživatele nebo kontextu relace Uživatelé uvidí jenom řádky, ke kterým mají oprávnění pro přístup, vynucované na úrovni databáze.

Zásady rozhraní API

Použití predikátů A filtrů OData na odpovědi rozhraní API Zásady automaticky omezují výsledky dotazů na základě deklarací identity a identity uživatelů.

Autorizace založená na deklaracích/assertionech

K určení přístupu použijte deklarace identity z ověřovacích tokenů (například skupiny, role, vlastní atributy). Nároky poskytují flexibilní a granulární rozhodnutí o oprávněních.

Jak to funguje

  1. Uživatel se ověřuje pomocí jedné z podporovaných metod ověřování.
  2. Systém extrahuje deklarace identity z ověřovacího tokenu (role, skupiny, organizace atd.).
  3. Autorizační pravidla se vyhodnocují na základě deklarací identity uživatele a požadovaného prostředku.
  4. Přístup je udělen nebo odepřen na základě oprávnění entit, zásad a pravidel zabezpečení na úrovni řádků.

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 hodnocení rolí se vztahuje na zprostředkovatele nositele JSON Web Token (JWT) (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:

  • Poskytovatelé EasyAuth (například AppService): hlavičky vložené platformou (například X-MS-CLIENT-PRINCIPAL) zajišťují ověřování místo nosného tokenu.
  • Simulator: Požadavky jsou považovány za authenticated pro vývoj/testování, a to bez ověření platné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.

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.

Zásady databáze (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 Nepodporováno
read, update, delete 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"
      }
    }
  ]
}

Dědičnost rolí

DAB 2.0 zavádí dědičnost rolí, takže nemusíte opakovat stejný blok oprávnění napříč jednotlivými rolemi. Řetězec dědičnosti je:

named-role → authenticated → anonymous
  • Pokud není authenticated explicitně nakonfigurováno pro entitu, dědí z anonymous.
  • Pokud pojmenovaná role není nakonfigurovaná, dědí z authenticated, nebo z anonymous, pokud je také authenticated nepřítomen.

Oprávnění můžete definovat jednou najednou anonymous a každá širší role získá stejný přístup automaticky bez nutnosti duplikace.

Poznámka:

Funkce tvůrce rozhraní Data API 2.0 popsané v této části jsou aktuálně ve verzi Preview a můžou se změnit před obecnou dostupností. Další informace najdete v tématu Co je nového ve verzi 2.0.

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

S touto konfigurací mohou anonymous, authenticated a všechny pojmenované role, které nejsou konfigurované, číst Book.

Použijte dab configure --show-effective-permissions k zobrazení vyřešených oprávnění pro každou entitu po aplikaci dědičnosti.

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 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.

Model vrstveného zabezpečení

Tvůrce rozhraní Data API používá více vrstev autorizace:

  • Úroveň entity: Které entity a operace jsou přístupné
  • Úroveň zásad: Jaká data se vrátí (filtrování na základě deklarací identity)
  • Úroveň řádků: Databáze používá filtrování řádků pomocí RLS
  • Úroveň rozhraní API: Hlavičky HTTP a ověřování požadavků

Další kroky

  • Last updated on