メインコンテンツにスキップ

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()関数はエンフォーサーを返します。 この関数は、2つのパラメータをファイルパスとして認識し、そこからファイルをロードします。 プロセス中に発生したエラーは変数errに格納されます。 このコードはデフォルトのアダプターを使用してモデルとポリシーをロードしますが、もちろん、サードパーティのアダプターを使用して同じ結果を得ることもできます。

ok, err := enforcer.Enforce("alice", "data1", "read")というコードは、アクセス権限を確認するために使用されます。 もしAliceがread操作で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​

取得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() に変更して、現在の名前付きポリシーに表示される主体のリストを取得することもできます。

同様に、Objects, Actions, Roles のための GetAll 関数を用意しています。 これらの関数にアクセスするには、関数名の 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") は指定されたフィールドフィルターを持つポリシー内のすべてのロール継承ルールを取得します。

追加、削除、更新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という1つの役割しか持っていないため、配列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は次のドキュメントで見つけることができます。