メインコンテンツにスキップ

Adapters

Casbinでは、ポリシーストレージはアダプター（Casbinのミドルウェアとも呼ばれる）として実装されています。 Casbinのユーザーは、アダプターを使用してポリシールールをストレージからロードしたり（LoadPolicy()とも呼ばれる）、ポリシールールをそれに保存したりできます（SavePolicy()とも呼ばれる）。 軽量を保つために、アダプターコードをメインライブラリに含めていません。

サポートされているアダプター​

Casbinアダプターの完全なリストを以下に示します。 新しいアダプターに関するサードパーティの貢献は歓迎します。その旨をお知らせいただければ、このリストに追加させていただきます。

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
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
メモ
  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 上の MySQL DB に root と空白のパスワードで接続します。

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エンフォーサーからストレージにすべてのポリシールールを保存するからです。 そのため、ポリシールールの数が多い場合、パフォーマンスの問題が発生する可能性があります。

アダプターが「自動保存（Auto-Save）」をサポートしている場合、「Enforcer.EnableAutoSave()」関数を介してこのオプションを切り替えることができます。 このオプションはデフォルトで有効になっています（アダプターがサポートしている場合）。

メモ
  1. 「自動保存（Auto-Save）」機能はオプションです。 アダプターはそれを実装するかどうかを選択できます。
  2. 自動保存 は、Casbinのエンフォーサーが使用するアダプターがそれをサポートしている場合にのみ機能します。
  3. 自動保存 がアダプターによってサポートされているかどうかを確認するには、上記のアダプターリストの 自動保存 列を参照してください。

自動保存 の使用方法についての例を示します：

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

アダプターの書き方​

すべてのアダプターは、少なくとも2つの必須メソッド LoadPolicy(model model.Model) error と SavePolicy(model model.Model) error を提供することで、Adapter インターフェースを実装する必要があります。

他の3つの関数はオプションです。 アダプターが 自動保存 機能をサポートしている場合に実装する必要があります。

メソッドタイプ説明
LoadPolicy()必須ストレージからすべてのポリシールールを読み込む
SavePolicy()必須すべてのポリシールールをストレージに保存する
AddPolicy()オプションストレージにポリシールールを追加する
RemovePolicy()オプションストレージからポリシールールを削除する
RemoveFilteredPolicy()オプションフィルタに一致するポリシールールをストレージから削除する
メモ

アダプタが Auto-Save をサポートしていない場合、3つのオプション関数に対して空の実装を提供する必要があります。 以下は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エンフォーサーは、これら3つのオプション関数を呼び出す際に 未実装 エラーを無視します。

アダプタの書き方についての詳細があります。

  • データ構造。 アダプタは少なくとも6列の読み取りをサポートする必要があります。
  • データベース名。 デフォルトのデータベース名は 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":[ [ "alice" ], [ "bob" ] ],
    "g":[ [ "", "book_group" ], [ "", "pen_group" ] ],
    "g2":[ [ "alice" ] ]
}

DBを作成する責任者は誰ですか？​

慣例として、アダプタは casbin という名前のデータベースを自動的に作成し、ポリシーストレージに使用できるべきです。 Xormアダプタを参考実装として使用してください: https://github.com/casbin/xorm-adapter

コンテキストアダプタ​

ContextAdapter は、Casbinアダプタのためのコンテキスト対応インターフェースを提供します。

コンテキストを通じて、アダプタAPIのタイムアウト制御などの機能を実装できます。

例​

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を実装することに基づいて、独自のコンテキスト処理ロジックをカプセル化できます。

gormadapterへの簡単な参照: adapter.go