API Overview

Diese Übersicht zeigt Ihnen nur, wie Sie die Casbin APIs verwenden und erklärt nicht, wie Casbin installiert wird oder wie es funktioniert. Diese Tutorials finden Sie hier: Installation von Casbin und Wie Casbin funktioniert. Wenn Sie also mit der Lektüre dieses Tutorials beginnen, gehen wir davon aus, dass Sie Casbin vollständig installiert und in Ihren Code importiert haben.

Enforce API

Beginnen wir mit den Enforce APIs von Casbin. Wir werden ein RBAC-Modell aus model.conf laden und Richtlinien aus policy.csv laden. Sie können die Syntax des Modells hier kennenlernen, und wir werden sie in diesem Tutorial nicht diskutieren. Wir gehen davon aus, dass Sie die unten gegebenen Konfigurationsdateien verstehen können:

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

Nachdem Sie die Konfigurationsdateien gelesen haben, lesen Sie bitte den folgenden Code.

// 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")

Dieser Code lädt das Zugriffskontrollmodell und die Richtlinien aus lokalen Dateien. Die Funktion casbin.NewEnforcer() gibt einen Durchsetzer zurück. Es erkennt seine beiden Parameter als Dateipfade und lädt die Dateien von dort. Fehler, die im Prozess aufgetreten sind, werden in der Variablen err gespeichert. Dieser Code verwendet den Standardadapter zum Laden des Modells und der Richtlinien, und natürlich können Sie das gleiche Ergebnis mit einem Drittanbieter-Adapter erzielen.

Der Code ok, err := enforcer.Enforce("alice", "data1", "read") wird verwendet, um Zugriffsberechtigungen zu bestätigen. Wenn Alice auf data1 mit der Leseoperation zugreifen kann, wird der zurückgegebene Wert von ok true sein; andernfalls wird er false sein. In diesem Beispiel ist der Wert von ok true.

EnforceEx API

Manchmal fragen Sie sich vielleicht, welche Richtlinie die Anfrage erlaubt hat, daher haben wir die Funktion EnforceEx() vorbereitet. Sie können es so verwenden:

ok, reason, err := enforcer.EnforceEx("amber", "data1", "read")
fmt.Println(ok, reason) // true [admin data1 read]

Die Funktion EnforceEx() gibt den genauen Richtlinienstring im Rückgabewert reason zurück. In diesem Beispiel ist amber eine admin-Rolle, daher hat die Richtlinie p, admin, data1, read diese Anfrage auf true zugelassen. Die Ausgabe dieses Codes steht im Kommentar.

Casbin hat viele APIs bereitgestellt, die dieser ähnlich sind. Diese APIs fügen den grundlegenden Funktionen einige zusätzliche Funktionen hinzu. Dazu gehören:

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

  Diese Funktion verwendet einen Matcher.

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

  Dies ist eine Kombination aus EnforceWithMatcher() und EnforceEx().

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

  Diese Funktion ermöglicht eine Liste von Jobs und gibt ein Array zurück.

Dies ist ein einfacher Anwendungsfall von Casbin. Sie können Casbin verwenden, um einen Autorisierungsserver mit diesen APIs zu starten. Wir werden Ihnen einige andere Arten von APIs in den folgenden Absätzen zeigen.

Management API

Get API

Diese APIs werden verwendet, um spezifische Objekte in Richtlinien abzurufen. In diesem Beispiel laden wir einen Durchsetzer und holen etwas davon ab.

Bitte schauen Sie sich den folgenden Code an:

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)

Ähnlich wie im vorherigen Beispiel werden die ersten vier Zeilen verwendet, um notwendige Informationen aus lokalen Dateien zu laden. Wir werden das hier nicht weiter diskutieren.

Der Code allSubjects := enforcer.GetAllSubjects() ruft alle Subjekte in der Richtliniendatei ab und gibt sie als Array zurück. Wir drucken dann dieses Array.

Typischerweise sollte die Ausgabe des Codes folgendermaßen aussehen:

[admin alice bob]

Sie können auch die Funktion GetAllSubjects() in GetAllNamedSubjects() ändern, um die Liste der Subjekte zu erhalten, die in der aktuellen benannten Richtlinie erscheinen.

Ebenso haben wir GetAll Funktionen für Objects, Actions, Roles vorbereitet. Um auf diese Funktionen zuzugreifen, müssen Sie einfach das Wort Subject im Funktionsnamen durch die gewünschte Kategorie ersetzen.

Zusätzlich gibt es weitere Getter für Richtlinien. Die Methode des Aufrufens und die Rückgabewerte ähneln den oben genannten.

• policy = e.GetPolicy() ruft alle Autorisierungsregeln in der Richtlinie ab.
• filteredPolicy := e.GetFilteredPolicy(0, "alice") ruft alle Autorisierungsregeln in der Richtlinie mit spezifizierten Feldfiltern ab.
• namedPolicy := e.GetNamedPolicy("p") ruft alle Autorisierungsregeln in der benannten Richtlinie ab.
• filteredNamedPolicy = e.GetFilteredNamedPolicy("p", 0, "bob") ruft alle Autorisierungsregeln in der benannten Richtlinie mit spezifizierten Feldfiltern ab.
• groupingPolicy := e.GetGroupingPolicy() ruft alle Rollenvererbungsregeln in der Richtlinie ab.
• filteredGroupingPolicy := e.GetFilteredGroupingPolicy(0, "alice") ruft alle Rollenvererbungsregeln in der Richtlinie mit spezifizierten Feldfiltern ab.
• namedGroupingPolicy := e.GetNamedGroupingPolicy("g") ruft alle Rollenvererbungsregeln in der Richtlinie ab.
• namedGroupingPolicy := e.GetFilteredNamedGroupingPolicy("g", 0, "alice") ruft alle Rollenvererbungsregeln in der Richtlinie mit spezifizierten Feldfiltern ab.

Add, Delete, Update API

Casbin bietet eine Vielzahl von APIs zum dynamischen Hinzufügen, Löschen oder Ändern von Richtlinien zur Laufzeit.

Der folgende Code zeigt, wie man Richtlinien hinzufügt, entfernt und aktualisiert, sowie wie man überprüft, ob eine Richtlinie existiert:

// 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

Mit diesen APIs können Sie Ihre Richtlinien dynamisch bearbeiten. Ebenso haben wir ähnliche APIs für FilteredPolicy, NamedPolicy, FilteredNamedPolicy, GroupingPolicy, NamedGroupingPolicy, FilteredGroupingPolicy, FilteredNamedGroupingPolicy bereitgestellt. Um sie zu verwenden, ersetzen Sie einfach das Wort Policy im Funktionsnamen durch die entsprechende Kategorie.

Darüber hinaus können Sie durch Ändern der Parameter in Arrays eine Stapelbearbeitung Ihrer Richtlinien durchführen.

Betrachten Sie zum Beispiel Funktionen wie diese:

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

Wenn wir Policy zu Policies ändern und die Parameter wie folgt ändern:

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

dann können wir eine Stapelbearbeitung dieser Richtlinien durchführen.

Die gleichen Operationen können auch auf GroupingPolicy, NamedGroupingPolicy angewendet werden.

AddEx API

Casbin bietet die AddEx-Serie von APIs an, um Benutzern zu helfen, Regeln in Chargen hinzuzufügen.

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) 

Der Unterschied zwischen diesen Methoden und den Methoden ohne das Ex-Suffix besteht darin, dass sie, wenn eine der Regeln bereits existiert, die nächste Regel überprüfen, anstatt sofort false zurückzugeben.

Zum Beispiel vergleichen wir AddPolicies und AddPoliciesEx.

Sie können den folgenden Code ausführen und beobachten, indem Sie ihn in den Test unter Casbin kopieren.

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 bietet einige APIs, mit denen Sie das RBAC-Modell und die Richtlinien ändern können. Wenn Sie mit RBAC vertraut sind, können Sie diese APIs leicht verwenden.

Hier zeigen wir Ihnen nur, wie Sie die RBAC-APIs von Casbin verwenden und sprechen nicht über RBAC selbst. Sie können mehr Details hier erhalten.

Wir verwenden den folgenden Code, um das Modell und die Richtlinien zu laden, genau wie zuvor.

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

Dann können wir eine Instanz des Enforcers enforcer verwenden, um auf diese APIs zuzugreifen.

roles, err := enforcer.GetRolesForUser("amber")
fmt.Println(roles) // [admin]
users, err := enforcer.GetUsersForRole("admin")
fmt.Println(users) // [amber abc]

GetRolesForUser() gibt ein Array zurück, das alle Rollen enthält, die Amber hat. In diesem Beispiel hat Amber nur eine Rolle, die Admin ist, daher ist das Array roles [admin]. Ebenso können Sie GetUsersForRole() verwenden, um die Benutzer zu erhalten, die zu einer Rolle gehören. Der Rückgabewert dieser Funktion ist ebenfalls ein Array.

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

Sie können HasRoleForUser() verwenden, um zu bestätigen, ob der Benutzer zur Rolle gehört. In diesem Beispiel ist Amber ein Mitglied von Admin, daher ist der Rückgabewert der Funktion true.

fmt.Println(enforcer.Enforce("bob", "data2", "write")) // true
enforcer.DeletePermission("data2", "write")
fmt.Println(enforcer.Enforce("bob", "data2", "write")) // false

Sie können DeletePermission() verwenden, um eine Berechtigung zu löschen.

fmt.Println(enforcer.Enforce("alice", "data1", "read")) // true
enforcer.DeletePermissionForUser("alice", "data1", "read")
fmt.Println(enforcer.Enforce("alice", "data1", "read")) // false

Und verwenden Sie DeletePermissionForUser(), um eine Berechtigung für einen Benutzer zu löschen.

Casbin hat viele APIs wie diese. Ihre Aufrufmethoden und Rückgabewerte haben den gleichen Stil wie die oben genannten APIs. You can find these APIs in the next documents.