Passer au contenu principal

Aperçu de l'API

Cette vue d'ensemble vous montre seulement comment utiliser les API Casbin et n'explique pas comment Casbin est installé et comment il fonctionne. Vous pouvez trouver ces tutoriels ici : installation de Casbin et fonctionnement de Casbin. Ainsi, lorsque vous commencez à lire ce tutoriel, nous supposons que vous avez complètement installé et importé Casbin dans votre code.

Forcer l'API​

Commençons par les APIs d'Enforce de Casbin. Nous allons charger un modèle RBAC à partir de model.conf, et charger les politiques de policy.csv. Vous pouvez apprendre la syntaxe du modèle ici, et nous ne vous en parlerons 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.

// charge les informations depuis les fichiers
enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy. sv")
if err != nil {
    log. atalf("erreur, détail : %s", err)
}
ok, err := enforcer.Enforce("alice", "data1", "read")

Ce code charge le modèle de contrôle d'accès et les règles à partir des fichiers locaux. La fonction casbin.NewEnforcer() retournera un responsable. Il reconnaîtra ses 2 paramètres en tant que chemin de fichier, et chargera les fichiers à partir de là. Des erreurs se sont produites dans le processus sont stockées dans err. Ce code a utilisé l'adaptateur par défaut pour charger le modèle et les règles. Et bien sûr, vous pouvez obtenir le même résultat en utilisant un adaptateur tiers.

Code ok, err := enforcer.Enforce("alice", "data1", "read") est de confirmer les autorisations d'accès. Si alice peut accéder aux données 1 avec la lecture de l'opération, la valeur retournée ok sera true, sinon elle sera false. Dans cet exemple, la valeur de ok est true.

API EnforceEx​

Sometimes you may wonder which policy allowed the request, so we prepared the function 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() retournera la chaîne de régulation exacte dans la raison de retour. Dans cet exemple, amber est un rôle de admin, donc la politique p, admin, data1, read a fait cette requête true. La sortie de ce code est dans le commentaire.

Casbin a préparé beaucoup d'API comme cela. Ces APIs ont ajouté quelques fonctions supplémentaires à la version de base. Ce sont :

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

    Avec un matcher.

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

    Une combinaison de EnforceWithMatcher() et EnforceEx().

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

    Faire une tâche de liste, retourne un tableau.

Il s'agit d'une utilisation simple de Casbin. Vous pouvez utiliser Casbin pour démarrer un serveur d'autorisation via ces API. Nous vous montrerons d'autres types d'API dans les paragraphes suivants.

API de gestion​

Get API​

Ces API sont utilisées pour obtenir des objets exacts dans les politiques. Cette fois, nous avons chargé un agent de sécurité comme le dernier exemple et nous avons obtenu quelque chose de cela.

Veuillez lire le 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)

Comme le dernier exemple, les 4 premières lignes ont chargé des informations nécessaires à partir de fichiers locaux. Nous n'en parlerons plus ici.

Code allSubjects := enforcer.GetAllSubjects() a récupéré tous les sujets dans le fichier de régulation et les a retournés sous forme de tableau. Puis nous avons imprimé ce tableau.

Normalement, la sortie du code devrait être :

[admin alice bob]

Vous pouvez également changer la fonction GetAllSubjects() en GetAllNamedSubjects() , o obtenir la liste des sujets qui apparaissent dans la police nommée courante.

De même, nous avons préparé les fonctions GetAll pour Objets, Actions, Rôles. La seule chose que vous devez faire est de changer le mot Sujet dans le nom de la fonction à ce que vous voulez si vous voulez accéder à ces fonctions.

En outre, nous avons plus d'atouts pour les politiques. La méthode d'appel et la valeur de retour sont similaires à celles 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 de la politique, les filtres de champs peuvent être 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") obtient toutes les règles d'autorisation dans la politique nommée, les filtres de champs peuvent être 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, les filtres de champs peuvent être 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.

Ajouter, supprimer, mettre à jour l'API​

Casbin a préparé de nombreuses API pour les politiques. Ces API vous permettent d'ajouter, de supprimer ou de modifier des politiques dynamiquement lors de l'exécution.

Ce code vous montre comment ajouter, supprimer et mettre à jour vos politiques, et vous dit comment confirmer qu'une politique existe :

// charge les informations depuis les fichiers
enforcer,err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
   fmt. rintf("Erreur, détails: %s\n", err)
}

// ajoute une politique, puis utilise HasPolicy() pour confirmer que
enforcer. ddPolicy("added_user", "data1", "read")
hasPolicy := enforcer.HasPolicy("added_user", "data1", "read")
fmt. rintln(hasPolicy) // true, nous avons ajouté que la politique avec succès

// supprime une politique, puis utilise HasPolicy() pour confirmer que
enforcer. emovePolicy("alice", "data1", "read")
hasPolicy = enforcer.HasPolicy("alice", "data1", "read")
fmt. rintln(hasPolicy) // false, nous avons supprimé cette politique avec succès

// mettre à jour une politique, puis utiliser HasPolicy() pour confirmer que
responsable. pdatePolicy([]string{"added_user", "data1", "read"}, []string{"added_user", "data1", "write"})
hasPolicy = enforcer.HasPolicy("added_user", "data1", "read")
fmt. rintln(hasPolicy) // false, la politique d'origine a expiré
hasPolicy = enforcer.HasPolicy("added_user", "data1", "write")
fmt.Println(hasPolicy) // true, la nouvelle politique est en cours d'utilisation

L'utilisation de ces quatre types d'API peut modifier vos règles. Comme cela, nous avons préparé les mêmes types d'APIs à FilteredPolicy, NamedPolicy, FilteredNamedPolicy, GroupingPolicy, NamedGroupingPolicy, FilteredGroupingPolicy, FilteredNamedGroupingPolicy. Pour les utiliser, vous devez seulement remplacer le mot Policy dans le nom de la fonction par les mots ci-dessus.

De plus, si vous changez les paramètres en tableaux, vous pouvez modifier par lots vos règles.

Par exemple, pour des fonctions comme ceci :

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

si nous changeons la Politique en Politiques, et modifions le paramètre à:

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

alors nous pouvons modifier en lot ces politiques.

Même opération utile également à GroupingPolicy, NamedGroupingPolicy.

AddEx API​

Casbin provides AddEx series APIs to help users add rules in batches.

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)

The difference between these methods and the methods without the Ex suffix is that if one of the rules already exists, they will continue to check the next rule instead of returning false directly.

For example: Compare AddPolicies and AddPoliciesEx

You can copy the code below into the test under casbin to run and observe.

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 des API pour vous permettre de modifier le modèle et les politiques du RBAC. Si vous êtes familier avec le RBAC, vous pouvez utiliser ces API facilement.

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 ce code 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)
}

alors, utilisez une instance d'Enforcer enforcer pour accéder à ces API.

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

GetRolesForUser() a retourné un tableau qui contenait tous les rôles contenus dans l'ambre. Dans cet exemple, l'ambre n'a qu'un seul rôle, donc le tableau rôles est [admin]. De même, vous pouvez utiliser GetUsersForRole() pour que les utilisateurs appartiennent au rôle. La valeur retournée par cette fonction est aussi un tableau.

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

Vous pouvez utiliser HasRoleForUser() pour confirmer si l'utilisateur appartient au rôle. Dans cet exemple, l'ambre est un membre de l'administrateur, donc la valeur retournée 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 utilisez DeletePermissionForUser() pour supprimer une permission pour un utilisateur.

Casbin a beaucoup d'API comme cela. Leurs méthodes d'appel et leurs valeurs de retour ont le même style que les API ci-dessus. Vous pouvez trouver ces API dans les prochains documents.