API Overview

На этой странице представлен обзор основных API Casbin. Для установки и концепций см. Get started и How it works.

Enforce API

Примеры ниже используют модель RBAC в model.conf и политики в policy.csv. Синтаксис модели описан в Model syntax. Примеры файлов:

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

NewEnforcer() загружает модель и политику из указанных путей (или из модели и адаптера). Он возвращает объект enforcer и ошибку. Адаптер файла по умолчанию используется, когда вы передаете два пути к файлам; вы можете заменить его на любой adapter.

enforcer.Enforce("alice", "data1", "read") проверяет, может ли Alice читать data1. Возвращает (true, nil) при разрешении и (false, nil) при отказе. С приведенной выше политикой этот вызов вернет true.

EnforceEx API

Чтобы увидеть, какая политика разрешила запрос, используйте EnforceEx():

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

reason — это соответствующая политика (например, [admin data1 read]). Amber имеет роль admin, поэтому политика p, admin, data1, read разрешает запрос.

Связанные API:

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

Enforce с одноразовым выражением matcher.
EnforceExWithMatcher(matcher, request) — Аналог EnforceEx с пользовательским матчером.
BatchEnforce(requests) — Проверка множества запросов за один вызов; возвращает срез булевых значений.

Полный набор методов см. в Management API и RBAC API.

Management API

Get API

Эти методы возвращают данные политики. Пример:

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)

GetAllSubjects() возвращает все субъекты, присутствующие в политике (в данном случае: admin, alice, bob). Вывод:

[admin alice bob]

Используйте GetAllNamedSubjects("p") для конкретного типа политики. Тот же принцип применим к Objects, Actions и Roles.

Другие геттеры:

GetPolicy() / GetFilteredPolicy(0, "alice") — Все правила или отфильтрованные по полю.
GetNamedPolicy("p") / GetFilteredNamedPolicy("p", 0, "bob") — То же самое для именованной политики.
GetGroupingPolicy() / GetFilteredGroupingPolicy(0, "alice") — Правила назначения ролей.
GetNamedGroupingPolicy("g") / GetFilteredNamedGroupingPolicy("g", 0, "alice") — То же самое для именованного группирования.

Add, delete, update 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

Та же схема add/remove/update/has существует для фильтрованных и именованных политик, а также для политик группирования. Для пакетных обновлений используйте множественные формы (например, AddPolicies, UpdatePolicies) со срезами в качестве аргументов.

Пример:

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

Методы 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) 

При использовании AddPolicies, если одно правило уже существует, весь вызов завершается ошибкой, и никакие правила не добавляются. При использовании AddPoliciesEx существующие правила пропускаются, а остальные добавляются. Пример:

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

Энфорсер также предоставляет вспомогательные функции RBAC (роли, пользователи, разрешения). Для настройки модели см. RBAC.

Загрузите модель и политику, как раньше:

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

Примеры вызовов RBAC:

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

GetRolesForUser("amber") возвращает [admin]. GetUsersForRole("admin") возвращает всех пользователей с этой ролью. 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("data2", "write") удаляет это разрешение у всех. DeletePermissionForUser("alice", "data1", "read") удаляет его только у Alice.

Полный список RBAC API см. в RBAC API.

Enforce API​

EnforceEx API​

Management API​

Get API​

Add, delete, update API​

AddEx API​

RBAC API​