Satır düzeyi filtreleme için veritabanı ilkelerini yapılandırma

Veri API oluşturucusu, tanımladığınız ifadelere göre sorgu sonuçlarını filtreleyen veritabanı ilkelerini destekler. Veritabanı bu ilkeleri sorgu koşulları (WHERE yan tümceleri) olarak değerlendirir, böylece kullanıcılar yalnızca erişmelerine izin verilen verileri görür.

İlkelerin uygulanmasını gösteren bir sıralama diyagramı.

Veritabanı ilkeleri ne zaman kullanılır?

Veritabanı ilkeleri, şunları yapmanız gerektiğinde idealdir:

  • Kayıtları alan değerine göre kısıtlama (örneğin, status eq 'published')
  • Kimliği doğrulanmış kullanıcının taleplerine göre verileri filtreleme (örneğin, @claims.userId)
  • Saklı yordamları veya görünümleri değiştirmeden satır düzeyi erişim denetimi uygulama
  • Rol başına farklı filtreleme kuralları uygulama

Uyarı

NoSQL için Azure Cosmos DB şu anda veritabanı ilkelerini desteklememektedir.

Desteklenen eylemler

Veritabanı ilkeleri şu eylemler için geçerlidir:

Eylem Destekleniyor Nasıl çalışır?
read ✔️ Evet SELECT sorgularına WHERE koşulu ekler
update ✔️ Evet WHERE koşulunu UPDATE deyimlerine ekler
delete ✔️ Evet DELETE deyimlerine WHERE koşulu ekler
create ❌ Hayır INSERT deyimleri WHERE şartlarını desteklemez
execute ❌ Hayır Saklı yordamlar sorgu koşullarını desteklemez

Önkoşullar

  • Data API builder CLI yüklü (yükleme kılavuzu)
  • En az bir varlığa sahip mevcut bir yapılandırma dosyası
  • Bir kimlik doğrulama sağlayıcısı yapılandırıldı (ilkeler kimliği doğrulanmış istekler gerektirir)

Hızlı referans

Konsept Sözdizimi Example
Alan referansı @item.<field> @item.status
Talep referansı @claims.<type> @claims.userId
Eşitlik eq @item.ownerId eq @claims.userId
Eşitsizlik ne @item.status ne 'draft'
Karşılaştırma gt, ge, lt, le @item.price lt 100
Mantıksal VE and @item.active eq true and @item.published eq true
Mantıksal VEYA or @item.role eq 'admin' or @item.role eq 'editor'

1. Adım: İlke ifadesini tanımlama

Veritabanı ilkeleri OData stili koşullarını kullanır. Bir satırın sonuçlara dahil edilmesi için ifadenin true olarak hesaplanması gerekir.

ile alan başvuruları @item

@item.<field> kullanarak varlık alanlarına başvurun. Veritabanı sütununu farklı bir API alanı adıyla eşlediyseniz, eşlenen adı kullanın.

@item.status eq 'published'

Referansları talep et @claims

@claims.<claimType> kullanarak kimliği doğrulanmış kullanıcının belirtecinden değerler yerleştirin. Veri API oluşturucu, çalışma zamanında talep değerini ifadeye yerine koymaktadır.

@item.ownerId eq @claims.userId

Önemli

Belirteçte referans verilen bir iddia eksikse, istek 403 Forbidden yanıtıyla reddedilir.

Bileşik ifadeler

and veya or kullanarak koşulları birleştirin.

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

2. Adım: İlkeyi varlık yapılandırmasına ekleme

İlkeler, bir rolün izinleri içinde eylem başına tanımlanır:

Yapılandırma dosyası biçimi

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

Örnek: Kullanıcı yalnızca kendi kayıtlarını okuyabilir

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

Örnek: Aynı ilkeye sahip birden çok eylem

Okumak, güncelleştirmek ve silmek için aynı ilkeyi uygulayı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"
              }
            }
          ]
        }
      ]
    }
  }
}

Örnek: Statik değer filtresi

Talep yerine sabit bir değere göre filtreleyin:

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

3. Adım: CLI kullanarak yapılandırma

dab update CLI aracılığıyla ilke eklemek için komutunu kullanın:

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

Tavsiye

İlke ifadesi özel karakterler içerdiğinde, ilke ifadesini kabuğunuz için uygun tırnak içine alın.

İlkeler nasıl işlenir?

bir istek geldiğinde Veri API oluşturucu:

  1. Etkin rolü üst bilgiden veya sistem rolünden X-MS-API-ROLE tanımlar
  2. Varlık, rol ve eylem kombinasyonu için ilkeleri sorgular
  3. Belirteç iddialarını, @claims.<type> belirteçten gelen gerçek değerlerle yerine koyarak değiştirir.
  4. İfadeyi OData $filter olarak ayrıştırıyor
  5. Veritabanı sorgusuna eklenen sorgu koşullarını oluşturur

Örneğin, ilke ise @item.ownerId eq @claims.userId ve belirteç içeriyorsa userId: "user123", oluşturulan SQL şunları içerir:

WHERE [ownerId] = 'user123'

Talep değiştirme

Veri API oluşturucusu, kimliği doğrulanmış kullanıcının JSON Web Belirtecinden (JWT) veya kimlik sorumlusundan talepleri ayıklar. Yaygın talepler şunlardır:

İddia Açıklama Örnek değer
sub Konu tanımlayıcısı (kullanıcı kimliği) ffffffff-eeee-dddd-cccc-bbbbbbbbbbb0
userId Özel kullanıcı tanımlayıcısı user123
email Kullanıcının e-posta adresi user@example.com
name Kullanıcının görünen adı Jane Doe
roles Rol üyelikleri (liste) ["reader", "editor"]

Uyarı

Politikada atıfta bulunulan bir talep belirteçte yoksa, Veri API oluşturucu isteği 403 Yasak yanıtı ile reddeder. Kimlik sağlayıcınızda tüm gerekli taleplerin bulunduğuna emin olun.

Alan kısıtlamalarıyla birleştir

Politikalar, alan düzeyinde erişim denetimiyle birlikte çalışır. Rolün erişebileceği satırları ve sütunları kısıtlayabilirsiniz:

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

Sınırlamalar

Sınırlama Ayrıntılar
Eylem yok create INSERT deyimleri WHERE şartlarını desteklemez
Eylem yok execute Saklı yordamlar sorgu koşullarını kabul etmemektedir
NoSQL için Azure Cosmos DB yok NoSQL API şu anda veritabanı ilkelerini desteklemiyor
Adlandırılmış yetkilendirme ilkesi yok DAB, ASP.NET/HotChocolate tarzı adlandırılmış ilkeleri desteklemez.

Sorun giderme

İddia bulunamadı (403 Engellendi)

İstek 403 Yasak ile başarısız olursa şunları doğrulayın:

  • Talep erişim belirtecinde var
  • Talep adı tam olarak eşleşir (büyük/küçük harfe duyarlı)
  • Kimlik sağlayıcısı, talebi içerecek şekilde yapılandırıldı

İlke uygulanmadı

Sonuçlar filtrelenmiyorsa:

  • Rol adının üst bilgi değeriyle eşleştiğinden X-MS-API-ROLE emin olun
  • Eylemin (okuma, güncelleştirme, silme) tanımlanmış bir ilkesi olduğunu onaylayın
  • Kimlik doğrulamanın yapılandırılmış olduğunu ve isteğin kimlik doğrulamasının yapıldığını kontrol edin.

Sözdizimi hataları

Motor bir politika ayrıştırma hatası raporluyorsa:

  • İfadenin OData söz dizimini (eq, ne, and, or) kullandığını doğrulayın
  • Alan adlarının eşlenen API adlarla (veritabanı sütun adları değil) eşleşdiğinden emin olun
  • Dize değerlerinin tek tırnak içine alındığından emin olun

İlgili içerik

  • Last updated on