Lewati ke konten utama

API Overview

Gambaran ini hanya menunjukkan cara menggunakan API Casbin dan tidak menjelaskan bagaimana Casbin diinstal atau bagaimana cara kerjanya. Anda dapat menemukan tutorial tersebut di sini: Instalasi Casbin dan Cara Kerja Casbin. Jadi, ketika Anda mulai membaca tutorial ini, kami menganggap bahwa Anda telah sepenuhnya menginstal dan mengimpor Casbin ke dalam kode Anda.

Paksa API​

Mari kita mulai dengan API Paksa Casbin. Kami akan memuat model RBAC dari model.conf dan memuat kebijakan dari policy.csv. Anda dapat mempelajari sintaks Model di sini, dan kami tidak akan membahasnya dalam tutorial ini. Kami menganggap bahwa Anda dapat memahami file konfigurasi yang diberikan di bawah ini:

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

Setelah membaca file konfigurasi, silakan baca kode berikut.

// 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")

Kode ini memuat model kontrol akses dan kebijakan dari file lokal. Fungsi casbin.NewEnforcer() akan mengembalikan sebuah enforcer. Ini akan mengenali dua parameter sebagai jalur file dan memuat file dari sana. Kesalahan yang terjadi dalam proses disimpan dalam variabel err. Kode ini menggunakan adaptor default untuk memuat model dan kebijakan, dan tentu saja, Anda dapat mencapai hasil yang sama dengan menggunakan adaptor pihak ketiga.

Kode ok, err := enforcer.Enforce("alice", "data1", "read") digunakan untuk mengonfirmasi izin akses. Jika Alice dapat mengakses data1 dengan operasi baca, nilai kembalian ok akan menjadi true; jika tidak, akan menjadi false. Dalam contoh ini, nilai ok adalah true.

EnforceEx API​

Terkadang Anda mungkin bertanya-tanya kebijakan mana yang mengizinkan permintaan, jadi kami telah menyiapkan fungsi EnforceEx(). Anda dapat menggunakannya seperti ini:

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

Fungsi EnforceEx() akan mengembalikan string kebijakan yang tepat dalam nilai kembalian reason. Dalam contoh ini, amber memiliki peran admin, sehingga kebijakan p, admin, data1, read mengizinkan permintaan ini menjadi true. Output dari kode ini ada dalam komentar.

Casbin telah menyediakan banyak API yang mirip dengan ini. API-API ini menambahkan beberapa fungsi tambahan ke yang dasar. Termasuk:

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

    Fungsi ini menggunakan matcher.

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

    Ini adalah kombinasi dari EnforceWithMatcher() dan EnforceEx().

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

    Fungsi ini memungkinkan daftar pekerjaan dan mengembalikan sebuah array.

Ini adalah kasus penggunaan sederhana dari Casbin. Anda dapat menggunakan Casbin untuk memulai server otorisasi menggunakan API ini. Kami akan menunjukkan beberapa jenis API lainnya di paragraf berikutnya.

API Manajemen​

API Dapatkan​

API ini digunakan untuk mengambil objek tertentu dalam kebijakan. Dalam contoh ini, kami sedang memuat enforcer dan mengambil sesuatu darinya.

Silakan lihat kode berikut:

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)

Mirip dengan contoh sebelumnya, empat baris pertama digunakan untuk memuat informasi yang diperlukan dari file lokal. Kami tidak akan membahas itu lebih lanjut di sini.

Kode allSubjects := enforcer.GetAllSubjects() mengambil semua subjek dalam file kebijakan dan mengembalikannya sebagai sebuah array. Kami kemudian mencetak array tersebut.

Biasanya, output dari kode tersebut seharusnya:

[admin alice bob]

Anda juga dapat mengubah fungsi GetAllSubjects() menjadi GetAllNamedSubjects() untuk mendapatkan daftar subjek yang muncul dalam kebijakan bernama saat ini.

Demikian pula, kami telah menyiapkan fungsi GetAll untuk Objects, Actions, Roles. Untuk mengakses fungsi-fungsi ini, Anda hanya perlu mengganti kata Subject dalam nama fungsi dengan kategori yang diinginkan.

Selain itu, terdapat lebih banyak getter yang tersedia untuk kebijakan. Metode pemanggilan dan nilai kembaliannya serupa dengan yang disebutkan di atas.

  • policy = e.GetPolicy() mengambil semua aturan otorisasi dalam kebijakan.
  • filteredPolicy := e.GetFilteredPolicy(0, "alice") mengambil semua aturan otorisasi dalam kebijakan dengan filter bidang yang ditentukan.
  • namedPolicy := e.GetNamedPolicy("p") mengambil semua aturan otorisasi dalam kebijakan bernama.
  • filteredNamedPolicy = e.GetFilteredNamedPolicy("p", 0, "bob") mengambil semua aturan otorisasi dalam kebijakan bernama dengan filter bidang yang ditentukan.
  • groupingPolicy := e.GetGroupingPolicy() mengambil semua aturan pewarisan peran dalam kebijakan.
  • filteredGroupingPolicy := e.GetFilteredGroupingPolicy(0, "alice") mengambil semua aturan pewarisan peran dalam kebijakan dengan filter bidang yang ditentukan.
  • namedGroupingPolicy := e.GetNamedGroupingPolicy("g") mengambil semua aturan pewarisan peran dalam kebijakan.
  • namedGroupingPolicy := e.GetFilteredNamedGroupingPolicy("g", 0, "alice") mengambil semua aturan pewarisan peran dalam kebijakan dengan filter bidang yang ditentukan.

Tambah, Hapus, Perbarui API​

Casbin menyediakan berbagai API untuk menambahkan, menghapus, atau memodifikasi kebijakan secara dinamis pada saat runtime.

Kode berikut menunjukkan cara menambahkan, menghapus, dan memperbarui kebijakan, serta cara memeriksa apakah suatu kebijakan ada:

// 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

Dengan menggunakan API ini, Anda dapat mengedit kebijakan Anda secara dinamis. Demikian pula, kami telah menyediakan API serupa untuk FilteredPolicy, NamedPolicy, FilteredNamedPolicy, GroupingPolicy, NamedGroupingPolicy, FilteredGroupingPolicy, FilteredNamedGroupingPolicy. Untuk menggunakannya, gantilah kata Policy dalam nama fungsi dengan kategori yang sesuai.

Selain itu, dengan mengubah parameter menjadi array, Anda dapat melakukan pengeditan batch pada kebijakan Anda.

Misalnya, pertimbangkan fungsi-fungsi seperti ini:

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

Jika kita mengubah Policy menjadi Policies dan memodifikasi parameter sebagai berikut:

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

maka kita dapat melakukan pengeditan batch pada kebijakan ini.

Operasi yang sama juga dapat diterapkan pada GroupingPolicy, NamedGroupingPolicy.

API AddEx​

Casbin menyediakan serangkaian API AddEx untuk membantu pengguna menambahkan aturan secara batch.

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)

Perbedaan antara metode-metode ini dan metode-metode tanpa akhiran Ex adalah jika salah satu aturan sudah ada, mereka akan terus memeriksa aturan berikutnya alih-alih mengembalikan false segera.

Misalnya, mari kita bandingkan AddPolicies dan AddPoliciesEx.

Anda dapat menjalankan dan mengamati kode berikut dengan menyalin ke dalam pengujian di casbin.

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 menyediakan beberapa API untuk Anda memodifikasi model dan kebijakan RBAC. Jika Anda familiar dengan RBAC, Anda dapat dengan mudah menggunakan API ini.

Di sini, kami hanya menunjukkan cara menggunakan API RBAC Casbin dan tidak akan membahas RBAC itu sendiri. Anda bisa mendapatkan detail lebih lanjut di sini.

Kami menggunakan kode berikut untuk memuat model dan kebijakan, seperti sebelumnya.

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

Kemudian, kita dapat menggunakan instance dari Enforcer enforcer untuk mengakses API ini.

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

GetRolesForUser() mengembalikan sebuah array yang berisi semua peran yang dimiliki oleh amber. Dalam contoh ini, amber hanya memiliki satu peran, yaitu admin, sehingga array roles adalah [admin]. Demikian pula, Anda dapat menggunakan GetUsersForRole() untuk mendapatkan pengguna yang termasuk dalam suatu peran. Nilai kembalian dari fungsi ini juga berupa sebuah array.

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

Anda dapat menggunakan HasRoleForUser() untuk mengonfirmasi apakah pengguna termasuk dalam peran tersebut. Dalam contoh ini, amber adalah anggota dari admin, sehingga nilai kembalian dari fungsi tersebut adalah true.

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

Anda dapat menggunakan DeletePermission() untuk menghapus sebuah izin.

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

Dan gunakan DeletePermissionForUser() untuk menghapus izin untuk seorang pengguna.

Casbin memiliki banyak API seperti ini. Metode pemanggilan dan nilai kembaliannya memiliki gaya yang sama dengan API di atas. Anda dapat menemukan API ini di dokumen berikutnya.