API Overview

이 페이지에서는 Casbin의 주요 API를 개관합니다. 설정 및 개념에 대해서는 Get started와 How it works를 참조하세요.

Enforce API

아래 예제는 model.conf의 RBAC 모델과 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()는 지정된 경로(또는 모델 및 adapter)에서 모델과 정책을 로드합니다. enforcer와 error를 반환합니다. 두 파일 경로를 전달하면 기본 파일 adapter가 사용되며, 임의의 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가 요청을 허용합니다.

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()는 정책에 등장하는 모든 subject를 반환합니다(여기서는 admin, alice, bob). 출력:

[admin alice bob]

특정 정책 유형에는 GetAllNamedSubjects("p")를 사용하세요. 동일한 패턴이 Objects, Actions, Roles에도 적용됩니다.

기타 getter:

GetPolicy() / GetFilteredPolicy(0, "alice") — 모든 규칙 또는 필드로 필터링된 규칙.
GetNamedPolicy("p") / GetFilteredNamedPolicy("p", 0, "bob") — named policy에 대해 동일하게 동작합니다.
GetGroupingPolicy() / GetFilteredGroupingPolicy(0, "alice") — 역할 할당 규칙.
GetNamedGroupingPolicy("g") / GetFilteredNamedGroupingPolicy("g", 0, "alice") — named grouping에 대해 동일하게 동작합니다.

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

필터링된 정책, named 정책, grouping 정책에서도 동일한 add/remove/update/has 패턴이 존재합니다. 일괄 업데이트에는 slice 인자를 사용하여 복수형 메서드(예: 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

enforcer는 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​