Yetkilendirmeye genel bakış

Yetkilendirme, kimliği doğrulanmış kullanıcıların Veri API'sini oluşturucu uygulamanızda ne yapmalarına izin verileceğini belirler. Kimlik doğrulaması kullanıcının kim olduğunu doğrulasa da, yetkilendirme kullanıcının erişebileceği ve değiştirebileceği şeyleri denetler.

Veri API'si oluşturucusu rol tabanlı yetkilendirme iş akışı kullanır. Kimliği doğrulanmış veya doğrulanmamış tüm gelen istekler bir role atanır. Roller Sistem Rolleri veya Kullanıcı Rolleri olabilir. Atanan rol daha sonra, istenen varlıkta söz konusu rol için hangi eylemlerin, alanların ve ilkelerin kullanılabilir olduğunu anlamak için yapılandırmada belirtilen tanımlı izinlere göre denetlenebilir.

Önemli yetkilendirme kavramları

Varlık izinleri

Varlık düzeyinde CRUD işlemlerini (Oluşturma, Okuma, Güncelleştirme, Silme) denetleyin. Her role belirli varlıklar üzerinde belirli eylemler verilebilir veya reddedilebilir.

Rol tabanlı erişim denetimi

Kullanıcıları rollere atayın ve rol üyeliğine göre izinler verin. Roller, benzer erişim desenlerine sahip büyük kullanıcı gruplarının yönetimini basitleştirir.

Satır düzeyi güvenlik (RLS)

Verileri kullanıcı kimliğine veya oturum bağlamlarına göre filtreleyin. Kullanıcılar, yalnızca erişim yetkisine sahip oldukları ve veritabanı düzeyinde uygulanan satırları görür.

API ilkeleri

API yanıtlarına OData koşullarını ve filtrelerini uygulayın. İlkeler, kullanıcı taleplerine ve kimliğine göre sorgu sonuçlarını otomatik olarak kısıtlar.

Talep tabanlı yetkilendirme

Erişimi belirlemek için kimlik doğrulama belirteçlerinden gelen talepleri kullanın (örneğin, gruplar, roller, özel öznitelikler). Talepler esnek, ayrıntılı izin kararları sağlar.

Nasıl çalışır?

1. Kullanıcı desteklenen kimlik doğrulama yöntemlerinden birini kullanarak kimlik doğrulaması yapar
2. Sistem kimlik doğrulama belirtecinden (roller, gruplar, kuruluş vb.) hak taleplerini ayıklar.
3. Yetkilendirme kuralları kullanıcının taleplerine ve istenen kaynağa göre değerlendirilir
4. Erişim, varlık izinleri, ilkeleri ve satır düzeyi güvenlik kuralları temelinde verilir veya reddedilir

Kullanıcının rolünü belirleme

Hiçbir rolün varsayılan izinleri yoktur. Veri API'sinin oluşturucusu bir rol belirledikten sonra isteğin başarılı olması için varlığın permissions bu rolü tanımlaması actions gerekir.

Aşağıdaki rol değerlendirme matrisi, istemcinin gönderdiği JSON Web Belirteci (JWT) taşıyıcı sağlayıcıları (örneğin, EntraID/AzureAD ve CustomAuthorization: Bearer <token>) için geçerlidir.

Taşıyıcı belirteci sağlandı	X-MS-API-ROLE Sağlanan	belirteç roles talebinde istenen rol var	Etkin rol / sonuç
Hayır	Hayır	Mevcut Değil	Anonymous
Evet (geçerli)	Hayır	Mevcut Değil	Authenticated
Evet (geçerli)	Evet	Hayır	Reddedildi (403 Yasak)
Evet (geçerli)	Evet	Evet	X-MS-API-ROLE değer
Evet (geçersiz)	Herhangi biri	Mevcut Değil	Reddedildi (401 Yetkisiz)

Anonymous veya Authenticated dışında bir rol kullanmak için, X-MS-API-ROLE üst bilgisi gereklidir.

Uyarı

İstek, kimliği doğrulanmış yetkili kullanıcıdaki birçok rolle ilişkilendirilebilir. Ancak, Veri API oluşturucusu izinleri ve ilkeleri tam olarak tek bir etkili rol bağlamında değerlendirir. Sağlandığında, X-MS-API-ROLE üst bilgi hangi rolün kullanılacağını seçer.

Sağlayıcı notları:

• EasyAuth sağlayıcıları (örneğin, AppService): platform tarafından eklenen başlıklar (örneğin X-MS-CLIENT-PRINCIPAL), taşıyıcı belirteç yerine kimlik doğrulaması sağlar.
• Simulator: istekler, gerçek bir belirteç doğrulanmadan geliştirme/test amaçlı olarak authenticated olarak işlenir.

Sistem rolleri

Sistem rolleri, Veri API'si oluşturucusu tarafından tanınan yerleşik rollerdir. Sistem rolü, istek sahibinin erişim belirteçlerinde belirtilen rol üyeliğinden bağımsız olarak istek sahibine otomatik olarak atanır. İki sistem rolü vardır: Anonymous ve Authenticated.

Anonim sistem rolü

Sistem Anonymous rolü, kimliği doğrulanmamış kullanıcılar tarafından yürütülen isteklere atanır. Kimliği doğrulanmamış erişim isteniyorsa çalışma zamanı yapılandırma tanımlı varlıkların Anonymous rol izinleri içermesi gerekir.

Example

Aşağıdaki Veri API'si oluşturucu çalışma zamanı yapılandırmasında, sistem rolünün Anonymous Kitap varlığına okuma erişimi içerecek şekilde açıkça yapılandırılması gösterilmektedir:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "Anonymous",
            "actions": [ "read" ]
        }
    ]
}

İstemci uygulaması kimliği doğrulanmamış bir kullanıcı adına Book varlığına erişen bir istek gönderdiğinde, uygulama HTTP üst bilgisini içermemelidir Authorization .

Kimliği doğrulanmış sistem rolü

Sistem Authenticated rolü, kimliği doğrulanmış kullanıcılar tarafından yürütülen isteklere atanır.

Example

Aşağıdaki Veri API'si oluşturucu çalışma zamanı yapılandırmasında, sistem rolünün Authenticated Kitap varlığına okuma erişimi içerecek şekilde açıkça yapılandırılması gösterilmektedir:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "Authenticated",
            "actions": [ "read" ]
        }
    ]
}

Kullanıcı rolleri

Kullanıcı rolleri, çalışma zamanı yapılandırmasında ayarladığınız kimlik sağlayıcısındaki kullanıcılara atanan sistem dışı rollerdir. Veri API'sinin oluşturucusunun bir isteği kullanıcı rolü bağlamında değerlendirmesi için iki gereksinimin karşılanması gerekir:

1. Kimliği doğrulanmış sorumlu, kullanıcının rol üyeliğini listeleyen rol taleplerini (örneğin, JWT roles talebi) içermelidir.
2. İstemci uygulaması, HTTP üst bilgisini X-MS-API-ROLE ile isteklerde içermeli ve üst bilginin değerini istenen kullanıcı rolü olarak ayarlamalıdır.

Rol değerlendirme örneği

Aşağıdaki örnek, Data API builder çalışma zamanı yapılandırmasında yapılandırılan varlığa yapılan Book istekleri aşağıda gösterildiği gibi gösterir:

"Book": {
    "source": "books",
    "permissions": [
        {
      "role": "Anonymous",
            "actions": [ "read" ]
        },
        {
      "role": "Authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

Veri API oluşturucusu istekleri tek bir etkili rol bağlamında değerlendirir. Eğer bir isteğin kimliği doğrulanmışsa ve X-MS-API-ROLE başlığı sağlanmamışsa, Veri API oluşturucu isteği varsayılan olarak Authenticated sistem rolü bağlamında değerlendirir.

İstemci uygulamasının isteği, değer olarak X-MS-API-ROLE ile birlikte HTTP üst bilgisini author içeriyorsa, istek author rol bağlamında değerlendirilir. Erişim belirteci ve X-MS-API-ROLE HTTP üst bilgisi de dahil olmak üzere örnek istek:

curl -k -X GET \
  -H 'Authorization: Bearer ey...' \
  -H 'X-MS-API-ROLE: author' \
  https://localhost:5001/api/Book

Önemli

Sağlanan erişim belirtecinin roles talebi üst bilgide listelenen rolü içermediğinde istemci uygulamasının X-MS-API-ROLE isteği reddedilir.

İzinler

İzinler şu şekilde açıklanmaktadır:

• Kim rol üyeliğine göre bir varlık üzerinde istekte bulunabilir?
• Kullanıcının gerçekleştirebileceği eylemler (oluşturma, okuma, güncelleştirme, silme, yürütme)
• Belirli bir eylem için hangi alanlara erişilebilir?
• İstek tarafından döndürülen sonuçlarda hangi ek kısıtlamalar var?

İzinleri tanımlama söz dizimi çalışma zamanı yapılandırma makalesinde açıklanmıştır.

Önemli

Tek bir varlığın izin yapılandırmasında tanımlanan birden çok rol olabilir. Ancak istek yalnızca tek bir rol bağlamında değerlendirilir:

• Varsayılan olarak, sistem rolü Anonymous veya Authenticated
• Eklendiğinde, X-MS-API-ROLE rolü HTTP üst bilgisine ayarlanır.

Varsayılan olarak güvenli

Varsayılan olarak, bir varlığın yapılandırılmış izni yoktur ve bu da hiç kimsenin varlığa erişe olmadığı anlamına gelir. Ayrıca, Veri API oluşturucusu çalışma zamanı yapılandırmasında başvurulmuyorsa veritabanı nesnelerini yoksayar.

Eylemler

Eylemler , bir rolün kapsamındaki bir varlığın erişilebilirliğini açıklar. Eylemler tek tek veya joker karakter kısayoluyla belirtilebilir: * (yıldız işareti). Joker karakter kısayolu, varlık türü için desteklenen eylemlerin tümünü temsil eder:

• Tablolar ve Görünümler: create, read, update, delete
• Saklanan Prosedürler: execute

Eylemler hakkında daha fazla bilgi için yapılandırma dosyası belgelerine bakın.

Alan erişimi

Eylem için hangi alanların erişilebilir olacağını yapılandırabilirsiniz. Örneğin, eyleme dahil etmek ve eylemdenread dışlamak için hangi alanları ayarlayabilirsiniz.

Aşağıdaki örnek, free-access rolündeki kullanıcıların Column3 üzerinde okuma işlemleri gerçekleştirmesini engeller. GET isteklerindeki (REST uç noktası) veya sorgulardaki (GraphQL uç noktası) Column3 referansları, isteğin reddedilmesiyle sonuçlanır:

    "book": {
      "source": "dbo.books",
      "permissions": [
        {
          "role": "free-access",
          "actions": [
            "create",
            "update",
            "delete",
            {
              "action": "read",
              "fields": {
                "include": [ "Column1", "Column2" ],
                "exclude": [ "Column3" ]
              }
            }
          ]
        }
      ]
    }

Uyarı

Azure Cosmos DB ile Veri API oluşturucusu kullanılırken GraphQL sorgularında erişim denetimini zorunlu kılmak için sağlanan @authorize yönergesini kullanmanız gerekir. Ancak GraphQL sorgularındaki GraphQL mutasyonları ve filtreleri için izin yapılandırması burada açıklandığı gibi erişim denetimini zorunlu kılmaya devam eder.

Veritabanı ilkeleri (öğe düzeyinde güvenlik)

Veritabanı ilkeleri , sonuçları satır düzeyinde filtrelemenize olanak verir. İlkeler, veritabanının değerlendirdiği sorgu koşulunu çevirir ve kullanıcıların yalnızca yetkili kayıtlara erişmesini sağlar.

Desteklenen eylemler	Desteklenmiyor
read, update, delete	create, execute

Uyarı

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

Ayrıntılı yapılandırma adımları, söz dizimi başvurusu ve örnekler için bkz. Veritabanı ilkelerini yapılandırma.

Hızlı örnek

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.ownerId eq @claims.userId"
      }
    }
  ]
}

Rol devralma

DAB 2.0 rol devralmayı tanıtır, bu nedenle her rolde aynı izin bloğunu yinelemeniz gerekmez. Devralma zinciri:

named-role → authenticated → anonymous

• Bir varlık için authenticated açıkça yapılandırılmamışsa, anonymous öğesinden devralır.
• Adlandırılmış bir rol yapılandırılmamışsa, authenticated öğesinden devralır veya anonymous de yoksa authenticated öğesinden devralır.

İzinleri anonymous üzerinde bir kez tanımlayarak, her daha geniş kapsamlı rol aynı erişimi otomatik olarak alır ve çoğaltma gerekmez.

Uyarı

Bu bölümde açıklanan Veri API oluşturucusu 2.0 işlevselliği şu anda önizleme aşamasındadır ve genel kullanılabilirlik öncesinde değişebilir. Daha fazla bilgi için bkz. Sürüm 2.0'daki yenilikler.

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

Bu yapılandırmayla, anonymous, authenticated ve herhangi bir yapılandırılmamış adlandırılmış rol Book'yi okuyabilir.

Devralma uygulandıktan sonra her varlık için çözümlenmiş izinleri görüntülemek amacıyla dab configure --show-effective-permissions kullanın.

İzinler açıkça yapılandırılmalıdır

Bir varlığa kimliği doğrulanmamış erişime izin vermek için rolün Anonymous varlığın izinlerinde açıkça tanımlanması gerekir. Örneğin, varlığın book izinleri kimliği doğrulanmamış okuma erişimine izin verecek şekilde açıkça ayarlanır:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "Anonymous",
    "actions": [ "read" ]
  }]
}

Okuma işlemlerinin yalnızca kimliği doğrulanmış kullanıcılarla sınırlandırılması gerektiğinde, aşağıdaki izin yapılandırması ayarlanmalıdır ve bu da kimliği doğrulanmamış isteklerin reddedilmesine neden olur:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "Authenticated",
    "actions": [ "read" ]
  }]
}

Bir varlık, Anonymous ve Authenticated rolleri için izin gerektirmez ve önceden yapılandırılmamıştır. Bir varlığın izin yapılandırmasında bir veya daha fazla kullanıcı rolü tanımlanabilir ve tanımlanan diğer tüm tanımlanmamış rollere, sisteme veya kullanıcıya erişim otomatik olarak reddedilir.

Aşağıdaki örnekte, varlık için administrator tanımlanan tek rol kullanıcı rolüdürbook. Kullanıcının, administrator rolünün bir üyesi olması ve X-MS-API-ROLE varlığı üzerinde işlem yapabilmesi için bu rolü book HTTP üst bilgisine eklemesi gerekir.

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "administrator",
    "actions": [ "*" ]
  }]
}

Uyarı

Azure Cosmos DB ile Veri API oluşturucusu kullanılırken GraphQL sorgularında erişim denetimini zorunlu kılmak için sağlanan @authorize yönergesini kullanmanız gerekir. Ancak GraphQL sorgularındaki GraphQL mutasyonları ve filtreleri için izin yapılandırması daha önce açıklandığı gibi erişim denetimini zorunlu kılmaya devam eder.

Katmanlı güvenlik modeli

Veri API'si oluşturucusu birden çok yetkilendirme katmanı kullanır:

• Varlık düzeyi: Hangi varlıkların ve işlemlerin erişilebilir olduğu
• İlke düzeyi: Hangi veriler döndürülür (taleplere göre filtreleme)
• Satır düzeyi: Veritabanı, RLS aracılığıyla satır filtreleme uygular
• API düzeyi: HTTP üst bilgileri ve istek doğrulama

Sonraki Adımlar

• Rol devralma—Rol hiyerarşileri oluşturma
• API ilkeleri—Taleplere göre OData filtreleri uygulama
• Satır düzeyi güvenlik—Verileri veritabanı düzeyinde filtreleme
• En iyi yöntemler—Güvenlik sağlamlaştırma kılavuzu