API Overview

Cette page donne un aperçu des principales API de Casbin. Pour la configuration et les concepts, consultez Get started et How it works.

Enforce API

Les exemples ci-dessous utilisent un modèle RBAC dans model.conf et des politiques dans policy.csv. La syntaxe du modèle est décrite dans Model syntax. Fichiers d'exemple :

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

Exemple d'utilisation :

// 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() charge le modèle et la politique depuis les chemins donnés (ou depuis un modèle et un adaptateur). Il retourne un enforceur et une erreur. L'adaptateur fichier par défaut est utilisé lorsque vous passez deux chemins de fichiers ; vous pouvez substituer n'importe quel adaptateur.

enforcer.Enforce("alice", "data1", "read") vérifie si Alice peut lire data1. Il retourne (true, nil) lorsqu'autorisé et (false, nil) lorsqu'il est refusé. Avec la politique ci-dessus, cet appel retourne true.

EnforceEx API

Pour voir quelle politique a autorisé une requête, utilisez EnforceEx() :

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

reason est la politique correspondante (par ex. [admin data1 read]). Amber a le rôle admin, donc la politique p, admin, data1, read autorise la requête.

API associées :

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

  Enforce avec une expression de matcher ponctuelle.

• EnforceExWithMatcher(matcher, request) — Comme EnforceEx avec un matcher personnalisé.

• BatchEnforce(requests) — Applique la politique à plusieurs requêtes à la fois ; renvoie un tableau de booléens.

Consultez Management API et RBAC API pour l'ensemble complet.

Management API

Get API

Ces méthodes renvoient les données de la politique. Exemple :

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() renvoie tous les sujets qui apparaissent dans la politique (ici : admin, alice, bob). Sortie :

[admin alice bob]

Utilisez GetAllNamedSubjects("p") pour un type de politique spécifique. Le même schéma s'applique aux Objects, Actions et Roles.

Autres getters :

• GetPolicy() / GetFilteredPolicy(0, "alice") — Toutes les règles ou filtrées par champ.
• GetNamedPolicy("p") / GetFilteredNamedPolicy("p", 0, "bob") — Idem pour une politique nommée.
• GetGroupingPolicy() / GetFilteredGroupingPolicy(0, "alice") — Règles d'affectation de rôles.
• GetNamedGroupingPolicy("g") / GetFilteredNamedGroupingPolicy("g", 0, "alice") — Idem pour le regroupement nommé.

Add, delete, update API

Vous pouvez modifier la politique à l'exécution. Exemple : ajouter, supprimer, mettre à jour et vérifier :

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

Le même schéma add/remove/update/has existe pour les politiques filtrées et nommées ainsi que pour les politiques de regroupement. Pour les mises à jour par lots, utilisez les formes plurielles (par ex. AddPolicies, UpdatePolicies) avec des arguments de type slice.

Exemple :

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

Changez Policy en Policies et modifiez les paramètres pour les opérations par lots :

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

Les opérations par lots s'appliquent également à GroupingPolicy et NamedGroupingPolicy.

AddEx API

Les méthodes AddEx ajoutent des règles par lots mais ignorent les règles qui existent déjà au lieu d'échouer :

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) 

Avec AddPolicies, si une règle existe déjà, l'appel entier échoue et aucune règle n'est ajoutée. Avec AddPoliciesEx, les règles existantes sont ignorées et les autres sont ajoutées. Exemple :

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

L'enforcer expose également des aides RBAC (rôles, utilisateurs, permissions). Pour la configuration du modèle, consultez RBAC.

Chargez le modèle et la politique comme précédemment :

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

Exemples d'appels RBAC :

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

GetRolesForUser("amber") renvoie [admin]. GetUsersForRole("admin") renvoie tous les utilisateurs ayant ce rôle. HasRoleForUser("amber", "admin") est true.

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

DeletePermission("data2", "write") supprime cette permission pour tout le monde. DeletePermissionForUser("alice", "data1", "read") la supprime uniquement pour Alice.

Pour la liste complète des APIs RBAC, consultez RBAC API.