Apache Casbin

Apache Casbin abstracts access control models into a configuration (CONF) file based on the PERM metamodel:

1. Policy: Defines the rules (e.g., p, alice, data1, read).
2. Effect: Defines how the policy rules are combined to reach a decision (e.g., some(where (p.eft == allow))).
3. Request: Defines the structure of the request being checked (e.g., r = sub, obj, act).
4. Matchers: Defines the logic used to match the request against the policy (e.g., m = r.sub == p.sub && r.obj == p.obj && r.act == p.act).

This abstraction allows you to switch or upgrade authorization mechanisms (like moving from ACL to RBAC or ABAC) simply by modifying the configuration file without changing your core application logic.

# 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

Casbin supports various access control models. You can find specific .conf (model) and .csv (policy) files in the repository's examples/ directory to implement the following patterns:

To implement authorization in your Go application, follow these three steps:

1. Initialize the Enforcer: Create a new enforcer instance by providing a model configuration file and a policy file (CSV or database).
2. Enforce Permissions: Call the Enforce method with the subject, object, and action to check if access should be granted.
3. Manage Permissions: Use the provided APIs to manage roles and policies at runtime.

// 1. New a Casbin enforcer with a model file and a policy file
e, _ := casbin.NewEnforcer("path/to/model.conf", "path/to/policy.csv")

// 2. Add an enforcement hook
sub := "alice" // the user
obj := "data1" // the resource
act := "read"  // the operation

if res, _ := e.Enforce(sub, obj, act); res {
    // permit alice to read data1
} else {
    // deny the request
}

// 3. Runtime permission management example
roles, _ := e.GetImplicitRolesForUser(sub)

The SyncedCachedEnforcer is a wrapper around SyncedEnforcer that provides a decision sync cache. It improves performance by caching the results of Enforce() calls. When a decision is made, the result is stored in a cache; subsequent identical requests can be served directly from the cache instead of re-evaluating the entire policy engine.

Key behaviors:

• Automatic Cache Invalidation: When policies are modified via AddPolicy, AddPolicies, RemovePolicy, or RemovePolicies, the enforcer automatically attempts to remove the relevant cached decisions to ensure consistency.
• Policy Reloading: Calling LoadPolicy() clears the entire cache to prevent stale decisions after a full policy reload.
• Cache Configuration: You can enable/disable the cache, set an expiration time for cached results, or provide a custom cache.Cache implementation.

// Create a new sync cached enforcer
enforcer, err := casbin.NewSyncedCachedEnforcer(adapter, model)
if err != nil {
    panic(err)
}

// Set how long decisions stay in cache
enforcer.SetExpireTime(time.Minute * 10)

// Perform an enforcement check (will use cache if enabled)
allowed, err := enforcer.Enforce("alice", "data1", "read")

Casbin uses a two-phase commit protocol to ensure consistency between the persistent storage (database) and the in-memory model.

1. Concurrency Control: Transactions attempt to acquire a commitLock with a timeout. If the lock cannot be acquired, the transaction fails.
2. Conflict Detection: Before applying changes, the system checks if the modelVersion has changed. If it has, a ConflictDetector validates that the buffered operations do not conflict with the current state of the model.
3. Database Phase: Operations are applied to the database. If the adapter supports batching (BatchAdapter) or updates (UpdatableAdapter), it uses those for efficiency. If a database error occurs, the database transaction is rolled back.
4. Model Phase: If the database commit succeeds, the in-memory model is updated. If this phase fails, it results in a critical error because the database and memory are now out of sync.
5. Role Rebuilding: If the transaction modified the g (grouping) section and autoBuildRoleLinks is enabled, the enforcer automatically rebuilds role links to maintain correct RBAC behavior.

The CachedEnforcer wraps a standard Enforcer and provides a decision cache to speed up repeated authorization requests. When enabled, it stores the results of Enforce() calls. To ensure cache consistency, the CachedEnforcer automatically invalidates or updates the cache when policies are reloaded or removed.

Key behaviors:

• Cache Key Generation: The cache uses GetCacheKey to generate keys from input parameters. Parameters must be either string types or implement the CacheableParam interface. If parameters cannot be converted to a key, the cache is bypassed for that specific call.
• Automatic Invalidation: Calling LoadPolicy(), RemovePolicy(), RemovePolicies(), or ClearPolicy() will trigger cache clearing or specific key deletion to prevent stale authorization decisions.
• Concurrency: The CachedEnforcer uses a sync.RWMutex to ensure thread-safe access to the underlying cache.

// Example of creating and using a CachedEnforcer
enforcer, err := casbin.NewCachedEnforcer("model.conf", "policy.csv")
if err != nil {
    panic(err)
}

// Set expiration for cached decisions
enforcer.SetExpireTime(time.Minute * 10)

// Enable the cache (enabled by default in NewCachedEnforcer)
enforcer.EnableCache(true)

// The first call performs the actual enforcement
allowed, err := enforcer.Enforce("alice", "data1", "read")

// Subsequent identical calls will return the cached result
allowed, err = enforcer.Enforce("alice", "data1", "read")