Implementierung von Zeilenebensicherheit mit Sitzungskontext im Data-API-Builder

Verwenden Sie das Sitzungskontextfeature von SQL, um die Sicherheit auf Zeilenebene im Daten-API-Generator zu implementieren.

Diagramm, das zeigt, wie der Daten-API-Generator SQL-Sitzungskontext festlegen kann, um die Sicherheit auf Zeilenebene zu aktivieren.

Von Bedeutung

Der Sitzungskontext mit SQL Server-Zeilenebensicherheit unterscheidet sich von den Datenbankrichtlinien des Data API Builders. Datenbankrichtlinien (z. B. --policy-database "@item.owner eq @claims.user_id") werden vom Data API Builder in WHERE-Klauseln übersetzt, während der Sitzungskontext Ansprüche an SQL Server weiterleitet, sodass die SQL-native Zeilenebensicherheit die Filterung übernimmt.

Voraussetzungen

Vorhandener SQL-Server und -Datenbank.
CLI des Daten-API-Erstellers. Installieren der CLI

Hinweis

Der Sitzungskontext wird unterstützt in:

SQL Server 2016 und höher
Azure SQL-Datenbank
Azure Synapse Analytics (dedizierter SQL-Pool)
Azure Synapse Analytics (Serverless SQL-Pool) wird nicht unterstützt.

Erstellen einer SQL-Tabelle und -Daten

Erstellen Sie eine Tabelle mit fiktiven Daten, die in diesem Beispielszenario verwendet werden sollen.

Stellen Sie mithilfe Ihres bevorzugten Clients oder Tools eine Verbindung mit der SQL-Datenbank her.

Erstellen Sie eine Tabelle mit dem Namen Revenues und den Spalten id, category, revenue und 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

Fügen Sie vier Beispielzeilen in die Revenues Tabelle ein.

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

In diesem Beispiel speichert die accessible_role Spalte den Rollennamen, der auf die Zeile zugreifen kann.

Tipp

Häufige Anwendungsfälle für den Sitzungskontext:

Rollenbasierte Filterung (hier gezeigt) mit roles
Mehrinstanzenisolation mit tenant_id
Benutzerspezifische Filterung mithilfe von user_id

Testen Sie Ihre Daten mit einer einfachen SELECT * Abfrage.
```
SELECT * FROM dbo.Revenues
```

Erstellen Sie eine Funktion mit dem Namen RevenuesPredicate. Diese Funktion filtert Ergebnisse basierend auf dem aktuellen Sitzungskontext.

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));

Erstellen Sie eine Sicherheitsrichtlinie mit dem Namen RevenuesSecurityPolicy unter Verwendung der Funktion.

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

Hinweis

Die WITH SCHEMABINDING Klausel ist für Funktionen erforderlich, die in Sicherheitsrichtlinien verwendet werden, sodass zugrunde liegende Schemaänderungen das Prädikat nicht ungültig machen.

(Optional) Erstellen einer gespeicherten Prozedur

Dieser Abschnitt zeigt ein einfaches "Hello World"-Muster für die direkte Verwendung von Sitzungskontextwerten in T-SQL.

Erstellen Sie eine gespeicherte Prozedur, die den roles Sitzungskontextwert liest und zum Filtern von Ergebnissen verwendet.

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

Ausführen des Tools

Führen Sie das DaB-Tool (Data API Builder) aus, um eine Konfigurationsdatei und eine einzelne Entität zu generieren.

Erstellen Sie eine neue Konfiguration und setzen Sie --set-session-context auf "true".
```
dab init \
    --database-type mssql \
    --connection-string "<sql-connection-string>" \
    --set-session-context true \
    --auth.provider Simulator
```
Wenn der Sitzungskontext für SQL Server aktiviert ist, sendet der Daten-API-Generator authentifizierte Benutzeransprüche, indem sp_set_session_context aufgerufen wird (z. B. roles). Durch aktivieren des Sitzungskontexts wird auch das Zwischenspeichern von Antworten für diese Datenquelle deaktiviert.

Warnung

Wenn set-session-context diese Option aktiviert ist, ist das Zwischenspeichern von Antworten für die Datenquelle deaktiviert. Bei Szenarien mit hohem Datenverkehr sollten Sie die Leistung testen, die Prädikatspalte indizieren oder Daten-API-Generator-Datenbankrichtlinien verwenden, wenn sie Ihren Anforderungen entsprechen.

Fügen Sie eine neue Entität mit dem Namen revenue für die Tabelle dbo.Revenues hinzu.

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

Starten Sie das Daten-API-Generator-Tool.
```
dab start
```
Fragen Sie den Endpunkt ab, ohne eine effektive Rolle anzugeben. Beachten Sie, dass keine Daten zurückgegeben werden, weil:
- Die effektive Rolle ist standardmäßig auf Authenticated.
- Es sind keine Zeilen vorhanden accessible_role = 'Authenticated'.
- Die Sicherheitsrichtlinie filtert Ergebnisse, wenn die Rolle nicht übereinstimmt.
```
curl http://localhost:5000/api/revenue
```
Fragen Sie den Endpunkt ab, während Sie die effektive Rolle auf Oscar festlegen. Beachten Sie, dass die gefilterten Ergebnisse nur die Oscar Zeilen enthalten.
```
curl -H "X-MS-API-ROLE: Oscar" http://localhost:5000/api/revenue
```

Wiederholen Sie die Nutzung der Hannah-Rolle.

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

Testen mit GraphQL

Der Sitzungskontext funktioniert auch mit GraphQL-Abfragen.

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

Übergeben Sie den Rollenheader:

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 } } }"}'

Was der Daten-API-Generator an SQL Server sendet

Wenn der Sitzungskontext aktiviert ist, legt der Daten-API-Generator Sitzungskontextwerte für jede Anforderung fest, bevor Die Abfrage ausgeführt wird.

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

Alle authentifizierten Benutzeransprüche werden als Schlüsselwertpaare gesendet. Allgemeine Ansprüche umfassen roles, sub oder oid, sowie alle benutzerdefinierten Ansprüche von Ihrem Identitätsanbieter.

Testen in SQL

Testen Sie den Filter und das Prädikat in SQL direkt, um sicherzustellen, dass er funktioniert.

Stellen Sie erneut eine Verbindung mit dem SQL-Server her, indem Sie ihren bevorzugten Client oder Ihr bevorzugtes Tool verwenden.
Führen Sie sp_set_session_context aus, um den Anspruch des Sitzungskontexts roles manuell auf den statischen Wert Oscar festzulegen.
```
EXEC sp_set_session_context 'roles', 'Oscar';
```
Führen Sie eine typische SELECT * Abfrage aus. Beachten Sie, dass die Ergebnisse automatisch mithilfe des Prädikats gefiltert werden.
```
SELECT * FROM dbo.Revenues;  
```
(Optional) Fragen Sie die Tabelle mithilfe der gespeicherten Prozedur ab.
```
EXEC dbo.GetRevenuesForCurrentRole;
```

Bereinigen von Ressourcen

Wenn Sie die Beispielobjekte entfernen möchten, führen Sie Folgendes aus:

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;

Problembehandlung

Keine Ergebnisse zurückgegeben: Überprüfen Sie, ob die Sicherheitsrichtlinie aktiv ist (SELECT * FROM sys.security_policies), überprüfen Sie den Sitzungskontextwert (SELECT SESSION_CONTEXT(N'roles')), und bestätigen Sie, dass --set-session-context true die Daten-API-Generator-Konfiguration festgelegt ist.
Alle zurückgegebenen Zeilen: Bestätigen Sie, dass die Sicherheitsrichtlinie nicht deaktiviert ist (WITH STATE = OFF) und dass das Prädikat nur für autorisierte Zeilen zurückgegeben wird 1 .
Leistungsprobleme: Indizieren Sie die Prädikatspalte (accessible_role), und deaktivieren Sie die Richtlinie vorübergehend, um die Auswirkungen auf die Leistung zu isolieren.

Feedback

War diese Seite hilfreich?

Last updated on 2026-01-28