Konfigurace zásad databáze pro filtrování na úrovni řádků

Tvůrce rozhraní Data API podporuje zásady databáze , které filtrují výsledky dotazů na základě vámi definovaných výrazů. Databáze tyto zásady vyhodnocuje jako predikáty dotazů (WHERE klauzule), takže uživatelé vidí jenom data, ke kterým mají povolený přístup.

Sekvenční diagram znázorňující použití zásad

Kdy použít zásady databáze

Zásady databáze jsou ideální, když potřebujete:

  • Omezení záznamů na základě hodnoty pole (například status eq 'published')
  • Filtrování dat na základě deklarací identity ověřeného uživatele (například @claims.userId)
  • Implementace řízení přístupu na úrovni řádků bez úpravy uložených procedur nebo zobrazení
  • Použití různých pravidel filtrování na roli

Poznámka:

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

Podporované akce

Zásady databáze se vztahují na tyto akce:

Action Podporováno Jak to funguje
read ✔️ Ano Přidá predikát WHERE do dotazů SELECT.
update ✔️ Ano Přidá predikát WHERE do příkazů UPDATE.
delete ✔️ Ano Přidá predikát WHERE do příkazů DELETE.
create ❌ Ne Příkazy INSERT nepodporují predikáty WHERE
execute ❌ Ne Uložené procedury nepodporují predikáty dotazů

Předpoklady

  • Nainstalovaný Data API builder CLI (průvodce instalací)
  • Existující konfigurační soubor s alespoň jednou entitou
  • Je nakonfigurovaný poskytovatel ověřování (zásady vyžadují autentizované požadavky).

Stručná referenční dokumentace

Koncepce Syntaxe Příklad
Referenční pole @item.<field> @item.status
Referenční číslo nároku @claims.<type> @claims.userId
Rovnost eq @item.ownerId eq @claims.userId
Nerovnost ne @item.status ne 'draft'
Porovnání gt, ge, , ltle @item.price lt 100
Logická operace AND and @item.active eq true and @item.published eq true
Logické NEBO or @item.role eq 'admin' or @item.role eq 'editor'

Krok 1: Definování výrazu zásady

Zásady databáze používají predikáty ve stylu OData. Výraz musí být vyhodnocen jako true, aby byl řádek zahrnut do výsledků.

Odkazy na pole s využitím @item

Použijte @item.<field> k odkazu na pole entit. Pokud jste namapovali sloupec databáze na jiný název pole rozhraní API, použijte mapovaný název.

@item.status eq 'published'

Odkazy na deklarace identity s využitím @claims

Slouží @claims.<claimType> k vložení hodnot z tokenu ověřeného uživatele. Při běhu aplikace nahrazuje tvůrce rozhraní Data API hodnotu pohledávky ve výrazu.

@item.ownerId eq @claims.userId

Důležité

Pokud v tokenu chybí odkazovaný nárok, žádost se odmítne s odpovědí 403 Forbidden.

Složené výrazy

Kombinujte podmínky pomocí and nebo or:

@item.ownerId eq @claims.userId and @item.status ne 'deleted'

Krok 2: Přidání zásady do konfigurace entity

Zásady se definují podle akce v rámci oprávnění role:

Formát konfiguračního souboru

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": "<role-name>",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "<predicate-expression>"
              }
            }
          ]
        }
      ]
    }
  }
}

Příklad: Uživatel může číst pouze své vlastní záznamy

{
  "entities": {
    "Order": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "customer",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@item.customerId eq @claims.userId"
              }
            }
          ]
        }
      ]
    }
  }
}

Příklad: Více akcí se stejnou zásadou

Použijte stejnou zásadu pro čtení, aktualizaci a odstranění:

{
  "entities": {
    "Document": {
      "source": "dbo.Documents",
      "permissions": [
        {
          "role": "author",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@item.authorId eq @claims.sub"
              }
            },
            {
              "action": "update",
              "policy": {
                "database": "@item.authorId eq @claims.sub"
              }
            },
            {
              "action": "delete",
              "policy": {
                "database": "@item.authorId eq @claims.sub"
              }
            }
          ]
        }
      ]
    }
  }
}

Příklad: Filtr statických hodnot

Filtrování podle pevné hodnoty místo deklarace identity:

{
  "entities": {
    "Article": {
      "source": "dbo.Articles",
      "permissions": [
        {
          "role": "Anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@item.status eq 'published'"
              }
            }
          ]
        }
      ]
    }
  }
}

Krok 3: Konfigurace pomocí rozhraní příkazového řádku

dab update Pomocí příkazu přidejte zásady prostřednictvím rozhraní příkazového řádku:

dab update Order \
  --permissions "customer:read" \
  --policy-database "@item.customerId eq @claims.userId"

Návod

Pokud výraz zásady obsahuje speciální znaky, uzavřete ho do uvozovek vhodných pro vaše prostředí.

Jak se zásady zpracovávají

Jakmile přijde požadavek, tvůrce rozhraní Data API:

  1. Identifikuje efektivní roli z hlavičky X-MS-API-ROLE nebo systémové role.
  2. Vyhledá zásadu pro entitu, roli a kombinaci akcí.
  3. Nahradí nároky nahrazením @claims.<type> tokenů skutečnými hodnotami z těchto tokenů.
  4. Parsuje výraz jako $filter OData.
  5. Generuje predikáty dotazu , které jsou připojeny k databázovému dotazu.

Pokud je @item.ownerId eq @claims.userId zásada a token obsahuje userId: "user123", vygenerovaný SQL například obsahuje:

WHERE [ownerId] = 'user123'

Nahrazení tvrzení

Tvůrce Data API extrahuje nároky z ověřeného uživatelského JSON Web Tokenu (JWT) nebo z identitního principálu. Mezi běžné nároky patří:

Požadavek Description Příklad hodnoty
sub Identifikátor subjektu (ID uživatele) ffffffff-eeee-dddd-cccc-bbbbbbbbbbb0
userId Vlastní identifikátor uživatele user123
email E-mailová adresa uživatele user@example.com
name Zobrazované jméno uživatele Jane Doe
roles Členství v rolích (pole) ["reader", "editor"]

Výstraha

Pokud nárok odkazovaný v zásadách v tokenu neexistuje, tvůrce rozhraní Data API žádost odmítne s odpovědí 403 Zakázaný. Ujistěte se, že váš zprostředkovatel identity obsahuje všechny požadované deklarace.

Kombinujte s omezeními polí

Zásady fungují společně s řízením přístupu na úrovni polí. Můžete omezit, ke kterým řádkům a ke kterým sloupcům má role přístup:

{
  "role": "auditor",
  "actions": [
    {
      "action": "read",
      "fields": {
        "include": ["id", "amount", "status"],
        "exclude": ["internalNotes"]
      },
      "policy": {
        "database": "@item.status eq 'completed'"
      }
    }
  ]
}

Omezení

Omezení Podrobnosti
Žádná create akce Příkazy INSERT nepodporují predikáty WHERE
Žádná execute akce Uložené procedury nepřijímají predikáty dotazů
Žádný Azure Cosmos DB pro NoSQL Rozhraní API NoSQL v současné době nepodporuje zásady databáze.
Žádné pojmenované zásady autorizace DAB nepodporuje v ASP.NET/HotChocolate stylu pojmenované zásady.

Troubleshooting

Požadavek nebyl nalezen (403 Zakázáno)

Pokud požadavek selže s kódem chyby 403 Zakázáno, ověřte:

  • Nárok se nachází v přístupovém tokenu.
  • Název požadavku přesně odpovídá (rozlišují se malá a velká písmena).
  • Poskytovatel identity je nastaven tak, aby zahrnoval nárok.

Zásady se nepoužijí.

Pokud se výsledky nefiltrují:

  • Ověřte, že název role odpovídá hodnotě X-MS-API-ROLE záhlaví.
  • Potvrďte, že akce (čtení, aktualizace, odstranění) má definovanou zásadu.
  • Zkontrolujte, jestli je nakonfigurované ověřování a že se požadavek ověřuje.

Syntaktické chyby

Pokud engine hlásí chybu při analýze politiky:

  • Ověřte, že výraz používá syntaxi OData (eq, ne, and, or)
  • Zkontrolujte, jestli názvy polí odpovídají názvům mapovaných rozhraní API (ne názvům sloupců databáze).
  • Ujistěte se, že řetězcové hodnoty jsou uzavřené v jednoduchých uvozovkách.

Související obsah

  • Last updated on