주요 콘텐츠로 건너뛰기

Adapters

Casbin에서 정책 저장소는 어댑터(즉, Casbin의 미들웨어)로 구현됩니다. Casbin 사용자는 어댑터를 사용하여 저장소에서 정책 규칙을 로드(즉, LoadPolicy())하거나 정책 규칙을 저장(즉, SavePolicy())할 수 있습니다. 가벼운 무게를 유지하기 위해, 우리는 어댑터 코드를 주 라이브러리에 넣지 않습니다.

지원되는 어댑터​

아래에 Casbin 어댑터의 전체 목록이 제공됩니다. 새로운 어댑터에 대한 제3자의 기여는 환영이며, 우리에게 알려주시면 이 목록에 추가하겠습니다:

AdapterTypeAuthorAutoSaveDescription
File Adapter (built-in)FileCasbin❌For .CSV (Comma-Separated Values) files
Filtered File Adapter (built-in)File@faceless-saint❌For .CSV (Comma-Separated Values) files with policy subset loading support
SQL AdapterSQL@Blank-Xu✅MySQL, PostgreSQL, SQL Server, SQLite3 are supported in master branch and Oracle is supported in oracle branch by database/sql
Xorm AdapterORMCasbin✅MySQL, PostgreSQL, TiDB, SQLite, SQL Server, Oracle are supported by Xorm
GORM AdapterORMCasbin✅MySQL, PostgreSQL, Sqlite3, SQL Server are supported by GORM
GORM Adapter ExORMCasbin✅MySQL, PostgreSQL, Sqlite3, SQL Server are supported by GORM
Ent AdapterORMCasbin✅MySQL, MariaDB, PostgreSQL, SQLite, Gremlin-based graph databases are supported by ent ORM
Beego ORM AdapterORMCasbin✅MySQL, PostgreSQL, Sqlite3 are supported by Beego ORM
SQLX AdapterORM@memwey✅MySQL, PostgreSQL, SQLite, Oracle are supported by SQLX
Sqlx AdapterORM@Blank-Xu✅MySQL, PostgreSQL, SQL Server, SQLite3 are supported in master branch and Oracle is supported in oracle branch by sqlx
GF ORM AdapterORM@vance-liu✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
GoFrame ORM AdapterORM@kotlin2018✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
gf-adapterORM@zcyc✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
Gdb AdapterORM@jxo-me✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
GoFrame V2 AdapterORM@hailaz✅MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by GoFrame ORM
Bun AdapterORM@JunNishimura✅MySQL, SQLite, PostgreSQL, SQL Server are supported by Bun ORM
Filtered PostgreSQL AdapterSQLCasbin✅For PostgreSQL
Filtered pgx AdapterSQL@pckhoi✅PostgreSQL is supported by pgx
Pgx AdapterSQL@gtoxlili✅PostgreSQL is supported by pgx, supports customizable column count
PostgreSQL AdapterSQL@cychiuae✅For PostgreSQL
RQLite AdapterSQLEDOMO Systems✅For RQLite
MongoDB AdapterNoSQLCasbin✅For MongoDB based on MongoDB Go Driver
RethinkDB AdapterNoSQL@adityapandey9✅For RethinkDB
Cassandra AdapterNoSQLCasbin❌For Apache Cassandra DB
DynamoDB AdapterNoSQLHOOQ❌For Amazon DynamoDB
DynacasbinNoSQLNewbMiao✅For Amazon DynamoDB
ArangoDB AdapterNoSQL@adamwasila✅For ArangoDB
Amazon S3 AdapterCloudSoluto❌For Minio and Amazon S3
Go CDK AdapterCloud@bartventer✅Adapter based on Go Cloud Dev Kit that supports: Amazon DynamoDB, Azure CosmosDB, GCP Firestore, MongoDB, In-Memory
Azure Cosmos DB AdapterCloud@spacycoder✅For Microsoft Azure Cosmos DB
GCP Firestore AdapterCloud@reedom❌For Google Cloud Platform Firestore
GCP Cloud Storage AdapterCloudqurami❌For Google Cloud Platform Cloud Storage
GCP Cloud Spanner AdapterCloud@flowerinthenight✅For Google Cloud Platform Cloud Spanner
Consul AdapterKV store@ankitm123❌For HashiCorp Consul
Redis Adapter (Redigo)KV storeCasbin✅For Redis
Redis Adapter (go-redis)KV store@mlsen✅For Redis
Etcd AdapterKV store@sebastianliu❌For etcd
BoltDB AdapterKV store@speza✅For Bolt
Bolt AdapterKV store@wirepair❌For Bolt
BadgerDB AdapterKV store@inits✅For BadgerDB
Protobuf AdapterStreamCasbin❌For Google Protocol Buffers
JSON AdapterStringCasbin❌For JSON
String AdapterString@qiangmzsx❌For String
HTTP File AdapterHTTP@h4ckedneko❌For http.FileSystem
FileSystem AdapterFile@naucon❌For fs.FS and embed.FS
NATS JetStream AdapterKV storegrepplabs✅For NATS JetStream
Kubernetes AdapterCloudgrepplabs✅For Kubernetes
노트
  1. casbin.NewEnforcer()가 명시적 또는 암시적 어댑터와 함께 호출되면, 정책이 자동으로 로드됩니다.
  2. 저장소에서 정책 규칙을 다시 로드하기 위해 e.LoadPolicy()를 호출할 수 있습니다.
  3. 어댑터가 Auto-Save 기능을 지원하지 않는 경우, 정책을 추가하거나 제거할 때 정책 규칙이 자동으로 저장소로 다시 저장되지 않습니다. 모든 정책 규칙을 저장하기 위해 SavePolicy()를 수동으로 호출해야 합니다.

예시​

다음은 몇 가지 예시를 제공합니다:

파일 어댑터 (내장형)​

아래는 내장 파일 어댑터에서 강제 실행기를 초기화하는 방법을 보여줍니다:

import "github.com/casbin/casbin"

e := casbin.NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv")

이것은 다음과 같습니다:

import (
    "github.com/casbin/casbin"
    "github.com/casbin/casbin/file-adapter"
)

a := fileadapter.NewAdapter("examples/basic_policy.csv")
e := casbin.NewEnforcer("examples/basic_model.conf", a)

MySQL 어댑터​

아래는 MySQL 데이터베이스에서 강제 실행기를 초기화하는 방법을 보여줍니다. 이것은 127.0.0.1:3306에서 root와 빈 비밀번호로 MySQL DB에 연결합니다.

import (
    "github.com/casbin/casbin"
    "github.com/casbin/mysql-adapter"
)

a := mysqladapter.NewAdapter("mysql", "root:@tcp(127.0.0.1:3306)/")
e := casbin.NewEnforcer("examples/basic_model.conf", a)

자체 저장소 어댑터 사용​

아래와 같이 자체 어댑터를 사용할 수 있습니다:

import (
    "github.com/casbin/casbin"
    "github.com/your-username/your-repo"
)

a := yourpackage.NewAdapter(params)
e := casbin.NewEnforcer("examples/basic_model.conf", a)

다른 어댑터 간에 마이그레이션/변환​

A에서 B로 어댑터를 변환하려면 다음과 같이 할 수 있습니다:

1.A에서 메모리로 정책 로드

e, _ := NewEnforcer(m, A)

또는

e.SetAdapter(A)
e.LoadPolicy()

2.A에서 B로 어댑터 변환

e.SetAdapter(B)

3.메모리에서 B로 정책 저장

e.SavePolicy()

런타임에 로드/저장​

초기화 후에 모델을 다시 로드하거나 정책을 다시 로드하거나 정책을 저장하려는 경우도 있을 수 있습니다:

// 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()

AutoSave​

어댑터에는 Auto-Save라는 기능이 있습니다. 어댑터가 Auto-Save를 지원하면, 저장소에 단일 정책 규칙을 추가하거나 저장소에서 단일 정책 규칙을 제거하는 것을 지원할 수 있음을 의미합니다. 이는 SavePolicy()와는 다르며, 후자는 저장소의 모든 정책 규칙을 삭제하고 Casbin enforcer의 모든 정책 규칙을 저장소에 저장합니다. 따라서 정책 규칙의 수가 많을 경우 성능 문제가 발생할 수 있습니다.

어댑터가 Auto-Save를 지원할 때, Enforcer.EnableAutoSave() 함수를 통해 이 옵션을 전환할 수 있습니다. 이 옵션은 기본적으로 활성화되어 있습니다(어댑터가 지원하는 경우).

노트
  1. Auto-Save 기능은 선택 사항입니다. 어댑터는 이를 구현하거나 구현하지 않을 수 있습니다.
  2. Auto-Save는 어댑터가 지원할 때만 Casbin enforcer에 대해 작동합니다.
  3. 어댑터가 Auto-Save를 지원하는지 확인하려면 위의 어댑터 목록에서 AutoSave 열을 참조하십시오.

Auto-Save를 사용하는 방법에 대한 예는 다음과 같습니다:

import (
    "github.com/casbin/casbin"
    "github.com/casbin/xorm-adapter"
    _ "github.com/go-sql-driver/mysql"
)

// By default, the AutoSave option is enabled for an enforcer.
a := xormadapter.NewAdapter("mysql", "mysql_username:mysql_password@tcp(127.0.0.1:3306)/")
e := casbin.NewEnforcer("examples/basic_model.conf", a)

// Disable the AutoSave option.
e.EnableAutoSave(false)

// Because AutoSave is disabled, the policy change only affects the policy in Casbin enforcer,
// it doesn't affect the policy in the storage.
e.AddPolicy(...)
e.RemovePolicy(...)

// Enable the AutoSave option.
e.EnableAutoSave(true)

// Because AutoSave is enabled, the policy change not only affects the policy in Casbin enforcer,
// but also affects the policy in the storage.
e.AddPolicy(...)
e.RemovePolicy(...)

더 많은 예제를 보려면 다음을 참조하십시오: https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go

어댑터 작성 방법​

모든 어댑터는 적어도 두 가지 필수 메서드인 LoadPolicy(model model.Model) error와 SavePolicy(model model.Model) error를 제공하여 Adapter 인터페이스를 구현해야 합니다.

나머지 세 가지 함수는 선택 사항입니다. 어댑터가 Auto-Save 기능을 지원하는 경우 이들을 구현해야 합니다.

메서드유형설명
LoadPolicy()필수저장소에서 모든 정책 규칙을 로드합니다
SavePolicy()필수모든 정책 규칙을 저장소에 저장합니다
AddPolicy()선택저장소에 정책 규칙을 추가합니다
RemovePolicy()선택저장소에서 정책 규칙을 제거하십시오
RemoveFilteredPolicy()선택 사항필터와 일치하는 정책 규칙을 저장소에서 제거하십시오
노트

어댑터가 'Auto-Save'를 지원하지 않는 경우, 세 가지 선택적 함수에 대해 빈 구현을 제공해야 합니다. 다음은 Golang의 예입니다:

// AddPolicy adds a policy rule to the storage.
func (a *Adapter) AddPolicy(sec string, ptype string, rule []string) error {
    return errors.New("not implemented")
}

// RemovePolicy removes a policy rule from the storage.
func (a *Adapter) RemovePolicy(sec string, ptype string, rule []string) error {
    return errors.New("not implemented")
}

// RemoveFilteredPolicy removes policy rules that match the filter from the storage.
func (a *Adapter) RemoveFilteredPolicy(sec string, ptype string, fieldIndex int, fieldValues ...string) error {
    return errors.New("not implemented")
}

Casbin enforcer는 이 세 가지 선택적 함수를 호출할 때 'not implemented' 오류를 무시합니다.

어댑터를 작성하는 방법에 대한 세부 정보가 있습니다.

  • 데이터 구조. 어댑터는 최소한 여섯 개의 열을 읽을 수 있어야 합니다.
  • 데이터베이스 이름. 기본 데이터베이스 이름은 'casbin'이어야 합니다.
  • 테이블 이름. 기본 테이블 이름은 'casbin_rule'이어야 합니다.
  • Ptype 열. 이 열의 이름은 'p_type' 또는 'Ptype' 대신 'ptype'이어야 합니다.
  • 테이블 정의는 '(id int primary key, ptype varchar, v0 varchar, v1 varchar, v2 varchar, v3 varchar, v4 varchar, v5 varchar)'이어야 합니다.
  • 고유 키 인덱스는 'ptype,v0,v1,v2,v3,v4,v5' 열에 구축되어야 합니다.
  • LoadFilteredPolicy는 filter를 매개변수로 필요로 합니다. 필터는 이런 식이어야 합니다.
{
    "p": ["", "domain1"],
    "g": ["", "", "domain1"]
}

데이터베이스를 생성할 책임이 누구인가요?​

관례적으로, 어댑터는 존재하지 않는 경우 'casbin'이라는 데이터베이스를 자동으로 생성하고 정책 저장소로 사용할 수 있어야 합니다. 참조 구현으로 Xorm 어댑터를 사용하십시오: https://github.com/casbin/xorm-adapter

Update Adapter​

The UpdateAdapter interface extends the basic Adapter interface to support updating policies directly in the storage. This is more efficient than removing and re-adding policies when you need to modify existing rules.

An adapter that implements the UpdateAdapter interface should provide the following methods:

MethodTypeDescription
UpdatePolicy()optionalUpdate a single policy rule in the storage
UpdatePolicies()optionalUpdate multiple policy rules in the storage
UpdateFilteredPolicies()optionalUpdate policy rules that match the filter in the storage

예시​

Here's an example of using the update adapter methods:

import (
    "github.com/casbin/casbin/v2"
    "github.com/casbin/gorm-adapter/v3"
)

a, _ := gormadapter.NewAdapter("mysql", "root:@tcp(127.0.0.1:3306)/")
e, _ := casbin.NewEnforcer("examples/rbac_model.conf", a)

// Update a single policy
// Change: p, alice, data1, read -> p, alice, data1, write
e.UpdatePolicy(
    []string{"alice", "data1", "read"},
    []string{"alice", "data1", "write"},
)

// Update multiple policies at once
e.UpdatePolicies(
    [][]string{{"alice", "data1", "write"}, {"bob", "data2", "read"}},
    [][]string{{"alice", "data1", "read"}, {"bob", "data2", "write"}},
)

// Update all policies matching a filter
e.UpdateFilteredPolicies(
    [][]string{{"alice", "data1", "write"}},
    0,
    "alice", "data1", "read",
)

How to write an update adapter​

To implement the UpdateAdapter interface, your adapter needs to implement the update methods in addition to the basic Adapter interface:

// UpdatePolicy updates a policy rule from storage.
// This is part of the UpdateAdapter interface.
func (a *Adapter) UpdatePolicy(sec string, ptype string, oldRule, newRule []string) error {
    // Implementation to update the policy in storage
    // For example, in SQL: UPDATE casbin_rule SET v0=?, v1=?, v2=? WHERE ptype=? AND v0=? AND v1=? AND v2=?
    return nil
}

// UpdatePolicies updates multiple policy rules in the storage.
// This is part of the UpdateAdapter interface.
func (a *Adapter) UpdatePolicies(sec string, ptype string, oldRules, newRules [][]string) error {
    // Implementation to update multiple policies in storage
    // This should be done in a transaction for consistency
    return nil
}

// UpdateFilteredPolicies updates policy rules that match the filter from the storage.
// This is part of the UpdateAdapter interface.
func (a *Adapter) UpdateFilteredPolicies(sec string, ptype string, newRules [][]string, fieldIndex int, fieldValues ...string) error {
    // Implementation to update filtered policies in storage
    // First find policies matching the filter, then update them
    return nil
}
노트

If an adapter doesn't support the UpdateAdapter interface, Casbin will automatically fall back to using the combination of RemovePolicy() and AddPolicy() operations.

컨텍스트 어댑터​

ContextAdapter는 Casbin 어댑터에 대한 컨텍스트 인식 인터페이스를 제공합니다.

컨텍스트를 통해 어댑터 API에 대한 타임아웃 제어와 같은 기능을 구현할 수 있습니다

Example​

gormadapter는 컨텍스트가 있는 어댑터를 지원하며, 다음은 컨텍스트를 사용하여 구현된 타임아웃 제어입니다

ca, _ := NewContextAdapter("mysql", "root:@tcp(127.0.0.1:3306)/", "casbin")
// Limited time 300s
ctx, cancel := context.WithTimeout(context.Background(), 300*time.Microsecond)
defer cancel()

err := ca.AddPolicyCtx(ctx, "p", "p", []string{"alice", "data1", "read"})
if err != nil {
    panic(err)
}

컨텍스트 어댑터를 작성하는 방법​

ContextAdapter API는 일반 Adapter API보다 컨텍스트 처리 계층만 추가로 있으며, 일반 Adapter API를 구현하는 기반 위에 컨텍스트에 대한 자체 처리 로직을 캡슐화할 수 있습니다

A simple reference to the gormadapter: adapter.go

Transaction​

Casbin now supports Transactions. Here's an example about how to use Transaction in gormadapter:

db, _ := gorm.Open(...)
adapter, _ := gormadapter.NewTransactionalAdapterByDB(db)
e, _ := casbin.NewTransactionalEnforcer("examples/rbac_model.conf", adapter)

ctx := context.Background()

// WithTransaction executes a function within a transaction.
// If the function returns an error, the transaction is rolled back.
// Otherwise, it's committed automatically.
err := e.WithTransaction(ctx, func(tx *casbin.Transaction) error {
    tx.AddPolicy("alice", "data1", "read")
    tx.AddPolicy("alice", "data1", "write")
    return nil
})

// If you wish to manually handle the transaction
tx, _ := e.BeginTransaction(ctx)
tx.AddPolicy("alice", "data1", "write")
if err := tx.Commit(); err != nil {
    // handle if transaction failed
}

To add this capability to your adapter, you need to implement TransactionalAdapter and TransactionContext in persist/transaction.go.

Code reference to the gormadapter: adapter.go