Passer au contenu principal

API Overview

Cet aperçu vous montre seulement comment utiliser les API Casbin et n'explique pas comment Casbin est installé ou comment il fonctionne. Vous pouvez trouver ces tutoriels ici : Installation de Casbin et Comment fonctionne Casbin. Donc, lorsque vous commencez à lire ce tutoriel, nous supposons que vous avez entièrement installé et importé Casbin dans votre code.

API Enforce​

Commençons par les API Enforce de Casbin. Nous chargerons un modèle RBAC à partir de model.conf et chargerons les politiques à partir de policy.csv. Vous pouvez en savoir plus sur la syntaxe du modèle ici, et nous n'en discuterons pas dans ce tutoriel. Nous supposons que vous pouvez comprendre les fichiers de configuration donnés ci-dessous :

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

Après avoir lu les fichiers de configuration, veuillez lire le code suivant.

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

Ce code charge le modèle de contrôle d'accès et les politiques à partir de fichiers locaux. La fonction casbin.NewEnforcer() renverra un exécuteur. Il reconnaîtra ses deux paramètres comme des chemins de fichiers et chargera les fichiers à partir de là. Les erreurs survenues dans le processus sont stockées dans la variable err. Ce code utilise l'adaptateur par défaut pour charger le modèle et les politiques, et bien sûr, vous pouvez obtenir le même résultat en utilisant un adaptateur tiers.

Le code ok, err := enforcer.Enforce("alice", "data1", "read") est utilisé pour confirmer les permissions d'accès. Si Alice peut accéder à data1 avec l'opération de lecture, la valeur renvoyée de ok sera true ; sinon, elle sera false. Dans cet exemple, la valeur de ok est true.

EnforceEx API​

Parfois, vous pouvez vous demander quelle politique a permis la demande, donc nous avons préparé la fonction EnforceEx(). Vous pouvez l'utiliser comme ceci :

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

La fonction EnforceEx() renverra la chaîne de politique exacte dans la valeur de retour reason. Dans cet exemple, amber est un rôle admin, donc la politique p, admin, data1, read a permis à cette demande d'être true. La sortie de ce code est dans le commentaire.

Casbin a fourni de nombreuses API similaires à celle-ci. Ces API ajoutent quelques fonctions supplémentaires à celles de base. Ils incluent :

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

    Cette fonction utilise un matcher.

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

    C'est une combinaison de EnforceWithMatcher() et EnforceEx().

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

    Cette fonction permet une liste de tâches et renvoie un tableau.

Ceci est un cas d'utilisation simple de Casbin. Vous pouvez utiliser Casbin pour démarrer un serveur d'autorisation en utilisant ces API. Nous vous montrerons d'autres types d'API dans les paragraphes suivants.

API de gestion​

API Get​

Ces API sont utilisées pour récupérer des objets spécifiques dans les politiques. Dans cet exemple, nous chargeons un exécuteur et récupérons quelque chose à partir de celui-ci.

Veuillez jeter un œil au code suivant :

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)

Semblable à l'exemple précédent, les quatre premières lignes sont utilisées pour charger les informations nécessaires à partir des fichiers locaux. Nous n'en discuterons pas plus ici.

Le code allSubjects := enforcer.GetAllSubjects() récupère tous les sujets dans le fichier de politique et les renvoie sous forme de tableau. Nous imprimons ensuite ce tableau.

En général, la sortie du code devrait être :

[admin alice bob]

Vous pouvez également changer la fonction GetAllSubjects() en GetAllNamedSubjects() pour obtenir la liste des sujets qui apparaissent dans la politique nommée actuelle.

De même, nous avons préparé des fonctions GetAll pour Objects, Actions, Roles. Pour accéder à ces fonctions, vous devez simplement remplacer le mot Subject dans le nom de la fonction par la catégorie souhaitée.

De plus, il y a plus de getters disponibles pour les politiques. La méthode d'appel et les valeurs de retour sont similaires à celles mentionnées ci-dessus.

  • policy = e.GetPolicy() récupère toutes les règles d'autorisation dans la politique.
  • filteredPolicy := e.GetFilteredPolicy(0, "alice") récupère toutes les règles d'autorisation dans la politique avec des filtres de champ spécifiés.
  • namedPolicy := e.GetNamedPolicy("p") récupère toutes les règles d'autorisation dans la politique nommée.
  • filteredNamedPolicy = e.GetFilteredNamedPolicy("p", 0, "bob") récupère toutes les règles d'autorisation dans la politique nommée avec des filtres de champ spécifiés.
  • groupingPolicy := e.GetGroupingPolicy() récupère toutes les règles d'héritage de rôle dans la politique.
  • filteredGroupingPolicy := e.GetFilteredGroupingPolicy(0, "alice") récupère toutes les règles d'héritage de rôle dans la politique avec des filtres de champ spécifiés.
  • namedGroupingPolicy := e.GetNamedGroupingPolicy("g") récupère toutes les règles d'héritage de rôle dans la politique.
  • namedGroupingPolicy := e.GetFilteredNamedGroupingPolicy("g", 0, "alice") récupère toutes les règles d'héritage de rôle dans la politique avec des filtres de champ spécifiés.

Ajouter, Supprimer, Mettre à jour l'API​

Casbin propose une variété d'API pour ajouter, supprimer ou modifier dynamiquement les politiques en temps réel.

Le code suivant montre comment ajouter, supprimer et mettre à jour des politiques, ainsi que comment vérifier si une politique existe :

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

En utilisant ces API, vous pouvez modifier vos politiques de manière dynamique. De même, nous avons fourni des API similaires pour FilteredPolicy, NamedPolicy, FilteredNamedPolicy, GroupingPolicy, NamedGroupingPolicy, FilteredGroupingPolicy, FilteredNamedGroupingPolicy. Pour les utiliser, remplacez simplement le mot Policy dans le nom de la fonction par la catégorie appropriée.

De plus, en changeant les paramètres en tableaux, vous pouvez effectuer l'édition en lot de vos politiques.

Par exemple, considérez des fonctions comme celle-ci :

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

Si nous changeons Policy en Policies et modifions les paramètres comme suit :

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

alors nous pouvons effectuer l'édition en lot de ces politiques.

Les mêmes opérations peuvent également être appliquées à GroupingPolicy, NamedGroupingPolicy.

API AddEx​

Casbin fournit la série d'API AddEx pour aider les utilisateurs à ajouter des règles par lots.

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)

La différence entre ces méthodes et les méthodes sans le suffixe Ex est que si l'une des règles existe déjà, elles continueront à vérifier la règle suivante au lieu de renvoyer false immédiatement.

Par exemple, comparons AddPolicies et AddPoliciesEx.

Vous pouvez exécuter et observer le code suivant en le copiant dans le test sous 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 fournit quelques API pour vous permettre de modifier le modèle RBAC et les politiques. Si vous êtes familier avec RBAC, vous pouvez facilement utiliser ces API.

Ici, nous vous montrons seulement comment utiliser les API RBAC de Casbin et nous ne parlerons pas de RBAC lui-même. Vous pouvez obtenir plus de détails ici.

Nous utilisons le code suivant pour charger le modèle et les politiques, comme avant.

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

Ensuite, nous pouvons utiliser une instance de l'Enforcer enforcer pour accéder à ces API.

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

GetRolesForUser() renvoie un tableau qui contient tous les rôles qu'amber a. Dans cet exemple, amber n'a qu'un seul rôle, qui est admin, donc le tableau roles est [admin]. De même, vous pouvez utiliser GetUsersForRole() pour obtenir les utilisateurs qui appartiennent à un rôle. La valeur de retour de cette fonction est également un tableau.

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

Vous pouvez utiliser HasRoleForUser() pour confirmer si l'utilisateur appartient au rôle. Dans cet exemple, amber est membre de admin, donc la valeur de retour de la fonction est true.

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

Vous pouvez utiliser DeletePermission() pour supprimer une permission.

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

Et utiliser DeletePermissionForUser() pour supprimer une permission pour un utilisateur.

Casbin a de nombreuses API comme celle-ci. Leurs méthodes d'appel et leurs valeurs de retour ont le même style que les API ci-dessus. You can find these APIs in the next documents.