casbin-rs

Casbin-rs supports a wide variety of access control models, including:

• ACL (Access Control List): Basic permission mapping.
• RBAC (Role-Based Access Control): Users assigned to roles.
• RBAC with domains/tenants: Roles scoped to specific domains.
• ABAC (Attribute-Based Access Control): Permissions based on attributes (e.g., resource.Owner).
• RESTful: Supports path patterns (e.g., /res/*) and HTTP methods.
• Deny-override: Explicit deny rules that override allow rules.
• Priority: Rules that can be prioritized like firewall rules.

If you are building web applications, you can use specialized authorization middlewares to integrate Casbin's access control logic directly into your web framework's request lifecycle. These middlewares handle the extraction of subjects, objects, and actions from incoming requests automatically.

For a list of supported middlewares and integration guides, refer to the official Casbin documentation: https://casbin.org/docs/middlewares

If you are upgrading from an older version of Casbin-RS where custom functions used ImmutableString, you must update the function signatures to use Dynamic and manually convert the arguments.

Old Pattern (ImmutableString):

e.add_function(
    "myFunc",
    OperatorFunction::Arg2(
        |s1: ImmutableString, s2: ImmutableString| {
            // logic here
            true.into()
        }
    ),
);

New Pattern (Dynamic):

e.add_function(
    "myFunc",
    OperatorFunction::Arg2(|s1: Dynamic, s2: Dynamic| {
        let str1 = s1.to_string();
        let str2 = s2.to_string();
        // logic here
        true.into()
    }),
);

To use Casbin, initialize an Enforcer with a model configuration file and a policy file. You can then use the .enforce() method to check if a specific request is authorized.

Important: The Enforcer instance is not thread-safe. If you need to access it across multiple threads, wrap it in an Arc<RwLock<Enforcer>>.

use casbin::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // 1. Initialize the enforcer
    let mut e = Enforcer::new("examples/rbac_with_domains_model.conf", "examples/rbac_with_domains_policy.csv").await?;
    e.enable_log(true);

    // 2. Enforce a request
    // The arguments passed to enforce must match the [request_definition] in your model
    e.enforce(("alice", "domain1", "data1", "read"))?;
    Ok(())
}

Add casbin to your Cargo.toml. It is recommended to use tokio v1.0 or later with casbin v2.0.6 or higher. You may need to enable specific features like runtime-async-std, logging, or incremental depending on your requirements.

[dependencies]
casbin = { version = "2.8.0", default-features = false, features = ["runtime-async-std", "logging", "incremental"] }
tokio = { version = "1.10.0", features = ["fs", "io-util"] }

A DefaultModel organizes authorization rules into several standard sections. When loading from a configuration, it populates these sections:

• r: Request definition
• p: Policy definition
• e: Policy effect
• m: Matchers
• g: Role definition (grouping policies)

In casbin-rs, events are categorized using the Event enum and identified via EventKey.

• Event: A standard enum provided by the library containing core event types:

  • PolicyChange: Triggered when policies are added, removed, or cleared.
  • ClearCache: Triggered when the internal cache is invalidated.

• EventKey: A trait used to constrain the type of keys used in an EventEmitter. Any type that implements Hash + PartialEq + Eq + Send + Sync automatically implements EventKey. This allows you to use the built-in Event enum or your own custom event types as keys for event subscription.

An EnforceContext allows the Enforcer to target specific model sections when multiple sets of request/policy/matcher/effector definitions exist in a single model.

When you create a context with a suffix, the Enforcer generates type-specific keys for the lookup:

• r_type: r + suffix
• p_type: p + suffix
• e_type: e + suffix
• m_type: m + suffix

This is essential for complex models where different rulesets coexist.

let ctx = EnforceContext::new("2");
// This context will target r2, p2, e2, and m2

The Enforcer is the primary interface for authorization enforcement and policy management. You can initialize it using a model and an adapter. If you use the new method, it will automatically load the policy from the adapter unless the adapter is filtered.

Note: The initialization is asynchronous and requires a runtime like tokio or async-std.

use casbin::prelude::*;

#[cfg(feature = "runtime-tokio")]
#[tokio::main]
async fn main() -> Result<()> {
    let mut e = Enforcer::new("examples/basic_model.conf", "examples/basic_policy.csv").await?;
    assert_eq!(true, e.enforce(("alice", "data1", "read"))?);
    Ok(())
}