API Overview

ภาพรวมนี้แสดงเพียงวิธีการใช้งาน Casbin APIs และไม่ได้อธิบายวิธีการติดตั้ง Casbin หรือมันทำงานอย่างไร คุณสามารถหาบทแนะนำเหล่านั้นได้ที่นี่: การติดตั้ง Casbin และ Casbin ทำงานอย่างไร ดังนั้น เมื่อคุณเริ่มอ่านบทแนะนำนี้ เราถือว่าคุณได้ติดตั้งและนำเข้า Casbin เข้าไปในโค้ดของคุณเรียบร้อยแล้ว

Enforce API

เรามาเริ่มกันที่ Enforce APIs ของ Casbin เราจะโหลดโมเดล RBAC จาก model.conf และโหลดนโยบายจาก policy.csv คุณสามารถเรียนรู้เกี่ยวกับไวยากรณ์ของโมเดลได้ ที่นี่ และเราจะไม่พูดถึงมันในบทแนะนำนี้ เราถือว่าคุณสามารถเข้าใจไฟล์การตั้งค่าที่ให้ไว้ด้านล่างนี้:

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

หลังจากอ่านไฟล์การตั้งค่าแล้ว กรุณาอ่านโค้ดต่อไปนี้

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

โค้ดนี้โหลดโมเดลการควบคุมการเข้าถึงและนโยบายจากไฟล์ท้องถิ่น ฟังก์ชัน casbin.NewEnforcer() จะคืนค่า enforcer มันจะรู้จักพารามิเตอร์สองตัวเป็นทางเข้าไฟล์และโหลดไฟล์จากที่นั่น ข้อผิดพลาดที่เกิดขึ้นในกระบวนการจะถูกเก็บไว้ในตัวแปร err โค้ดนี้ใช้ adapter มาตรฐานในการโหลดโมเดลและนโยบาย และแน่นอน คุณสามารถทำผลลัพธ์เดียวกันได้โดยใช้ adapter ของบุคคลที่สาม

โค้ด ok, err := enforcer.Enforce("alice", "data1", "read") ใช้เพื่อยืนยันสิทธิ์การเข้าถึง หาก Alice สามารถเข้าถึง data1 ด้วยการดำเนินการอ่าน ค่าที่คืนค่าของ ok จะเป็น true; มิฉะนั้น จะเป็น false ในตัวอย่างนี้ ค่าของ ok เป็น true

EnforceEx API

บางครั้งคุณอาจสงสัยว่านโยบายใดที่อนุญาตคำขอ ดังนั้นเราจึงเตรียมฟังก์ชัน EnforceEx() ไว้ คุณสามารถใช้มันได้ดังนี้:

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

ฟังก์ชัน EnforceEx() จะคืนค่าสตริงนโยบายที่แน่นอนในค่าที่คืนค่า reason ในตัวอย่างนี้ amber เป็นบทบาท admin ดังนั้นนโยบาย p, admin, data1, read อนุญาตให้คำขอนี้เป็น true ผลลัพธ์ของโค้ดนี้อยู่ในคอมเมนต์

Casbin ได้จัดเตรียม APIs ที่คล้ายคลึงกันมากมาย APIs เหล่านี้เพิ่มฟังก์ชันพิเศษบางอย่างเข้ากับฟังก์ชันพื้นฐาน พวกมันรวมถึง:

ok, err := enforcer.EnforceWithMatcher(matcher, request)
ฟังก์ชันนี้ใช้ matcher
ok, reason, err := enforcer.EnforceExWithMatcher(matcher, request)
นี่เป็นการรวม EnforceWithMatcher() และ EnforceEx()
boolArray, err := enforcer.BatchEnforce(requests)
ฟังก์ชันนี้อนุญาตให้มีรายการงานและคืนค่าเป็นอาร์เรย์

นี่เป็นกรณีการใช้งานที่ง่ายของ Casbin คุณสามารถใช้ Casbin เพื่อเริ่มต้นเซิร์ฟเวอร์การอนุญาตโดยใช้ APIs เหล่านี้ เราจะแสดงให้คุณเห็น APIs ประเภทอื่นๆ ในย่อหน้าต่อไป

Management API

Get API

APIs เหล่านี้ใช้เพื่อดึงวัตถุที่เฉพาะเจาะจงในนโยบาย ในตัวอย่างนี้ เรากำลังโหลด enforcer และดึงบางสิ่งออกมาจากมัน

กรุณาดูโค้ดต่อไปนี้:

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)

คล้ายกับตัวอย่างก่อนหน้า สี่บรรทัดแรกใช้เพื่อโหลดข้อมูลที่จำเป็นจากไฟล์ท้องถิ่น เราจะไม่พูดถึงสิ่งนี้ต่อไปอีก

โค้ด allSubjects := enforcer.GetAllSubjects() ดึงทุกวัตถุที่เป็นหัวข้อในไฟล์นโยบายและคืนค่าเป็นอาร์เรย์ จากนั้นเราจะพิมพ์อาร์เรย์นั้นออกมา

โดยปกติ ผลลัพธ์ของโค้ดควรจะเป็น:

[admin alice bob]

คุณยังสามารถเปลี่ยนฟังก์ชัน GetAllSubjects() เป็น GetAllNamedSubjects() เพื่อรับรายการของหัวข้อที่ปรากฏในนโยบายที่มีชื่อปัจจุบัน

ในทำนองเดียวกัน เราได้เตรียม GetAll ฟังก์ชันสำหรับ Objects, Actions, Roles เพื่อเข้าถึงฟังก์ชันเหล่านี้ คุณเพียงแค่ต้องเปลี่ยนคำว่า Subject ในชื่อฟังก์ชันเป็นหมวดหมู่ที่ต้องการ

นอกจากนี้ยังมี getters อื่นๆ ที่มีให้สำหรับนโยบาย วิธีการเรียกและค่าที่คืนค่าคล้ายกับที่กล่าวถึงข้างต้น

policy = e.GetPolicy() ดึงกฎการอนุญาตทั้งหมดในนโยบาย
filteredPolicy := e.GetFilteredPolicy(0, "alice") ดึงกฎการอนุญาตทั้งหมดในนโยบายที่มีการกรองฟิลด์ที่ระบุ
namedPolicy := e.GetNamedPolicy("p") ดึงกฎการอนุญาตทั้งหมดในนโยบายที่มีชื่อ
filteredNamedPolicy = e.GetFilteredNamedPolicy("p", 0, "bob") ดึงกฎการอนุญาตทั้งหมดในนโยบายที่มีชื่อพร้อมการกรองฟิลด์ที่ระบุ
groupingPolicy := e.GetGroupingPolicy() ดึงกฎการสืบทอดบทบาททั้งหมดในนโยบาย
filteredGroupingPolicy := e.GetFilteredGroupingPolicy(0, "alice") ดึงกฎการสืบทอดบทบาททั้งหมดในนโยบายที่มีการกรองฟิลด์ที่ระบุ
namedGroupingPolicy := e.GetNamedGroupingPolicy("g") ดึงกฎการสืบทอดบทบาททั้งหมดในนโยบาย
namedGroupingPolicy := e.GetFilteredNamedGroupingPolicy("g", 0, "alice") ดึงกฎการสืบทอดบทบาททั้งหมดในนโยบายที่มีการกรองฟิลด์ที่ระบุ

เพิ่ม, ลบ, อัปเดต API

Casbin มี API หลากหลายสำหรับการเพิ่ม, ลบ หรือแก้ไขนโยบายได้แบบไดนามิกขณะทำงาน

โค้ดต่อไปนี้แสดงวิธีการเพิ่ม, ลบ และอัปเดตนโยบาย รวมถึงวิธีการตรวจสอบว่านโยบายนั้นมีอยู่หรือไม่:

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

โดยการใช้ API เหล่านี้ คุณสามารถแก้ไขนโยบายของคุณได้แบบไดนามิก ในทำนองเดียวกัน เราได้มี API ที่คล้ายกันสำหรับ FilteredPolicy, NamedPolicy, FilteredNamedPolicy, GroupingPolicy, NamedGroupingPolicy, FilteredGroupingPolicy, FilteredNamedGroupingPolicy ในการใช้งาน แค่เปลี่ยนคำว่า Policy ในชื่อฟังก์ชันเป็นหมวดหมู่ที่เหมาะสม

นอกจากนี้ โดยการเปลี่ยนพารามิเตอร์เป็นอาร์เรย์ คุณสามารถทำการแก้ไขนโยบายของคุณเป็นกลุ่มได้

ตัวอย่างเช่น พิจารณาฟังก์ชันเหล่านี้:

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

หากเราเปลี่ยน Policy เป็น Policies และแก้ไขพารามิเตอร์ดังนี้:

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

แล้วเราสามารถทำการแก้ไขนโยบายเหล่านี้เป็นกลุ่มได้

การดำเนินการเดียวกันนี้ยังสามารถใช้กับ GroupingPolicy, NamedGroupingPolicy

AddEx API

Casbin มีชุด API AddEx เพื่อช่วยผู้ใช้เพิ่มกฎเป็นกลุ่ม

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) 

ความแตกต่างระหว่างวิธีการเหล่านี้กับวิธีการที่ไม่มีคำต่อท้าย Ex คือ หากหนึ่งในกฎเหล่านั้นมีอยู่แล้ว พวกเขาจะดำเนินการตรวจสอบกฎถัดไปแทนที่จะคืนค่าเป็น false ทันที

ตัวอย่างเช่น มาเปรียบเทียบ AddPolicies และ AddPoliciesEx

คุณสามารถรันและสังเกตโค้ดต่อไปนี้โดยการคัดลอกเข้าไปในการทดสอบภายใต้ 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 มี API บางอย่างสำหรับคุณในการแก้ไขโมเดล RBAC และนโยบาย หากคุณคุ้นเคยกับ RBAC คุณสามารถใช้ API เหล่านี้ได้อย่างง่ายดาย

ที่นี่ เราเพียงแค่แสดงวิธีการใช้ API RBAC ของ Casbin และไม่ได้พูดถึง RBAC เอง คุณสามารถดูรายละเอียดเพิ่มเติม ที่นี่

เราใช้โค้ดต่อไปนี้เพื่อโหลดโมเดลและนโยบาย เหมือนกับที่เคยทำมาก่อน

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

จากนั้น เราสามารถใช้ตัวอย่างของ Enforcer enforcer เพื่อเข้าถึง API เหล่านี้

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

GetRolesForUser() คืนค่าอาร์เรย์ที่มีบทบาททั้งหมดที่ amber มี ในตัวอย่างนี้ amber มีบทบาทเพียงหนึ่งบทบาท ซึ่งคือ admin ดังนั้นอาร์เรย์ roles คือ [admin] ในทำนองเดียวกัน คุณสามารถใช้ GetUsersForRole() เพื่อดึงผู้ใช้ที่อยู่ในบทบาท ค่าที่คืนค่าของฟังก์ชันนี้ก็เป็นอาร์เรย์เช่นกัน

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

คุณสามารถใช้ HasRoleForUser() เพื่อยืนยันว่าผู้ใช้นั้นอยู่ในบทบาทหรือไม่ ในตัวอย่างนี้ amber เป็นสมาชิกของ admin ดังนั้นค่าที่คืนค่าของฟังก์ชันคือ true

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

คุณสามารถใช้ DeletePermission() เพื่อลบสิทธิ์

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