Перейти до основного контенту

API Overview

Цей огляд показує лише, як користуватися API Casbin, і не пояснює, як Casbin встановлюється або як він працює. Ці навчальні матеріали ви можете знайти тут: Встановлення Casbin та Як працює Casbin. Отже, коли ви починаєте читати цей навчальний матеріал, ми припускаємо, що ви повністю встановили та імпортували Casbin у свій код.

API Enforce​

Почнемо з API Enforce в 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. Цей код використовує стандартний адаптер для завантаження моделі та політик, і, звичайно, ви можете досягти того ж результату, використовуючи адаптер стороннього виробника.

Код ok, err := enforcer.Enforce("alice", "data1", "read") використовується для підтвердження прав доступу. Якщо Аліса може отримати доступ до 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 надав багато API, подібних до цього. Ці API додають деякі додаткові функції до базових. До них відносяться:

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

    Ця функція використовує матчер.

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

    Це комбінація EnforceWithMatcher() та EnforceEx().

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

    Ця функція дозволяє виконувати список завдань і повертає масив.

Це простий випадок використання Casbin. Ви можете використовувати Casbin для запуску сервера авторизації, використовуючи ці API. Ми покажемо вам деякі інші типи API в наступних абзацах.

API управління​

Get API​

Ці API використовуються для отримання конкретних об'єктів у політиках. У цьому прикладі ми завантажуємо 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 у назві функції на бажану категорію.

Крім того, є більше гетерів, доступних для політик. Метод виклику та повернені значення подібні до згаданих вище.

  • 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

І використовуйте DeletePermissionForUser(), щоб видалити дозвіл для користувача.

Casbin має багато подібних API. Їхні методи виклику та повернені значення мають такий самий стиль, як і вищезазначені API. Ви можете знайти ці API в наступних документах.