Implementace zabezpečení na úrovni řádků s kontextem relace v Tvůrci rozhraní Data API

K implementaci zabezpečení na úrovni řádků v Tvůrci rozhraní Data API použijte funkci kontextu relace SQL.

Diagram znázorňující, jak tvůrce rozhraní DATA API může nastavit kontext relace SQL pro povolení zabezpečení na úrovni řádků

Důležité

Kontext relace se zabezpečením na úrovni řádků SQL Serveru se liší od zásad databáze pro Data API Builder. Zásady databáze (například --policy-database "@item.owner eq @claims.user_id") jsou překládány do klauzulí WHERE prostřednictvím nástroje pro tvorbu Data API, zatímco kontext relace přenáší přihlašovací údaje k SQL Serveru, aby SQL-native zabezpečení na úrovni řádků zvládlo filtrování.

Požadavky

Existující sql server a databáze.
Rozhraní příkazového řádku pro tvorbu API dat. Instalace rozhraní příkazového řádku

Poznámka:

Kontext relace je podporován v:

SQL Server 2016 a novější
Azure SQL Database
Azure Synapse Analytics (vyhrazený SQL fond)
Azure Synapse Analytics (bezserverový SQL pool) není podporován.

Vytvoření tabulky a dat SQL

Vytvořte tabulku s fiktivními daty, která se mají použít v tomto ukázkovém scénáři.

Připojte se k databázi SQL pomocí preferovaného klienta nebo nástroje.

Vytvořte tabulku pojmenovanou Revenues se sloupci id, category, revenue a accessible_role.

DROP TABLE IF EXISTS dbo.Revenues;

CREATE TABLE dbo.Revenues(
    id int PRIMARY KEY,  
    category varchar(max) NOT NULL,  
    revenue int,  
    accessible_role varchar(max) NOT NULL  
);
GO

Vložte do Revenues tabulky čtyři ukázkové řádky.

INSERT INTO dbo.Revenues VALUES
    (1, 'Book', 5000, 'Oscar'),  
    (2, 'Comics', 10000, 'Oscar'),  
    (3, 'Journals', 20000, 'Hannah'),  
    (4, 'Series', 40000, 'Hannah')
GO

V tomto příkladu accessible_role sloupec ukládá název role, který má přístup k řádku.

Návod

Běžné případy použití kontextu sezení:

Filtrování na základě rolí (zobrazené tady) pomocí roles
Izolace v multitenantním prostředí pomocí tenant_id
Filtrování specifické pro uživatele pomocí user_id

Otestujte data pomocí jednoduchého SELECT * dotazu.
```
SELECT * FROM dbo.Revenues
```

Vytvořte funkci s názvem RevenuesPredicate. Tato funkce bude filtrovat výsledky na základě aktuálního kontextu relace.

CREATE FUNCTION dbo.RevenuesPredicate(@accessible_role varchar(max))
RETURNS TABLE
WITH SCHEMABINDING
AS RETURN SELECT 1 AS fn_securitypredicate_result
WHERE @accessible_role = CAST(SESSION_CONTEXT(N'roles') AS varchar(max));

Vytvořte zásadu zabezpečení pojmenovanou RevenuesSecurityPolicy pomocí funkce.

CREATE SECURITY POLICY dbo.RevenuesSecurityPolicy
ADD FILTER PREDICATE dbo.RevenuesPredicate(accessible_role)
ON dbo.Revenues;

Poznámka:

Klauzule WITH SCHEMABINDING je vyžadována pro funkce používané v zásadách zabezpečení, aby změny základního schématu neznamenaly zneplatnění predikátu.

(Volitelné) Vytvoření uložené procedury

Tato část ukazuje jednoduchý vzor "hello world" pro použití hodnot kontextu relace přímo v T-SQL.

Vytvořte uloženou proceduru roles , která čte kontextovou hodnotu relace a používá ji k filtrování výsledků.

CREATE OR ALTER PROCEDURE dbo.GetRevenuesForCurrentRole
AS
BEGIN
    SET NOCOUNT ON;

    DECLARE @role varchar(max) = CAST(SESSION_CONTEXT(N'roles') AS varchar(max));

    SELECT id, category, revenue, accessible_role
    FROM dbo.Revenues
    WHERE accessible_role = @role;
END
GO

Spustit nástroj

Spuštěním nástroje Data API Builder (DAB) vygenerujte konfigurační soubor a jednu entitu.

Vytvořte novou konfiguraci při nastavení --set-session-context na hodnotu true.
```
dab init \
    --database-type mssql \
    --connection-string "<sql-connection-string>" \
    --set-session-context true \
    --auth.provider Simulator
```
Pokud je pro SQL Server povolený kontext relace, tvůrce rozhraní DATA API odesílá ověřené deklarace identity uživatelů do SQL voláním sp_set_session_context (například roles). Povolení kontextu relace také zakáže ukládání odpovědí do mezipaměti pro tento zdroj dat.

Výstraha

Pokud set-session-context je tato možnost povolená, ukládání odpovědí do mezipaměti je pro zdroj dat zakázané. V případě scénářů s vysokým provozem zvažte testování výkonu, indexování sloupce predikátu nebo použití databázových zásad Tvůrce rozhraní Data API, když vyhovují vašim potřebám.

Přidejte novou entitu pojmenovanou revenuedbo.Revenues pro tabulku.

dab add revenue \
    --source "dbo.Revenues" \
    --permissions "Authenticated:read"

Spusťte nástroj Tvůrce rozhraní Data API.
```
dab start
```
Dotazujte se na koncový bod bez zadání efektivní role. Všimněte si, že se nevrátí žádná data, protože:
- Platná role má výchozí hodnotu Authenticated.
- Žádné řádky nemají accessible_role = 'Authenticated'.
- Zásady zabezpečení filtruje výsledky, když se role neshoduje.
```
curl http://localhost:5000/api/revenue
```
Dotazování koncového bodu při nastavování efektivní role na Oscar. Všimněte si, že filtrované výsledky obsahují pouze Oscar řádky.
```
curl -H "X-MS-API-ROLE: Oscar" http://localhost:5000/api/revenue
```

Zopakujte použití role Hannah.

curl -H "X-MS-API-ROLE: Hannah" http://localhost:5000/api/revenue

Testování pomocí GraphQL

Kontext relace také funguje s dotazy GraphQL.

query {
    revenues {
        items {
            id
            category
            revenue
            accessible_role
        }
    }
}

Předejte hlavičku role:

curl -X POST http://localhost:5000/graphql \
    -H "Content-Type: application/json" \
    -H "X-MS-API-ROLE: Oscar" \
    -d '{"query": "{ revenues { items { id category revenue accessible_role } } }"}'

Co tvůrce rozhraní Data API odesílá na SQL Server

Pokud je kontext relace povolený, tvůrce rozhraní DATA API nastaví hodnoty kontextu relace na každém požadavku před spuštěním dotazu.

EXEC sp_set_session_context 'roles', 'Oscar', @read_only = 0;
-- Then executes your query
SELECT * FROM dbo.Revenues;

Všechny ověřené deklarace identity uživatelů se odesílají jako páry klíč-hodnota. Mezi běžné nároky patří roles, sub nebo oid, a všechny vlastní nároky od vašeho poskytovatele identity.

Testování v SQL

Otestujte filtr a predikát v SQL přímo, abyste měli jistotu, že funguje.

Znovu se připojte k SQL Serveru pomocí preferovaného klienta nebo nástroje.
Spusťte příkaz sp_set_session_context k ručnímu nastavení deklarace identity kontextu roles relace na statickou hodnotu Oscar.
```
EXEC sp_set_session_context 'roles', 'Oscar';
```
Spusťte typický SELECT * dotaz. Všimněte si, že výsledky se automaticky filtrují pomocí predikátu.
```
SELECT * FROM dbo.Revenues;  
```
(Volitelné) Dotazování tabulky pomocí uložené procedury
```
EXEC dbo.GetRevenuesForCurrentRole;
```

Vyčistěte zdroje

Pokud chcete odebrat ukázkové objekty, spusťte:

DROP SECURITY POLICY IF EXISTS dbo.RevenuesSecurityPolicy;
DROP FUNCTION IF EXISTS dbo.RevenuesPredicate;
DROP PROCEDURE IF EXISTS dbo.GetRevenuesForCurrentRole;
DROP TABLE IF EXISTS dbo.Revenues;

Řešení problémů

Nevrátí se žádné výsledky: Ověřte, že je zásada zabezpečení aktivní (SELECT * FROM sys.security_policies), zkontrolujte hodnotu kontextu relace (SELECT SESSION_CONTEXT(N'roles')) a ověřte, že --set-session-context true je nastavená v konfiguraci tvůrce rozhraní Data API.
Všechny vrácené řádky: Ověřte, že bezpečnostní politika není zakázána (WITH STATE = OFF) a že predikát vrátí 1 pouze pro autorizované řádky.
Problémy s výkonem: Indexujte sloupec predikátu (accessible_role) a zvažte dočasné vypnutí zásady za účelem izolace výkonového dopadu.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-01-28