Veri API'si oluşturucusunda yetkilendirme ve roller

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.

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 Authorization: Bearer <token> gönderdiği JWT taşıyıcı sağlayıcıları için geçerlidir (örneğin EntraID/AzureADCustom).

Taşıyıcı belirteci sağlandı	X-MS-API-ROLE Sağlanan	belirteç roles talebinde istenen rol var	Etkin rol / sonuç
Hayı	Hayı	Mevcut Değil	Anonymous
Evet (geçerli)	Hayı	Mevcut Değil	Authenticated
Evet (geçerli)	Evet	Hayı	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): Kimlik doğrulaması taşıyıcı belirteç yerine platform tarafından eklenen başlıklar (örneğin, X-MS-CLIENT-PRINCIPAL) ile sağlanabilir.
• Simulator: istekler, gerçek bir token doğrulanması olmadan geliştirme/test amaçlı kimliği doğrulanmış olarak kabul edilir.

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.

Örnek

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.

Örnek

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 birden çok rol tanımlanmış 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.

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

Hem kimliği doğrulanmamış hem de kimliği doğrulanmış kullanıcıların erişimi olmasını istiyorsanız, her iki sistem rolüne (Anonymous ve ) açıkça izin verin Authenticated.

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.

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.

Öğe düzeyi 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	Desteklenmez
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"
      }
    }
  ]
}

İlgili içerik

• Satır düzeyi filtreleme için veritabanı ilkelerini yapılandırma
• Microsoft Entra Id kimlik doğrulamayı yapılandırma
• Yerel test için Simülatör kimlik doğrulamasını yapılandırma