API Overview
Questa panoramica mostra solo come utilizzare le API di Casbin e non spiega come Casbin viene installato o come funziona. Puoi trovare quei tutorial qui: Installazione di Casbin e Come Funziona Casbin. Quindi, quando inizi a leggere questo tutorial, supponiamo che tu abbia installato e importato completamente Casbin nel tuo codice.
Applicazione delle API
Iniziamo con le API di Enforce di Casbin. Caricheremo un modello RBAC dal file model.conf e caricheremo le politiche dal file policy.csv. Puoi imparare la sintassi del Modello qui, e non ne parleremo in questo tutorial. Supponiamo che tu possa capire i file di configurazione forniti di seguito:
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
Dopo aver letto i file di configurazione, leggi il seguente codice.
// 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")
Questo codice carica il modello di controllo degli accessi e le politiche dai file locali. La funzione casbin.NewEnforcer() restituirà un enforcer. Riconoscerà i suoi due parametri come percorsi di file e caricherà i file da lì. Gli errori che si verificano nel processo sono memorizzati nella variabile err. Questo codice utilizza l'adattatore predefinito per caricare il modello e le politiche, e ovviamente, puoi ottenere lo stesso risultato utilizzando un adattatore di terze parti.
Il codice ok, err := enforcer.Enforce("alice", "data1", "read") viene utilizzato per confermare le autorizzazioni di accesso. Se Alice può accedere a data1 con l'operazione di lettura, il valore restituito di ok sarà true; in caso contrario, sarà false. In questo esempio, il valore di ok è true.
EnforceEx API
A volte potresti chiederti quale politica abbia permesso la richiesta, quindi abbiamo preparato la funzione EnforceEx(). Puoi utilizzarla in questo modo:
ok, reason, err := enforcer.EnforceEx("amber", "data1", "read")
fmt.Println(ok, reason) // true [admin data1 read]
La funzione EnforceEx() restituirà la stringa esatta della politica nel valore di ritorno reason. In questo esempio, amber ha il ruolo di admin, quindi la policy p, admin, data1, read ha permesso che questa richiesta fosse true. L'output di questo codice è nel commento.
Casbin ha fornito molte API simili a questa. Queste API aggiungono alcune funzioni extra rispetto a quelle di base. Esse includono:
ok, err := enforcer.EnforceWithMatcher(matcher, request)Questa funzione utilizza un matcher.
ok, reason, err := enforcer.EnforceExWithMatcher(matcher, request)Questa è una combinazione di
EnforceWithMatcher()eEnforceEx().boolArray, err := enforcer.BatchEnforce(requests)Questa funzione permette di avere una lista di lavori e restituisce un array.
Questo è un caso d'uso semplice di Casbin. Puoi utilizzare Casbin per avviare un server di autorizzazione utilizzando queste API. Ti mostreremo alcuni altri tipi di API nei paragrafi seguenti.
API di Gestione
API di Recupero
Queste API vengono utilizzate per recuperare oggetti specifici nelle politiche. In questo esempio, stiamo caricando un enforcer e recuperando qualcosa da esso.
Dai un'occhiata al seguente codice:
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)
Simile all'esempio precedente, le prime quattro righe vengono utilizzate per caricare le informazioni necessarie dai file locali. Non discuteremo ulteriormente quello qui.
Il codice allSubjects := enforcer.GetAllSubjects() recupera tutti i soggetti nel file di policy e li restituisce come un array. Quindi stampiamo quell'array.
Tipicamente, l'output del codice dovrebbe essere:
[admin alice bob]
Puoi anche cambiare la funzione GetAllSubjects() in GetAllNamedSubjects() per ottenere la lista dei soggetti che compaiono nella policy nominata corrente.
Allo stesso modo, abbiamo preparato funzioni GetAll per Objects, Actions, Roles. Per accedere a queste funzioni, devi semplicemente sostituire la parola Subject nel nome della funzione con la categoria desiderata.
Inoltre, ci sono più getter disponibili per le policy. Il metodo di chiamata e i valori di ritorno sono simili a quelli menzionati sopra.
policy = e.GetPolicy()recupera tutte le regole di autorizzazione nella policy.filteredPolicy := e.GetFilteredPolicy(0, "alice")recupera tutte le regole di autorizzazione nella policy con filtri di campo specificati.namedPolicy := e.GetNamedPolicy("p")recupera tutte le regole di autorizzazione nella policy nominata.filteredNamedPolicy = e.GetFilteredNamedPolicy("p", 0, "bob")recupera tutte le regole di autorizzazione nella policy nominata con filtri di campo specificati.groupingPolicy := e.GetGroupingPolicy()recupera tutte le regole di ereditarietà del ruolo nella policy.filteredGroupingPolicy := e.GetFilteredGroupingPolicy(0, "alice")recupera tutte le regole di ereditarietà del ruolo nella policy con filtri di campo specificati.namedGroupingPolicy := e.GetNamedGroupingPolicy("g")recupera tutte le regole di ereditarietà del ruolo nella policy.namedGroupingPolicy := e.GetFilteredNamedGroupingPolicy("g", 0, "alice")recupera tutte le regole di ereditarietà del ruolo nella policy con filtri di campo specificati.
Aggiungi, Elimina, Aggiorna API
Casbin fornisce una varietà di API per aggiungere, eliminare o modificare dinamicamente le policy in fase di runtime.
Il seguente codice dimostra come aggiungere, rimuovere e aggiornare le policy, nonché come verificare se una policy esiste:
// 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
Utilizzando queste API, puoi modificare dinamicamente le tue politiche. Allo stesso modo, abbiamo fornito API simili per FilteredPolicy, NamedPolicy, FilteredNamedPolicy, GroupingPolicy, NamedGroupingPolicy, FilteredGroupingPolicy, FilteredNamedGroupingPolicy. Per utilizzarle, sostituisci semplicemente la parola Policy nel nome della funzione con la categoria appropriata.
Inoltre, modificando i parametri in array, puoi eseguire la modifica batch delle tue politiche.
Ad esempio, considera funzioni come questa:
enforcer.UpdatePolicy([]string{"eve", "data3", "read"}, []string{"eve", "data3", "write"})
Se cambiamo Policy in Policies e modifichiamo i parametri come segue:
enforcer.UpdatePolicies([][]string{{"eve", "data3", "read"}, {"jack", "data3", "read"}}, [][]string{{"eve", "data3", "write"}, {"jack", "data3", "write"}})
allora possiamo eseguire la modifica batch di queste politiche.
Le stesse operazioni possono essere applicate anche a GroupingPolicy, NamedGroupingPolicy.
API AddEx
Casbin fornisce la serie di API AddEx per aiutare gli utenti ad aggiungere regole in batch.
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 differenza tra questi metodi e i metodi senza il suffisso Ex è che se una delle regole esiste già, continueranno a verificare la regola successiva invece di restituire false immediatamente.
Ad esempio, confrontiamo AddPolicies e AddPoliciesEx.
Puoi eseguire e osservare il seguente codice copiandolo nel test sotto 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 fornisce alcune API per consentirti di modificare il modello e le politiche RBAC. Se sei familiare con RBAC, puoi facilmente utilizzare queste API.
Qui, ti mostriamo solo come utilizzare le API RBAC di Casbin e non parleremo di RBAC stesso. Puoi ottenere maggiori dettagli qui.
Utilizziamo il seguente codice per caricare il modello e le politiche, proprio come prima.
enforcer, err := casbin.NewEnforcer("./example/model.conf", "./example/policy.csv")
if err != nil {
fmt.Printf("Error, details: %s\n", err)
}
Quindi, possiamo utilizzare un'istanza dell'Enforcer enforcer per accedere a queste API.
roles, err := enforcer.GetRolesForUser("amber")
fmt.Println(roles) // [admin]
users, err := enforcer.GetUsersForRole("admin")
fmt.Println(users) // [amber abc]
GetRolesForUser() restituisce un array che contiene tutti i ruoli che amber ha. In questo esempio, amber ha solo un ruolo, che è admin, quindi l'array roles è [admin]. Allo stesso modo, puoi utilizzare GetUsersForRole() per ottenere gli utenti che appartengono a un ruolo. Il valore di ritorno di questa funzione è anche un array.
enforcer.HasRoleForUser("amber", "admin") // true
Puoi utilizzare HasRoleForUser() per confermare se l'utente appartiene al ruolo. In questo esempio, amber è un membro di admin, quindi il valore di ritorno della funzione è true.
fmt.Println(enforcer.Enforce("bob", "data2", "write")) // true
enforcer.DeletePermission("data2", "write")
fmt.Println(enforcer.Enforce("bob", "data2", "write")) // false
Puoi utilizzare DeletePermission() per eliminare un permesso.
fmt.Println(enforcer.Enforce("alice", "data1", "read")) // true
enforcer.DeletePermissionForUser("alice", "data1", "read")
fmt.Println(enforcer.Enforce("alice", "data1", "read")) // false
E utilizzare DeletePermissionForUser() per eliminare un permesso per un utente.
Casbin ha molte API come queste. I loro metodi di chiamata e i valori di ritorno hanno lo stesso stile delle API sopra menzionate. Puoi trovare queste API nei prossimi documenti.