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

Обзор API

Этот обзор показывает только как использовать Casbin API и не объясняет, как установлен Casbin и как он работает. Вы можете найти эти уроки здесь: установка Casbin и как работает Casbin. Итак, когда вы начинаете читать это руководство, мы предполагаем, что вы полностью установили и импортировали Casbin в ваш код.

Принудительный API​

Начнем использовать API Касбина. Мы загрузим модель 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

После прочтения конфигурационных файлов, пожалуйста, прочтите следующий код.

// загружаем информацию из файлов
enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy. sv")
if err != nil {
    log. atalf("ошибка, деталь: %s", ошибка)
}
ok, err := enforcer.Enforce("алицей", "данные1", "чтение")

Этот код загружает модель контроля доступа и политики из локальных файлов. Функция casbin.NewEnforcer() возвращает форвард. Он распознает 2 параметра как пути к файлам и загрузит файлы отсюда. Ошибки в процессе хранятся в err. Этот код использовал адаптер по умолчанию для загрузки модели и политики. И конечно же, можно получить тот же результат, используя сторонний адаптер.

Код ak, err := enforcer.Enforce("alice", "data1", "read") - это подтверждение прав доступа. Если alice может получить доступ к данным с помощью операции чтения, возвращаемое значение ок будет true, в противном случае он будет ложным. В этом примере значение ок равно истина.

EnforceEx API​

Иногда вы можете задаться вопросом, какая политика разрешала запрос, поэтому мы подготовили функцию EnforceEx(). Вы можете использовать его следующим образом:

ok, причина, err := enforcer.EnforceEx("amber", "data1", "read")
fmt.Println(ok, reason) // true [admin data1 read]

функция EnforceEx() возвращает точную строку политики в значение Причина. В этом примере янтарь является ролью admin, так что политика p, admin, data1, прочитанная сделала этот запрос истинным. Выход из этого кода находится в комментарии.

Касбин подготовил много API, как это. Эти API добавили некоторые дополнительные функции на основном. К ним относятся:

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

    С игроком.

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

    Комбинация EnforceWithMatcher() и EnforceEx().

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

    Сделайте задачу списка, возвращает массив.

Это простое использование Касбина. Вы можете использовать Casbin для запуска сервера авторизации через эти API. В следующих параграфах мы покажем вам некоторые другие типы API.

API управления​

Get API​

Эти 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)

Так же, как и в последнем примере, первые 4 строки загрузили некоторую необходимую информацию из локальных файлов. Мы больше не будем об этом говорить.

Код allSubjects := enforcer.GetAllSubjects() получил все темы в файле политики и возвратил их в виде массива. Затем мы распечатали этот массив.

Обычно вывод кода должен быть:

[admin alice bob]

Вы также можете изменить функцию GetAllSubjects() на GetAllNamedSubjects() , o получить список тем, которые отображаются в текущей именованной политике.

Точно так же мы подготовили GetAll функции для Объектов, Действий, Ролей. Единственное, что вам нужно сделать, это изменить слово Тема в названии функции на то, что вы хотите, если вы хотите получить доступ к этим функциям.

Кроме того, у нас есть больше получателей по политике. Метод вызова и значение возврата похожи на метод выше.

  • политика = 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​

Касбин подготовил много API для политики. Эти API позволяют динамически добавлять, удалять или редактировать политики во время работы.

Этот код показывает, как добавлять, удалять и обновлять свои политики, и рассказал вам, как подтвердить, что существует политика:

// загружаем информацию из файлов
enforcer,err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
   fmt. rintf("Error, details: %s\n", err)
}

// добавьте политику, затем используйте HasPolicy() для подтверждения того, что
enforcer. ddPolicy("added_user", "data1", "read")
hasPolicy := enforcer.HasPolicy("added_user", "data1", "read")
fmt. rintln(hasPolicy) // true, we added that policy successfully

// remove the policy, then use HasPolicy() to confirm that
enforcer. emovePolicy("alice", "data1", "read")
hasPolicy = enforcer.HasPolicy("alice", "data1", "read")
fmt. rintln(hasPolicy) // false, мы удалили эту политику успешно

// обновляем политику, затем используйте HasPolicy() для подтверждения того, что
enforcer. pdatePolicy([]string{"added_user", "data1", "read"}, []string{"added_user", "data1", "write"})
hasPolicy = enforcer.HasPolicy("added_user", "data1", "read")
fmt. rintln(hasPolicy) // false, политика происхождения пропущена
hasPolicy = enforcer.HasPolicy("added_user", "data1", "write")
fmt.Println(hasPolicy) // true, the new policy is in use

Используя эти четыре типа API, вы можете редактировать ваши политики. Подобно этим, мы подготовили одинаковые типы API FilteredPolicy, NamedPolicy, FilteredNamedPolicy, GroupingPolicy, NamedGroupingPolicy, FilteredGroupingPolicy, FilteredNamedGroupingPolicy. Для их использования необходимо заменить слово Политику в названии функции на слова выше.

Кроме того, если вы измените параметры на массивы, вы можете пакетное редактирование политик.

Например, для таких функций:

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

если мы изменим Политику на Политикии отредактируем параметр:

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

мы можем отредактировать эти политики.

Одинаковые операции также полезны GroupingPolicy, NamedGroupingPolicy.

AddEx API​

Casbin provides AddEx series APIs to help users add rules in batches.

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)

The difference between these methods and the methods without the Ex suffix is that if one of the rules already exists, they will continue to check the next rule instead of returning false directly.

For example: Compare AddPolicies and AddPoliciesEx

You can copy the code below into the test under casbin to run and observe.

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​

Касбин предоставляет API для изменения модели и политики RBAC. Если вы знакомы с RBAC, вы можете легко использовать эти API.

Здесь мы покажем вам, как использовать RBAC API в Casbin и не будем говорить о самом RBAC. Вы можете получить более подробную информацию здесь.

Мы используем этот код для загрузки модели и политики, как раньше.

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

затем используйте экземпляр Enforcer для доступа к этим API.

roles, err := enforcer.GetRolesForUser("amber")
fmt.Println(roles) // [admin]
пользователей, err := enforcer.GetUsersForRole("admin")
fmt.Println(users) // [amber abc]

GetRolesForUser() возвращает массив, содержащий все роли, содержащие янтарь. В этом примере у янтарь имеет только одну роль администратора, поэтому массив ролей является [admin]. Кроме того, вы можете использовать GetUsersForRole() для присвоения роли пользователям. Возвращаемое значение этой функции также является массивом.

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

Вы можете использовать HasRoleForUser() для подтверждения принадлежности пользователя к этой роли. В этом примере янтарь является членом админа, поэтому возвратное значение функции истинно.

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() для удаления разрешения пользователя.

Касбин имеет много API, как это. Методы вызова и значения возврата имеют тот же стиль, что и приведенные выше API. Вы можете найти эти API в следующих документах.