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

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") используется для подтверждения прав доступа. Если 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 предоставил множество 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") извлекает все правила наследования ролей в политике с указанными фильтрами полей.

Add, Delete, Update 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.

API AddEx​

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 есть только одна роль, которая является администратором, поэтому массив 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. You can find these APIs in the next documents.