Mengonfigurasi kebijakan database untuk pemfilteran tingkat baris

Penyusun API Data mendukung kebijakan database yang memfilter hasil kueri berdasarkan ekspresi yang Anda tentukan. Database mengevaluasi kebijakan ini sebagai predikat kueri (WHERE klausa), sehingga pengguna hanya melihat data yang diizinkan untuk mereka akses.

Diagram urutan yang menunjukkan penerapan kebijakan.

Kapan menggunakan kebijakan database

Kebijakan database sangat ideal ketika Anda perlu:

  • Membatasi rekaman berdasarkan nilai bidang (misalnya, status eq 'published')
  • Memfilter data berdasarkan klaim pengguna yang diautentikasi (misalnya, @claims.userId)
  • Menerapkan kontrol akses tingkat baris tanpa memodifikasi prosedur atau tampilan tersimpan
  • Menerapkan aturan pemfilteran yang berbeda per peran

Nota

Azure Cosmos DB for NoSQL saat ini tidak mendukung kebijakan database.

Tindakan yang didukung

Kebijakan database berlaku untuk tindakan ini:

Action Dukungan Cara kerjanya
read ✔️ Ya Menambahkan predikat WHERE ke kueri SELECT
update ✔️ Ya Menambahkan predikat WHERE ke pernyataan UPDATE
delete ✔️ Ya Menambahkan predikat WHERE ke pernyataan DELETE
create ❌ Tidak Pernyataan INSERT tidak mendukung predikat WHERE
execute ❌ Tidak Prosedur tersimpan tidak mendukung predikat kueri

Prasyarat

  • CLI penyusun API Data terinstal (panduan penginstalan)
  • File konfigurasi yang ada dengan setidaknya satu entitas
  • Penyedia autentikasi dikonfigurasi (kebijakan memerlukan permintaan terautentikasi)

Referensi cepat

Konsep Sintaksis Example
Referensi bidang @item.<field> @item.status
Referensi klaim @claims.<type> @claims.userId
Kesetaraan eq @item.ownerId eq @claims.userId
Ketidaksetaraan ne @item.status ne 'draft'
Perbandingan gt,ge,lt,le @item.price lt 100
DAN Logika and @item.active eq true and @item.published eq true
ATAU Logika or @item.role eq 'admin' or @item.role eq 'editor'

Langkah 1: Tentukan ekspresi kebijakan

Kebijakan database menggunakan predikat bergaya OData. Ekspresi harus menghasilkan nilai benar agar baris disertakan dalam hasil.

Rujukan bidang dengan @item

Gunakan @item.<field> untuk mereferensikan bidang entitas. Jika Anda memetakan kolom database ke nama bidang API yang berbeda, gunakan nama yang dipetakan.

@item.status eq 'published'

Referensi klaim dengan @claims

Gunakan @claims.<claimType> untuk menyuntikkan nilai dari token pengguna yang diautentikasi. Pada runtime, penyusun Data API menggantikan nilai klaim ke dalam ekspresi.

@item.ownerId eq @claims.userId

Penting

Jika klaim yang direferensikan hilang dari token, permintaan ditolak dengan respons Terlarang 403.

Ekspresi gabungan

Gabungkan kondisi menggunakan and atau or:

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

Langkah 2: Tambahkan kebijakan ke konfigurasi entitas

Kebijakan ditentukan untuk setiap tindakan dalam izin suatu peran:

Format file konfigurasi

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

Contoh: Pengguna hanya dapat membaca rekaman mereka sendiri

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

Contoh: Beberapa tindakan dengan kebijakan yang sama

Terapkan kebijakan yang sama untuk membaca, memperbarui, dan menghapus:

{
  "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"
              }
            }
          ]
        }
      ]
    }
  }
}

Contoh: Filter nilai statis

Filter menggunakan nilai tetap alih-alih klaim

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

Langkah 3: Mengonfigurasi menggunakan CLI

dab update Gunakan perintah untuk menambahkan kebijakan melalui CLI:

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

Petunjuk / Saran

Saat ekspresi kebijakan berisi karakter khusus, sertakan dalam tanda kutip yang sesuai untuk shell Anda.

Bagaimana kebijakan diproses

Saat permintaan tiba, penyusun API Data:

  1. Mengidentifikasi peran efektif dari header atau peran sistemX-MS-API-ROLE
  2. Penelusuran kebijakan untuk kombinasi entitas, peran, dan tindakan
  3. Mengganti klaim dengan mengganti @claims.<type> token dengan nilai aktual dari token
  4. Mengurai ekspresi sebagai filter $ OData
  5. Menghasilkan predikat kueri yang ditambahkan ke kueri database

Misalnya, jika kebijakan adalah @item.ownerId eq @claims.userId dan token berisi userId: "user123", SQL yang dihasilkan meliputi:

WHERE [ownerId] = 'user123'

Penggantian klaim

Penyusun API Data mengekstrak klaim dari JSON Web Token (JWT) pengguna yang diautentikasi atau prinsip identitas. Klaim umum meliputi:

Tuntutan Deskripsi Contoh nilai
sub Pengidentifikasi subjek (ID pengguna) 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
userId Pengidentifikasi pengguna kustom user123
email Alamat email pengguna user@example.com
name Nama tampilan pengguna Jane Doe
roles Keanggotaan peranan (array) ["reader", "editor"]

Peringatan

Jika klaim yang dirujuk dalam kebijakan tidak ada dalam token, pembuat API Data menolak permintaan dengan respons Terlarang 403. Pastikan penyedia identitas (IdP) Anda menyertakan semua klaim yang diperlukan.

Gabungkan dengan pembatasan lapangan

Kebijakan berfungsi bersama kontrol akses tingkat lapangan. Anda dapat membatasi baris mana dan kolom mana yang dapat diakses peran:

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

Keterbatasan

Pembatasan Rincian
Tidak ada create tindakan Pernyataan INSERT tidak mendukung predikat WHERE
Tidak ada execute tindakan Prosedur tersimpan tidak menerima predikat kueri
Tidak ada Azure Cosmos DB untuk NoSQL Api NoSQL saat ini tidak mendukung kebijakan database
Tidak ada kebijakan otorisasi bernama DAB tidak mendukung kebijakan bernama ASP.NET/HotChocolate-style

Troubleshooting

Klaim tidak ditemukan (403 Terlarang)

Jika permintaan gagal dengan 403 Forbidden, verifikasi:

  • Klaim ada dalam token akses
  • Nama klaim sama persis (sensitif terhadap huruf besar/kecil)
  • Penyedia identitas dikonfigurasi untuk menyertakan klaim

Kebijakan tidak diterapkan

Jika hasil tidak difilter:

  • Verifikasi bahwa nama peran sesuai dengan nilai header X-MS-API-ROLE
  • Konfirmasikan bahwa tindakan (baca, perbarui, hapus) telah ditentukan dalam kebijakan
  • Periksa apakah autentikasi dikonfigurasi dan permintaan diautentikasi

Kesalahan sintaksis

Jika mesin melaporkan kesalahan penguraian kebijakan:

  • Verifikasi ekspresi menggunakan sintaks OData (eq, , ne, andor)
  • Periksa apakah nama bidang cocok dengan nama API yang dipetakan (bukan nama kolom database)
  • Pastikan nilai string diapit dalam tanda kutip tunggal

Konten terkait

  • Last updated on