ucon

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 15, 2025 License: Apache-2.0 Imports: 7 Imported by: 0

README

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:

go func() {
  for {
    if !session.IfActive() {
      if session.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"
)

func main() {
    // Create standard Casbin enforcer
    e, _ := casbin.NewEnforcer("model.conf", "policy.csv")

    // Wrap with UCON functionality
    uconE := ucon.NewUconEnforcer(e)

    // Add conditions
    condition := &ucon.Condition{
        ID:   "location_condition",
		Name: "location",
		Kind: "always",
		Expr: "office",
    }
    uconE.AddCondition(condition)

    // Add obligations
    obligation := &ucon.Obligation{
        ID:   "post_log",
		Name: "access_logging",
		Kind: "post",
		Expr: "log_level:detailed",
    }
    uconE.AddObligation(obligation)

        // Create a session
    sessionID, _ := uconE.CreateSession("alice", "read", "document1", map[string]interface{}{
        "location":      "office",
		"log_level":     "detailed",
    })

    // UCON session-based enforcement
    session, err := uconE.EnforceWithSession(sessionID)
	if session == nil {
        // refused
        fmt.Println("session refused because: ",err )
    }

  go func() {
    for {
      if !session.IfActive() {
        if session.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 enforcement
EnforceWithSession(sessionID string) (*Session, error)

// Session management
CreateSession(subject, action, object string, attributes map[string]interface{}) (string, error)
GetSession(sessionID string) (*Session, error)
UpdateSessionAttribute(sessionID string, key string, val interface{}) error
RevokeSession(sessionID string) error

// Condition  management
AddCondition(condition *Condition) error
EvaluateConditions(sessionID string) (bool, error)
// Obligation management
AddObligation(obligation *Obligation) error
ExecuteObligations(sessionID string) error
ExecuteObligationsByType(sessionID string, phase string) error

// Monitoring
StartMonitoring(sessionID string) error
StopMonitoring(sessionID string) 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.

Documentation

Index

Constants

View Source 
const (
	NormalStopReason = ""
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Condition 

type Condition struct {
	ID   string
	Name string
	Kind string // "one", "always"
	Expr string
}

type IUconEnforcer 

type IUconEnforcer interface {
	// Inherit Casbin basic functionality
	casbin.IEnforcer

	// Enhanced enforcement with session context
	EnforceWithSession(sessionID string) (*Session, error)

	// Session management
	CreateSession(sub string, act string, obj string, attributes map[string]interface{}) (string, error)
	GetSession(sessionID string) (*Session, error)
	UpdateSessionAttribute(sessionID string, key string, val interface{}) error
	RevokeSession(sessionID string) error

	// Condition evaluation
	AddCondition(condition *Condition) error
	EvaluateConditions(sessionID string) (bool, error)

	// Obligation management
	AddObligation(obligation *Obligation) error
	ExecuteObligations(sessionID string) error
	ExecuteObligationsByType(sessionID string, phase string) error

	// Continuous monitoring
	StartMonitoring(sessionID string) error
	StopMonitoring(sessionID string) error
}

IUconEnforcer is the API interface of UconEnforcer.

func NewUconEnforcer 

func NewUconEnforcer(e *casbin.Enforcer) IUconEnforcer

NewUconEnforcer creates a new UCON enforcer.

type Obligation 

type Obligation struct {
	ID   string
	Name string
	Kind string // "pre", "post", "ongoing"
	Expr string
}

type Session 

type Session struct {
	// contains filtered or unexported fields
}

func (*Session) GetAction added in v1.1.0 

func (s *Session) GetAction() string

func (*Session) GetAttribute added in v1.1.0 

func (s *Session) GetAttribute(key string) interface{}

func (*Session) GetDuration added in v1.1.0 

func (s *Session) GetDuration() time.Duration

func (*Session) GetEndTime added in v1.1.0 

func (s *Session) GetEndTime() time.Time

func (*Session) GetId added in v1.1.0 

func (s *Session) GetId() string

func (*Session) GetObject added in v1.1.0 

func (s *Session) GetObject() string

func (*Session) GetStartTime added in v1.1.0 

func (s *Session) GetStartTime() time.Time

func (*Session) GetStopReason added in v1.1.0 

func (s *Session) GetStopReason() string

func (*Session) GetSubject added in v1.1.0 

func (s *Session) GetSubject() string

func (*Session) IfActive added in v1.1.0 

func (s *Session) IfActive() bool

func (*Session) Stop added in v1.1.0 

func (s *Session) Stop(reason string) error

func (*Session) UpdateAttribute added in v1.1.0 

func (s *Session) UpdateAttribute(key string, val interface{}) error

type SessionManager added in v1.1.0 

type SessionManager struct {
	// contains filtered or unexported fields
}

func NewSessionManager added in v1.1.0 

func NewSessionManager() *SessionManager

func (*SessionManager) CreateSession added in v1.1.0 

func (sm *SessionManager) CreateSession(sub string, act string, obj string, attributes map[string]interface{}) (string, error)

func (*SessionManager) DeleteSession added in v1.1.0 

func (sm *SessionManager) DeleteSession(sessionID string) error

func (*SessionManager) GetSessionById added in v1.1.0 

func (sm *SessionManager) GetSessionById(id string) (*Session, error)

func (*SessionManager) UpdateSessionAttribute added in v1.1.0 

func (sm *SessionManager) UpdateSessionAttribute(sessionID string, key string, val interface{}) error

type UconEnforcer 

type UconEnforcer struct {
	*casbin.Enforcer // Embed casbin.Enforcer for backward compatibility
	// contains filtered or unexported fields
}

UconEnforcer UCON enforcer that wraps casbin.Enforcer and extends UCON functionality.

func (*UconEnforcer) AddCondition 

func (u *UconEnforcer) AddCondition(condition *Condition) error

AddCondition adds a condition.

func (*UconEnforcer) AddObligation 

func (u *UconEnforcer) AddObligation(obligation *Obligation) error

AddObligation adds an obligation.

func (*UconEnforcer) CreateSession 

func (u *UconEnforcer) CreateSession(sub string, act string, obj string, attributes map[string]interface{}) (string, error)

CreateSession creates a new session.

func (*UconEnforcer) EnforceWithSession 

func (u *UconEnforcer) EnforceWithSession(sessionID string) (*Session, error)

EnforceWithSession performs enforcement with session context.

func (*UconEnforcer) EvaluateConditions 

func (u *UconEnforcer) EvaluateConditions(sessionID string) (bool, error)

EvaluateConditions evaluates all conditions for a session.

func (*UconEnforcer) ExecuteObligations 

func (u *UconEnforcer) ExecuteObligations(sessionID string) error

ExecuteObligations executes all obligations for a session (backward compatibility).

func (*UconEnforcer) ExecuteObligationsByType 

func (u *UconEnforcer) ExecuteObligationsByType(sessionID string, kind string) error

ExecuteObligationsByPhase executes obligations for a specific type.

func (*UconEnforcer) GetSession 

func (u *UconEnforcer) GetSession(sessionID string) (*Session, error)

GetSession retrieves session information.

func (*UconEnforcer) RevokeSession 

func (u *UconEnforcer) RevokeSession(sessionID string) error

RevokeSession revokes a session.

func (*UconEnforcer) StartMonitoring 

func (u *UconEnforcer) StartMonitoring(sessionID string) error

StartMonitoring starts monitoring a session.

func (*UconEnforcer) StopMonitoring 

func (u *UconEnforcer) StopMonitoring(sessionID string) error

StopMonitoring stops monitoring a session.

func (*UconEnforcer) UpdateSessionAttribute 

func (u *UconEnforcer) UpdateSessionAttribute(sessionID string, key string, val interface{}) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.