Add error handling for the enforcer.
Note: The plugins and middleware based on Casbin can be found at: https://github.com/casbin
Casbin is a powerful and efficient open-source access control library for Golang projects. It provides support for enforcing authorization based on various models. By far, the access control models supported by Casbin are:
write-article, read-log. It doesn't control the access to a specific article or log.In Casbin, an access control model is abstracted into a CONF file based on the PERM metamodel (Policy, Effect, Request, Matchers). So switching or upgrading the authorization mechanism for a project is just as simple as modifying a configuration. You can customize your own access control model by combining the available models. For example, you can get RBAC roles and ABAC attributes together inside one model and share one set of policy rules.
The most basic and simplest model in Casbin is ACL. ACL's model CONF is:
# Request definition [request_definition] r = sub, obj, act # Policy definition [policy_definition] p = sub, obj, act # Policy effect [policy_effect] e = some(where (p.eft == allow)) # Matchers [matchers] m = r.sub == p.sub && r.obj == p.obj && r.act == p.act
An example policy for ACL model is like:
p, alice, data1, read p, bob, data2, write
It means:
What Casbin does:
{subject, object, action} form or a customized form as you defined, both allow and deny authorizations are supported.root or administrator. A superuser can do anything without explict permissions.keyMatch can map a resource key /foo/bar to the pattern /foo*.What Casbin does NOT do:
username and password when a user logs in)go get github.com/casbin/casbin
casbin.conf to your need. Its default content is:[default] # The file path to the model: model_path = examples/basic_model.conf # The persistent method for policy, can be two values: file or database. # policy_backend = file # policy_backend = database policy_backend = file [file] # The file path to the policy: policy_path = examples/basic_policy.csv [database] driver = mysql data_source = root:@tcp(127.0.0.1:3306)/
It means uses basic_model.conf as the model and basic_policy.csv as the policy.
e := casbin.NewEnforcer("path/to/casbin.conf")
Note: you can also initialize an enforcer directly with a file path or database, see Persistence section for details.
sub := "alice" // the user that wants to access a resource. obj := "data1" // the resource that is going to be accessed. act := "read" // the operation that the user performs on the resource. if e.Enforce(sub, obj, act) == true { // permit alice to read data1 } else { // deny the request, show an error }
roles := e.GetRoles("alice")
_test.go files for more usage.See: Model.md
The model and policy can be persisted in Casbin with the following restrictions:
| Persist Method | Casbin Model | Casbin Policy | Usage |
|---|---|---|---|
| File | Load only | Load/Save | Details |
| Database (tested with MySQL) | Not supported | Load/Save | Details |
| Cassandra (NoSQL) | Not supported | Load/Save | Details |
We think the model represents the access control model that our customer uses and is not often modified at run-time, so we don't implement an API to modify the current model or save the model into a file. And the model cannot be loaded from or saved into a database. The model file should be in .CONF format.
The policy is much more dynamic than model and can be loaded from a file/database or saved to a file/database at any time. As for file persistence, the policy file should be in .CSV (Comma-Separated Values) format. As for the database backend, Casbin should support all relational DBMSs but I only tested with MySQL. Casbin has no built-in database with it, you have to setup a database on your own. Let me know if there are any compatibility issues here. Casbin will automatically create a database named casbin and use it for policy storage. So make sure your provided credential has the related privileges for the database you use.
Below shows how to initialize an enforcer from file:
// Initialize an enforcer with a model file and a policy file. e := casbin.NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv")
Below shows how to initialize an enforcer from database. it connects to a MySQL DB on 127.0.0.1:3306 with root and blank password.
// Initialize an enforcer with a model file and policy from database. e := casbin.NewEnforcer("examples/basic_model.conf", "mysql", "root:@tcp(127.0.0.1:3306)/")
In Casbin, both the above file and database storage is implemented as an adapter. You can use your own adapter like below:
// Initialize an enforcer with an adapter. adapter := persist.NewFileAdapter("examples/basic_policy.csv") // or replace with your own adapter. e := casbin.NewEnforcer("examples/basic_model.conf", adapter)
An adapter should implement two methods:LoadPolicy(model model.Model) and SavePolicy(model model.Model). To keep light-weight, we don‘t put all adapters’ code in this main library. You can choose officially supported adapters from: https://github.com/casbin and use it like a plugin as above.
You may also want to reload the model, reload the policy or save the policy after initialization:
// Reload the model from the model CONF file. e.LoadModel() // Reload the policy from file/database. e.LoadPolicy() // Save the current policy (usually after changed with Casbin API) back to file/database. e.SavePolicy()
| Model | Model file | Policy file |
|---|---|---|
| ACL | basic_model.conf | basic_policy.csv |
| ACL with superuser | basic_model_with_root.conf | basic_policy.csv |
| ACL without users | basic_model_without_users.conf | basic_policy_without_users.csv |
| ACL without resources | basic_model_without_resources.conf | basic_policy_without_resources.csv |
| RBAC | rbac_model.conf | rbac_policy.csv |
| RBAC with resource roles | rbac_model_with_resource_roles.conf | rbac_policy_with_resource_roles.csv |
| RBAC with domains/tenants | rbac_model_with_domains.conf | rbac_policy_with_domains.csv |
| ABAC | abac_model.conf | N/A |
| RESTful | keymatch_model.conf | keymatch_policy.csv |
| Deny-override | rbac_model_with_deny.conf | rbac_policy_with_deny.csv |
This project is licensed under the Apache 2.0 license.
If you have any issues or feature requests, please contact us. PR is welcomed.