Aracılığıyla paylaş

Veri API'si oluşturucusunda yetkilendirme ve roller

  • Makale

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ırma dosyasında belirtilen tanımlı izinlere göre denetlenebilir.

Roller

Roller, bir isteğin yürütülmesi gereken izin bağlamını ayarlar. Çalışma zamanı yapılandırmasında tanımlanan her varlık için, varlığa hem REST hem de GraphQL uç noktalarında nasıl erişilebileceğini belirleyen bir rol kümesi ve ilişkili izinler tanımlayabilirsiniz.

Veri API oluşturucusu istekleri tek bir rol bağlamında değerlendirir:

  • anonymous hiçbir erişim belirteci sunulmadığında.
  • authenticated geçerli bir erişim belirteci sunulduğunda.
  • <CUSTOM_USER_ROLE>geçerli bir erişim belirteci sunulduğunda X-MS-API-ROLEve HTTP üst bilgisi eklendiğinde, erişim belirtecinin roles talebine de dahil olan bir kullanıcı rolü belirtilir.

Roller eklenebilir değildir, yani her ikisinin de üyesi olan ve Role2 her iki Role1 rolle ilişkili izinleri devralmayan bir kullanıcı.

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ğine bakılmaksızın 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ırması tanımlı varlıklar rol için anonymous izinler içermelidir.

Örnek

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

"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ı, sistem rolünün authenticated Book varlığına okuma erişimi içerecek şekilde açıkça yapılandırılmasını gösterir:

"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 oluşturucusunun bir isteği kullanıcı rolü bağlamında değerlendirmesi için iki gereksinimin karşılanması gerekir:

  1. İstemci uygulaması tarafından sağlanan erişim belirteci, kullanıcının rol üyeliğini listeleyen rol taleplerini içermelidir.
  2. İstemci uygulamasının isteklerle BIRLIKTE HTTP üst bilgisini X-MS-API-ROLE içermesi ve üst bilginin değerini istenen kullanıcı rolü olarak ayarlaması gerekir.

Rol değerlendirme örneği

Aşağıdaki örnek, Veri API oluşturucusu ç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" ]
        }
    ]
}

Static Web Apps'da, kullanıcı varsayılan olarak anonim rolün bir üyesidir. Kullanıcının kimliği doğrulanırsa, kullanıcı hem hem authenticated de anonymous rollerinin üyesi olur.

İstemci uygulaması, Static Web Apps veritabanı bağlantıları (Önizleme) kullanılarak dağıtılan Veri API oluşturucusuna kimliği doğrulanmış bir istek gönderdiğinde, istemci uygulaması Static Web Apps JSON'a dönüştürülen bir erişim belirteci sağlar:

{
  "identityProvider": "azuread",
  "userId": "d75b260a64504067bfc5b2905e3b8182",
  "userDetails": "username",
  "userRoles": ["anonymous", "authenticated", "author"]
}

Veri API oluşturucusu istekleri tek bir rol bağlamında değerlendirdiğinden, isteği varsayılan olarak sistem rolü authenticated bağlamında değerlendirir.

İstemci uygulamasının isteği değeriyle authorHTTP üst bilgisini X-MS-API-ROLE de içeriyorsa, istek rol bağlamında author değerlendirilir. Erişim belirteci ve X-MS-API-ROLE HTTP üst bilgisi içeren örnek istek:

curl -k -r 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 X-MS-API-ROLE listelenen rolü içermediğinde istemci uygulamasının isteği reddedilir.

İzinler

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

  • Bir varlıkta rol üyeliğine göre kim 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 vardır?

İ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, HTTP üst bilgisinde X-MS-API-ROLE ayarlanan rol.

Varsayılan olarak güvenli

Varsayılan olarak, bir varlığın yapılandırılmış izinleri yoktur ve başka bir deyişle hiç kimse varlığa erişemez. Buna ek olarak, Veri API oluşturucusu çalışma zamanı yapılandırmasında başvurulmadığında veritabanı nesnelerini yoksayar.

İzinlerin açıkça yapılandırılması gerekir

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

Bir varlık üzerindeki izin tanımını basitleştirmek için rol için authenticated belirli izinler yoksa rol için anonymous tanımlanan izinlerin kullanıldığını varsayalım. Daha book önce gösterilen yapılandırma, anonim veya kimliği doğrulanmış tüm kullanıcıların varlık üzerinde okuma işlemleri gerçekleştirmesine book izin verir.

Okuma işlemlerinin yalnızca kimliği doğrulanmış kullanıcılarla kısıtlanması 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" ]
  }]
}

Varlık gerektirmez ve ve authenticated rolleri için anonymous izinlerle önceden yapılandırılmaz. Bir varlığın izin yapılandırmasında bir veya daha fazla kullanıcı rolü tanımlanabilir ve tanımlanamayan diğer tüm roller, sistem veya kullanıcı tanımlı rollerin erişimi otomatik olarak reddedilir.

Aşağıdaki örnekte, varlık için book tek tanımlı rol kullanıcı rolüdüradministrator. Kullanıcının rolün administrator üyesi olması ve varlıkta çalışması için bu rolü X-MS-API-ROLE HTTP üst bilgisine dahil etmesi book gerekir:

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

Not

Azure Cosmos DB ile Veri API oluşturucusu kullanırken GraphQL sorgularında erişim denetimini zorunlu kılmak için sağlanan GraphQL şema dosyanızda yönergesini @authorize kullanmanız gerekir. Ancak GraphQL sorgularındaki GraphQL mutasyonları ve filtreleri için erişim denetimi daha önce açıklandığı gibi izin yapılandırması tarafından yine de zorunlu kılınıyor.

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 tüm eylemleri temsil eder:

  • Tablolar ve Görünümler: create, read, update, delete
  • Saklı Yordamlar: execute

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

Alan erişimi

Bir eylem için hangi alanların erişilebilir olacağını yapılandırabilirsiniz. Örneğin, eyleme dahil etmek ve eylemden readdışlamak için hangi alanları ayarlayabilirsiniz.

Aşağıdaki örnek roldeki free-access kullanıcıların üzerinde Column3okuma işlemleri gerçekleştirmesini engeller. GET isteklerinde (REST uç noktası) veya sorgularda (GraphQL uç noktası) başvurular Column3 reddedilen bir istekle sonuçlanır:

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

Not

Azure Cosmos DB ile Veri API oluşturucusu kullanırken GraphQL sorgularında erişim denetimini zorunlu kılmak için sağlanan GraphQL şema dosyanızda yönergesini @authorize kullanmanız gerekir. Ancak GraphQL sorgularındaki GraphQL mutasyonları ve filtreleri için erişim denetimi yine de burada açıklandığı gibi izin yapılandırması tarafından zorlanır.

Öğe düzeyi güvenlik

Veritabanı ilkesi ifadeleri, sonuçların daha da kısıtlanmalarını sağlar. Veritabanı ilkeleri, ifadeleri veritabanında yürütülen sorgu koşullarını çevirir. Veritabanı ilkesi ifadeleri aşağıdaki eylemler için desteklenir:

  • oluşturmaya
  • okuma
  • update
  • delete

Uyarı

Saklı yordamlarla kullanılan yürütme eylemi, veritabanı ilkelerini desteklemez .

Not

Veritabanı ilkeleri şu anda NoSQL için CosmosDB tarafından desteklenmemektedir.

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

Örnek

Roldeki readconsumer eylemi yalnızca başlığın "Örnek Başlık" olduğu kayıtları döndürecek şekilde kısıtlayan bir veritabanı ilkesi.

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.title eq 'Sample Title'"
      }
    }
  ]
}

İlgili içerik