casbin-ucon

A UCON (Usage Control) extension for Casbin that provides session-based access control with conditions, obligations, and continuous monitoring.

Overview

Casbin-UCON extends Casbin with UCON (Usage Control) capabilities, enabling:

• Session-based access control with dynamic attributes
• Condition evaluation for contextual constraints
• Obligation execution for required actions
• Continuous monitoring for ongoing authorization

Prerequisites

• Basic knowledge of Casbin is required, since Casbin-UCON extends Casbin with session-based usage control.

Installation

go get github.com/casbin/casbin-ucon

Continuous Authorization Behavior

It's important to understand how continuous authorization works in Casbin-UCON:

1. EnforceWithSession(sessionID) performs pre-checks (pre-conditions and pre-obligations) and automatically starts monitoring for ongoing conditions and obligations.

2. StartMonitoring(sessionID) only starts monitoring without pre-checks.

3. If a session no longer satisfies the conditions, session.IfActive() will return false, and you can use session.GetStopReason() to determine why the session stopped.

4. Your application is responsible for handling these notifications and deciding how to terminate the session.

Always call StopMonitoring() to clean up resources when done. Example:

gofunc() {
for {
if!session.IfActive() {
ifsession.GetStopReason() ==ucon.NormalStopReason {
// NormalStopReason means the session was stopped by user code calling StopMonitoring().break
}
//TODO//decide how to handle session termination yourself// For example, clean up resources, close connections, write logs, notify the frontend, etc.fmt.Printf("%s %s %s is stopped because: %s\n", session.GetSubject(), session.GetAction(), session.GetObject(),session.GetStopReason())
break
}
time.Sleep(200*time.Millisecond)
}
}()

Quick Start

Casbin-UCON requires standard Casbin configuration files:

• model.conf: defines the access control model (RBAC, ABAC, etc.)
• policy.csv: defines the access policies

For example:

model.conf

[request_definition]r = sub, obj, act
[policy_definition]p = sub, obj, act
[policy_effect]e = some(where (p.eft == allow))
[matchers]m = r.sub == p.sub && r.obj == p.obj && r.act == p.act

policy.csv

p,alice,document1,read

package main
import (
"github.com/casbin/casbin/v2""github.com/casbin/casbin-ucon""fmt""time"
)
funcmain() {
// Create standard Casbin enforcere, _:=casbin.NewEnforcer("model.conf", "policy.csv")
// Wrap with UCON functionalityuconE:=ucon.NewUconEnforcer(e)
// Add conditionscondition:=&ucon.Condition{
ID: "location_condition",
Name: "location",
Kind: "always",
Expr: "office",
}
uconE.AddCondition(condition)
// Add obligationsobligation:=&ucon.Obligation{
ID: "post_log",
Name: "access_logging",
Kind: "post",
Expr: "log_level:detailed",
}
uconE.AddObligation(obligation)
// Create a sessionsessionID, _:=uconE.CreateSession("alice", "read", "document1", map[string]interface{}{
"location": "office",
"log_level": "detailed",
})
// UCON session-based enforcementsession, err:=uconE.EnforceWithSession(sessionID)
ifsession==nil {
// refusedfmt.Println("session refused because: ",err )
}
gofunc() {
for {
if!session.IfActive() {
ifsession.GetStopReason() ==ucon.NormalStopReason {
break
}
//TODO//decide how to handle session termination yourself// For example, clean up resources, close connections, write logs, notify the frontend, etc.fmt.Printf("%s %s %s is stopped because: %s\n", session.GetSubject(), session.GetAction(), session.GetObject(),session.GetStopReason())
break
}
time.Sleep(200*time.Millisecond)
}
}()
/*	alice read document1	//you could change the attribute by:	session.UpdateAttribute("location", "home") */// Stop the session_=uconE.StopMonitoring(sessionID)
}

Basic API

// Enhanced enforcementEnforceWithSession(sessionIDstring) (*Session, error)
// Session managementCreateSession(subject, action, objectstring, attributesmap[string]interface{}) (string, error)
GetSession(sessionIDstring) (*Session, error)
UpdateSessionAttribute(sessionIDstring, keystring, valinterface{}) errorRevokeSession(sessionIDstring) error// Condition managementAddCondition(condition*Condition) errorEvaluateConditions(sessionIDstring) (bool, error)
// Obligation managementAddObligation(obligation*Obligation) errorExecuteObligations(sessionIDstring) errorExecuteObligationsByType(sessionIDstring, phasestring) error// MonitoringStartMonitoring(sessionIDstring) errorStopMonitoring(sessionIDstring) error

Status

Development Status: This project is in an early development stage and features may change frequently.

Current Features:

• Core interface definitions
• Basic session management
• Foundation for conditions, obligations, and monitoring
• Full Casbin compatibility

Future Plans

• Enhanced Condition & Obligation Management – Allow more flexible and customizable conditions and obligations.

• Improved Session Management – Additional features for session lifecycle and attribute handling.

• Advanced Monitoring – Configurable monitoring options for ongoing authorization and obligations.

• Comprehensive Documentation & Examples – Expanded guides, usage examples, and best practices.

License

Apache 2.0 License - see LICENSE for details.