API Overview

Bu genel bakış sadece Casbin API'lerini nasıl kullanacağınızı gösterir ve Casbin'in nasıl kurulduğunu ya da nasıl çalıştığını açıklamaz. Bu eğitimleri şu adreste bulabilirsiniz: Casbin Kurulumu ve Casbin Nasıl Çalışır. Yani, bu eğitimi okumaya başladığınızda, Casbin'i kodunuza tamamen kurup içe aktardığınızı varsayıyoruz.

Zorunlu API

Casbin'in Zorunlu API'leriyle başlayalım. model.conf dosyasından bir RBAC modeli yükleyeceğiz ve policy.csv dosyasından politikalar yükleyeceğiz. Model sözdizimi hakkında buradan bilgi edinebilirsiniz ve bu öğreticide bunu ele almayacağız. Aşağıda verilen yapılandırma dosyalarını anlayabileceğinizi varsayıyoruz:

model.conf

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

policy.csv

p, admin, data1, read
p, admin, data1, write
p, admin, data2, read
p, admin, data2, write
p, alice, data1, read
p, bob, data2, write
g, amber, admin
g, abc, admin

Yapılandırma dosyalarını okuduktan sonra, lütfen aşağıdaki kodu okuyun.

// Load information from files.
enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
    log.Fatalf("Error, detail: %s", err)
}
ok, err := enforcer.Enforce("alice", "data1", "read")

Bu kod, erişim kontrol modelini ve politikaları yerel dosyalardan yükler. casbin.NewEnforcer() fonksiyonu bir zorlayıcı döndürecektir. İki parametresini dosya yolları olarak tanıyacak ve oradan dosyaları yükleyecektir. İşlem sırasında oluşan hatalar err değişkeninde saklanır. Bu kod, modeli ve politikaları yüklemek için varsayılan adaptörü kullanır ve tabii ki, aynı sonucu bir üçüncü taraf adaptör kullanarak da elde edebilirsiniz.

ok, err := enforcer.Enforce("alice", "data1", "read") kodu, erişim izinlerini onaylamak için kullanılır. Eğer Alice read işlemiyle data1'e erişebiliyorsa, ok'un dönüş değeri true olacaktır; aksi takdirde false olacaktır. Bu örnekte, ok değeri true'dur.

EnforceEx API

Bazen hangi politikanın isteğe izin verdiğini merak edebilirsiniz, bu yüzden EnforceEx() fonksiyonunu hazırladık. Bunu şu şekilde kullanabilirsiniz:

ok, reason, err := enforcer.EnforceEx("amber", "data1", "read")
fmt.Println(ok, reason) // true [admin data1 read]

EnforceEx() fonksiyonu, dönüş değeri reason içinde tam politikayı döndürecektir. Bu örnekte, amber bir admin rolüdür, bu nedenle politik p, admin, data1, read bu isteğin true olmasına izin verdi. Bu kodun çıktısı yorum içinde.

Casbin, bu benzeri birçok API sağlamıştır. Bu API'ler temel olanlara bazı ek fonksiyonlar ekler. Bunlar şunları içerir:

• ok, err := enforcer.EnforceWithMatcher(matcher, request)

  Bu fonksiyon bir eşleştirici kullanır.

• ok, reason, err := enforcer.EnforceExWithMatcher(matcher, request)

  Bu, EnforceWithMatcher() ve EnforceEx() kombinasyonudur.

• boolArray, err := enforcer.BatchEnforce(requests)

  Bu fonksiyon, bir iş listesi sağlar ve bir dizi döndürür.

Bu, Casbin'in basit bir kullanım örneğidir. Casbin'i bu API'leri kullanarak bir yetkilendirme sunucusu başlatmak için kullanabilirsiniz. Sonraki paragraflarda sizlere bazı diğer API türlerini göstereceğiz.

Yönetim API'si

Get API

Bu API'ler, politikalardaki belirli nesneleri almak için kullanılır. Bu örnekte, bir enforcer yüklüyoruz ve ondan bir şey alıyoruz.

Lütfen aşağıdaki koda göz atın:

enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
    fmt.Printf("Error, details: %s\n", err)
}
allSubjects := enforcer.GetAllSubjects()
fmt.Println(allSubjects)

Önceki örneğe benzer şekilde, ilk dört satır yerel dosyalardan gerekli bilgileri yüklemek için kullanılır. Burada bunu daha fazla tartışmayacağız.

Kod allSubjects := enforcer.GetAllSubjects() politikalar dosyasındaki tüm konuları alır ve bunları bir dizi olarak döndürür. Daha sonra bu diziyi yazdırırız.

Tipik olarak, kodun çıktısı şöyle olmalıdır:

[admin alice bob]

Ayrıca GetAllSubjects() fonksiyonunu GetAllNamedSubjects() olarak değiştirerek, şu anki adlandırılmış politikada geçen konuların listesini alabilirsiniz.

Benzer şekilde, Objects, Actions, Roles için GetAll fonksiyonları hazırladık. Bu fonksiyonlara erişmek için, fonksiyon adındaki Subject kelimesini istenen kategoriyle değiştirmeniz yeterlidir.

Ek olarak, politikalar için daha fazla alıcı mevcuttur. Çağırma yöntemi ve dönüş değerleri yukarıda bahsedilenlerle benzerdir.

• policy = e.GetPolicy() politikadaki tüm yetkilendirme kurallarını alır.
• filteredPolicy := e.GetFilteredPolicy(0, "alice") belirtilen alan filtreleriyle ilgili politika içindeki tüm yetkilendirme kurallarını alır.
• namedPolicy := e.GetNamedPolicy("p") adlandırılmış politika içindeki tüm yetkilendirme kurallarını alır.
• filteredNamedPolicy = e.GetFilteredNamedPolicy("p", 0, "bob") adlandırılmış politika içindeki belirtilen alan filtreleriyle tüm yetkilendirme kurallarını alır.
• groupingPolicy := e.GetGroupingPolicy() politika içindeki tüm rol miras kurallarını alır.
• filteredGroupingPolicy := e.GetFilteredGroupingPolicy(0, "alice") belirtilen alan filtreleriyle politika içindeki tüm rol miras kurallarını alır.
• namedGroupingPolicy := e.GetNamedGroupingPolicy("g") politika içindeki tüm rol miras kurallarını alır.
• namedGroupingPolicy := e.GetFilteredNamedGroupingPolicy("g", 0, "alice") belirtilen alan filtreleriyle politika içindeki tüm rol miras kurallarını alır.

Ekle, Sil, Güncelle API

Casbin, çalışma zamanında politikaları dinamik olarak eklemek, silmek veya değiştirmek için çeşitli API'ler sağlar.

Aşağıdaki kod, politikaları nasıl eklemek, kaldırmak ve güncellemek ve ayrıca bir politika olup olmadığını kontrol etmek için nasıl kullanılacağını gösterir:

// load information from files
enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
    fmt.Printf("Error, details: %s\n", err)
}

// add a policy and use HasPolicy() to confirm
enforcer.AddPolicy("added_user", "data1", "read")
hasPolicy := enforcer.HasPolicy("added_user", "data1", "read")
fmt.Println(hasPolicy) // true, the policy was added successfully

// remove a policy and use HasPolicy() to confirm
enforcer.RemovePolicy("alice", "data1", "read")
hasPolicy = enforcer.HasPolicy("alice", "data1", "read")
fmt.Println(hasPolicy) // false, the policy was removed successfully

// update a policy and use HasPolicy() to confirm
enforcer.UpdatePolicy([]string{"added_user", "data1", "read"}, []string{"added_user", "data1", "write"})
hasPolicy = enforcer.HasPolicy("added_user", "data1", "read")
fmt.Println(hasPolicy) // false, the original policy has expired
hasPolicy = enforcer.HasPolicy("added_user", "data1", "write")
fmt.Println(hasPolicy) // true, the new policy is in effect

Bu API'leri kullanarak, politikalarınızı dinamik olarak düzenleyebilirsiniz. Benzer şekilde, FilteredPolicy, NamedPolicy, FilteredNamedPolicy, GroupingPolicy, NamedGroupingPolicy, FilteredGroupingPolicy, FilteredNamedGroupingPolicy için benzer API'ler sağladık. Bunları kullanmak için, fonksiyon adındaki Policy kelimesini uygun kategoriyle değiştirmek yeterlidir.

Ayrıca, parametreleri dizilere değiştirerek, politikalarınızı toplu olarak düzenleyebilirsiniz.

Örneğin, böyle fonksiyonlar düşünün:

enforcer.UpdatePolicy([]string{"eve", "data3", "read"}, []string{"eve", "data3", "write"})

Eğer Policy yerine Policies koyar ve parametreleri aşağıdaki gibi değiştirirsek:

enforcer.UpdatePolicies([][]string{{"eve", "data3", "read"}, {"jack", "data3", "read"}}, [][]string{{"eve", "data3", "write"}, {"jack", "data3", "write"}})

o zaman bu politikaları toplu olarak düzenleyebiliriz.

Aynı işlemler GroupingPolicy, NamedGroupingPolicy için de uygulanabilir.

AddEx API

Casbin, kullanıcıların kuralları toplu olarak eklemeye yardımcı olmak için AddEx serisi API'leri sağlar.

AddPoliciesEx(rules [][]string) (bool, error)
AddNamedPoliciesEx(ptype string, rules [][]string) (bool, error)
AddGroupingPoliciesEx(rules [][]string) (bool, error)
AddNamedGroupingPoliciesEx(ptype string, rules [][]string) (bool, error)
SelfAddPoliciesEx(sec string, ptype string, rules [][]string) (bool, error) 

Bu yöntemler ile Ex soneksi olmayan yöntemler arasındaki fark, eğer kurallardan biri zaten mevcutsa, hemen false dönmek yerine bir sonraki kuralı kontrol etmeye devam edecekleridir.

Örneğin, AddPolicies ve AddPoliciesEx'i karşılaştıralım.

Aşağıdaki kodu casbin altındaki teste kopyalayarak çalıştırabilir ve gözlemleyebilirsiniz.

func TestDemo(t *testing.T) {
    e, err := NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv")
    if err != nil {
        fmt.Printf("Error, details: %s\n", err)
    }
    e.ClearPolicy()
    e.AddPolicy("user1", "data1", "read")
    fmt.Println(e.GetPolicy())
    testGetPolicy(t, e, [][]string{{"user1", "data1", "read"}})

    // policy {"user1", "data1", "read"} now exists

    // Use AddPolicies to add rules in batches
    ok, _ := e.AddPolicies([][]string{{"user1", "data1", "read"}, {"user2", "data2", "read"}})
    fmt.Println(e.GetPolicy())
    // {"user2", "data2", "read"} failed to add because {"user1", "data1", "read"} already exists
    // AddPolicies returns false and no other policies are checked, even though they may not exist in the existing ruleset
    // ok == false
    fmt.Println(ok)
    testGetPolicy(t, e, [][]string{{"user1", "data1", "read"}})

    // Use AddPoliciesEx to add rules in batches
    ok, _ = e.AddPoliciesEx([][]string{{"user1", "data1", "read"}, {"user2", "data2", "read"}})
    fmt.Println(e.GetPolicy())
    // {"user2", "data2", "read"} is added successfully
    // because AddPoliciesEx automatically filters the existing {"user1", "data1", "read"}
    // ok == true
    fmt.Println(ok)
    testGetPolicy(t, e, [][]string{{"user1", "data1", "read"}, {"user2", "data2", "read"}})
}

RBAC API

Casbin, RBAC modelini ve politikalarını değiştirmeniz için size bazı API'ler sunar. Eğer RBAC'a aşinasanız, bu API'leri kolayca kullanabilirsiniz.

Burada, Casbin'in RBAC API'lerini nasıl kullanacağınızı gösteriyoruz ve RBAC'ın kendisinden bahsetmiyoruz. Daha fazla ayrıntıyı buradan alabilirsiniz.

Modeli ve politikaları, daha önce olduğu gibi yüklemek için aşağıdaki kodu kullanırız.

enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
    fmt.Printf("Error, details: %s\n", err)
}

Ardından, bu API'lere erişmek için enforcer adlı bir Enforcer örneği kullanabiliriz.

roles, err := enforcer.GetRolesForUser("amber")
fmt.Println(roles) // [admin]
users, err := enforcer.GetUsersForRole("admin")
fmt.Println(users) // [amber abc]

GetRolesForUser() bir dizi döndürür ve bu dizi, amber'in sahip olduğu tüm rolleri içerir. Bu örnekte, amber'in sadece bir rolü vardır, ki bu da admin'dir, bu nedenle roles dizisi [admin] şeklindedir. Benzer şekilde, bir role ait kullanıcıları almak için GetUsersForRole() kullanabilirsiniz. Bu fonksiyonun dönüş değeri de bir dizidir.

enforcer.HasRoleForUser("amber", "admin") // true

Bir kullanıcının rolün üyesi olup olmadığını doğrulamak için HasRoleForUser() kullanabilirsiniz. Bu örnekte, amber admin'in bir üyesidir, bu nedenle fonksiyonun dönüş değeri true şeklindedir.

fmt.Println(enforcer.Enforce("bob", "data2", "write")) // true
enforcer.DeletePermission("data2", "write")
fmt.Println(enforcer.Enforce("bob", "data2", "write")) // false

Bir izni silmek için DeletePermission() kullanabilirsiniz.

fmt.Println(enforcer.Enforce("alice", "data1", "read")) // true
enforcer.DeletePermissionForUser("alice", "data1", "read")
fmt.Println(enforcer.Enforce("alice", "data1", "read")) // false

Ve bir kullanıcı için izni silmek için DeletePermissionForUser() kullanabilirsiniz.

Casbin'in buna benzer birçok API'si bulunmaktadır. Çağırma yöntemleri ve dönüş değerleri, yukarıdaki API'lerle aynı stilde olup aynıdır. Bu API'leri sonraki belgelerde bulabilirsiniz.