API Overview

이 개요는 Casbin API의 사용 방법만을 보여주며, Casbin의 설치 방법이나 작동 방식에 대해서는 설명하지 않습니다. 해당 튜토리얼은 여기에서 찾을 수 있습니다: Casbin 설치 및 Casbin 작동 방식. 따라서, 이 튜토리얼을 읽기 시작할 때, Casbin을 완전히 설치하고 코드에 임포트했다고 가정합니다.

Enforce API

Casbin의 Enforce API부터 시작해봅시다. model.conf에서 RBAC 모델을 로드하고 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 변수에 저장됩니다. 이 코드는 기본 어댑터를 사용하여 모델과 정책을 로드하며, 당연히 제3자 어댑터를 사용하여 동일한 결과를 얻을 수 있습니다.

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의 간단한 사용 사례입니다. 이 API들을 사용하여 Casbin으로 인증 서버를 시작할 수 있습니다. 다음 단락에서 다른 유형의 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()로 변경하여 현재 명명된 정책에 나타나는 주체 목록을 얻을 수도 있습니다.

마찬가지로, 우리는 Objects, Actions, Roles에 대해 GetAll 함수를 준비했습니다. 이 함수들에 접근하려면, 함수 이름에서 Subject 단어를 원하는 카테고리로 바꾸기만 하면 됩니다.

또한, 정책에 대해 더 많은 getter가 사용 가능합니다. 호출 방법과 반환 값은 위에서 언급한 것과 유사합니다.

• 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들을 사용하면 정책을 동적으로 편집할 수 있습니다. 마찬가지로, FilteredPolicy, NamedPolicy, FilteredNamedPolicy, GroupingPolicy, NamedGroupingPolicy, FilteredGroupingPolicy, FilteredNamedGroupingPolicy에 대해 유사한 API를 제공하였습니다. 이들을 사용하려면 함수 이름에서 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은 사용자가 규칙을 일괄적으로 추가할 수 있도록 AddEx 시리즈의 API를 제공합니다.

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은 RBAC 모델과 정책을 수정할 수 있는 몇 가지 API를 제공합니다. RBAC에 익숙하다면 이 API들을 쉽게 사용할 수 있습니다.

여기서는 Casbin의 RBAC API 사용 방법만 보여주고 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들은 다음 문서에서 찾을 수 있습니다.