diff --git a/website/translated_docs/fr-FR/ABAC.md b/website/translated_docs/fr-FR/ABAC.md new file mode 100644 index 00000000..03a53a11 --- /dev/null +++ b/website/translated_docs/fr-FR/ABAC.md @@ -0,0 +1,75 @@ +--- +id: abac +title: ABAC +--- + +## What is the ABAC model actually? + +ABAC is `Attribute-Based Access Control`, meaning you can use the attributes (properties) of the subject, object or action instead of themselves (the string) to control the access. You may already hear of a complicated ABAC access control language named XACML. Compared to XACML, Casbin's ABAC is very simple: in ABAC, you can use structs (or class instances based on the programming language) instead of string for model elements. + +Use the official ABAC example for example: + +```ini +[request_definition] +r = sub, obj, act + +[policy_definition] +p = sub, obj, act + +[policy_effect] +e = some(where (p.eft == allow)) + +[matchers] +m = r.sub == r.obj.Owner +``` + +We use `r.obj.Owner` instead of `r.obj` in the matcher. The `r.obj` passed in the `Enforce()` function will be a struct or class instance instead of string. Casbin will use reflection to retrieve the `obj` member variable in that struct or class for you. + +Here is a definition for the `r.obj` struct or class: + +```go +type testResource struct { + Name string + Owner string +} +``` + +## How to use ABAC? + +Simply speaking, to use ABAC, you need to do two things: + +1. Specify the attributes in the model matcher. +2. Pass in the struct or class instance for the element as the argument in Casbin's `Enforce()` function. + +:::warning Currently, only request elements like `r.sub`, `r.obj`, `r.act` and so on support ABAC. You cannot use it on policy elements like `p.sub`, because there is no way to define a struct or class in Casbin's policy. ::: + +:::tip You can use multiple ABAC attributes in a matcher, for example: `m = r.sub.Domain == r.obj.Domain`. ::: + +## Scaling the model for complex and large number of ABAC rules. + +The above instance of ABAC implementation is at its core very simple, but oftentimes the authorization system needs a very complex and large number of ABAC rules. To fit this necessity the above implementation will increase the verbosity of the model to a large extent. So, it’s wise to add the rules in the policy instead of in the model. This is done by introducing a `eval()` functional construct. Below is the example instance to manage such ABAC models. + +This is the definition of the `CONF` file used for defining the ABAC model. + +```ini +[request_definition] +r = sub, obj, act + +[policy_definition] +p = sub_rule, obj, act + +[policy_effect] +e = some(where (p.eft == allow)) + +[matchers] +m = eval(p.sub_rule) && r.obj == p.obj && r.act == p.act +``` + +Here, `p.sub_rule` is of type struct or class(user-defined type) which consists of necessary attributes to be used in the policy. + +This is the policy that is used against the model for `Enforcement`. Now, you can use the object instance which is passed to `eval()` as a parameter to define certain ABAC constraints. + +``` +p, r.sub.Age > 18, /data1, read +p, r.sub.Age < 60, /data2, write +``` \ No newline at end of file diff --git a/website/translated_docs/fr-FR/Adapters.md b/website/translated_docs/fr-FR/Adapters.md new file mode 100644 index 00000000..6f2bc35b --- /dev/null +++ b/website/translated_docs/fr-FR/Adapters.md @@ -0,0 +1,321 @@ +--- +id: adapters +title: Adapters +--- + +In Casbin, the policy storage is implemented as an adapter (aka middleware for Casbin). A Casbin user can use an adapter to load policy rules from a storage (aka `LoadPolicy()`), or save policy rules to it (aka `SavePolicy()`). To keep light-weight, we don't put adapter code in the main library. + +## Supported adapters + +A complete list of Casbin adapters is provided as below. Any 3rd-party contribution on a new adapter is welcomed, please inform us and we will put it in this list:) + + + + +| Adapter | Type | Author | AutoSave | Description | +| ------------------------------------------------------------------------------------ | -------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [Filtered File Adapter (built-in)](https://casbin.org/docs/en/policy-subset-loading) | File | [@faceless-saint](https://github.com/faceless-saint) | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files with policy subset loading support | +| [SQL Adapter](https://github.com/Blank-Xu/sql-adapter) | SQL | [@Blank-Xu](https://github.com/Blank-Xu) | ✅ | MySQL, PostgreSQL, SQL Server, SQLite3 are supported in `master` branch and Oracle is supported in `oracle` branch by `database/sql` | +| [Xorm Adapter](https://github.com/casbin/xorm-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, TiDB, SQLite, SQL Server, Oracle are supported by [Xorm](https://github.com/go-xorm/xorm/) | +| [Gorm Adapter](https://github.com/casbin/gorm-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, Sqlite3, SQL Server are supported by [Gorm](https://github.com/jinzhu/gorm/) | +| [Beego ORM Adapter](https://github.com/casbin/beego-orm-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, Sqlite3 are supported by [Beego ORM](https://beego.me/docs/mvc/model/overview.md) | +| [SQLX Adapter](https://github.com/memwey/casbin-sqlx-adapter) | ORM | [@memwey](https://github.com/memwey) | ✅ | MySQL, PostgreSQL, SQLite, Oracle are supported by [SQLX](https://github.com/jmoiron/sqlx) | +| [Sqlx Adapter](https://github.com/Blank-Xu/sqlx-adapter) | SQL | [@Blank-Xu](https://github.com/Blank-Xu) | ✅ | MySQL, PostgreSQL, SQL Server, SQLite3 are supported in `master` branch and Oracle is supported in `oracle` branch by [sqlx](https://github.com/jmoiron/sqlx) | +| [GF ORM Adapter](https://github.com/vance-liu/gdb-adapter) | ORM | [@vance-liu](https://github.com/vance-liu) | ✅ | MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by [GoFrame ORM](https://goframe.org/pages/viewpage.action?pageId=1114686) | +| [GoFrame ORM Adapter](https://github.com/kotlin2018/adapter) | ORM | [@kotlin2018](https://github.com/kotlin2018) | ✅ | MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by [GoFrame ORM](https://goframe.org/pages/viewpage.action?pageId=1114686) | +| [Filtered PostgreSQL Adapter](https://github.com/casbin/casbin-pg-adapter) | SQL | Casbin | ✅ | For [PostgreSQL](https://www.postgresql.org/) | +| [PostgreSQL Adapter](https://github.com/cychiuae/casbin-pg-adapter) | SQL | [@cychiuae](https://github.com/cychiuae) | ✅ | For [PostgreSQL](https://www.postgresql.org/) | +| [PostgreSQL Adapter (Archived)](https://github.com/going/casbin-postgres-adapter) | SQL | [Going](https://github.com/going) | ❌ | For [PostgreSQL](https://www.postgresql.org/) | +| [RQLite Adapter](https://github.com/edomosystems/rqlite-adapter) | SQL | [EDOMO Systems](https://github.com/edomosystems) | ✅ | For [RQLite](https://github.com/rqlite/rqlite/) | +| [MongoDB Adapter](https://github.com/casbin/mongodb-adapter) | NoSQL | Casbin | ✅ | For [MongoDB](https://www.mongodb.com) based on [MongoDB driver for Go](https://github.com/globalsign/mgo) | +| [RethinkDB Adapter](https://github.com/adityapandey9/rethinkdb-adapter) | NoSQL | [@adityapandey9](https://github.com/adityapandey9) | ✅ | For [RethinkDB](https://rethinkdb.com/) | +| [Cassandra Adapter](https://github.com/casbin/cassandra-adapter) | NoSQL | Casbin | ❌ | For [Apache Cassandra DB](http://cassandra.apache.org) | +| [DynamoDB Adapter](https://github.com/HOOQTV/dynacasbin) | NoSQL | [HOOQ](https://github.com/HOOQTV) | ❌ | For [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) | +| [Dynacasbin](https://github.com/NewbMiao/dynacasbin) | NoSQL | [NewbMiao](https://github.com/NewbMiao) | ✅ | For [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) | +| [ArangoDB Adapter](https://github.com/adamwasila/arangodb-adapter) | NoSQL | [@adamwasila](https://github.com/adamwasila) | ✅ | For [ArangoDB](https://www.arangodb.com/) | +| [Amazon S3 Adapter](https://github.com/Soluto/casbin-minio-adapter) | Cloud | [Soluto](https://github.com/Soluto) | ❌ | For [Minio](https://github.com/minio/minio) and [Amazon S3](https://aws.amazon.com/s3/) | +| [Azure Cosmos DB Adapter](https://github.com/spacycoder/cosmos-casbin-adapter) | Cloud | [@spacycoder](https://github.com/spacycoder) | ✅ | For [Microsoft Azure Cosmos DB](https://docs.microsoft.com/en-us/azure/cosmos-db/introduction) | +| [GCP Firestore Adapter](https://github.com/reedom/casbin-firestore-adapter) | Cloud | [@reedom](https://github.com/reedom) | ❌ | For [Google Cloud Platform Firestore](https://cloud.google.com/firestore/) | +| [Consul Adapter](https://github.com/ankitm123/consul-adapter) | KV store | [@ankitm123](https://github.com/ankitm123) | ❌ | For [HashiCorp Consul](https://www.consul.io/) | +| [Redis Adapter](https://github.com/casbin/redis-adapter) | KV store | Casbin | ❌ | For [Redis](https://redis.io/) | +| [Etcd Adapter](https://github.com/sebastianliu/etcd-adapter) | KV store | [@sebastianliu](https://github.com/sebastianliu) | ❌ | For [etcd](https://github.com/coreos/etcd) | +| [BoltDB Adapter](https://github.com/speza/casbin-bolt-adapter) | KV store | [@speza](https://github.com/speza) | ✅ | For [Bolt](https://github.com/boltdb/bolt) | +| [Bolt Adapter](https://github.com/wirepair/bolt-adapter) | KV store | [@wirepair](https://github.com/wirepair) | ❌ | For [Bolt](https://github.com/boltdb/bolt) | +| [BadgerDB Adapter](https://github.com/inits/casbin-badgerdb-adapter) | KV store | [@inits](https://github.com/inits) | ✅ | For [BadgerDB](https://github.com/dgraph-io/badger) | +| [Protobuf Adapter](https://github.com/casbin/protobuf-adapter) | Stream | Casbin | ❌ | For [Google Protocol Buffers](https://developers.google.com/protocol-buffers/) | +| [JSON Adapter](https://github.com/casbin/json-adapter) | String | Casbin | ❌ | For [JSON](https://www.json.org/) | +| [String Adapter](https://github.com/qiangmzsx/string-adapter) | String | [@qiangmzsx](https://github.com/qiangmzsx) | ❌ | For String | +| [HTTP File Adapter](https://github.com/h4ckedneko/casbin-httpfs) | HTTP | [@h4ckedneko](https://github.com/h4ckedneko) | ❌ | For [http.FileSystem](https://golang.org/src/net/http/fs.go) | + + +| Adapter | Type | Author | AutoSave | Description | +| ------------------------------------------------------------------------------------ | ----- | ------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [JDBC Adapter](https://github.com/jcasbin/jdbc-adapter) | JDBC | Casbin | ✅ | MySQL, Oracle, PostgreSQL, DB2, Sybase, SQL Server are supported by [JDBC](https://docs.oracle.com/cd/E19226-01/820-7688/gawms/index.html) | +| [Hibernate Adapter](https://github.com/jcasbin/hibernate-adapter) | ORM | Casbin | ✅ | Oracle, DB2, SQL Server, Sybase, MySQL, PostgreSQL are supported by [Hibernate](http://www.hibernate.org/) | +| [MyBatis Adapter](https://github.com/jcasbin/mybatis-adapter) | ORM | Casbin | ✅ | MySQL, Oracle, PostgreSQL, DB2, Sybase, SQL Server (the same as JDBC) are supported by [MyBatis 3](https://mybatis.org/mybatis-3/) | +| [Hutool Adapter](https://github.com/mapleafgo/jcasbin-extra) | ORM | [@mapleafgo](https://github.com/mapleafgo) | ✅ | MySQL, Oracle, PostgreSQL, SQLite are supported by [Hutool](https://github.com/looly/hutool) | +| [DynamoDB Adapter](https://github.com/jcasbin/dynamodb-adapter) | NoSQL | Casbin | ❌ | For [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) | + + +| Adapter | Type | Author | AutoSave | Description | +| ----------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [Filtered File Adapter (built-in)](https://casbin.org/docs/en/policy-subset-loading) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files with policy subset loading support | +| [String Adapter (built-in)](https://github.com/casbin/node-casbin/blob/master/src/persist/stringAdapter.ts) | String | [@calebfaruki](https://github.com/calebfaruki) | ❌ | For String | +| [Basic Adapter](https://github.com/node-casbin/basic-adapter) | Native ORM | Casbin | ✅ | pg, mysql, mysql2, sqlite3, oracledb, mssql are supported by the adapter itself | +| [Sequelize Adapter](https://github.com/node-casbin/sequelize-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, SQLite, Microsoft SQL Server are supported by [Sequelize](https://github.com/sequelize/sequelize) | +| [TypeORM Adapter](https://github.com/node-casbin/typeorm-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, MariaDB, SQLite, MS SQL Server, Oracle, WebSQL, MongoDB are supported by [TypeORM](https://github.com/typeorm/typeorm) | +| [Mongoose Adapter](https://github.com/node-casbin/mongoose-adapter) | ORM | [elastic.io](https://github.com/elasticio) and Casbin | ✅ | MongoDB is supported by [Mongoose](https://mongoosejs.com/) | +| [Knex Adapter](https://github.com/knex/casbin-knex-adapter) | ORM | [@sarneeh](https://github.com/sarneeh) and [knex](https://github.com/knex) | ✅ | MSSQL, MySQL, PostgreSQL, SQLite3, Oracle are supported by [Knex.js](https://knexjs.org/) | +| [Objection.js Adapter](https://github.com/willsoto/casbin-objection-adapter) | ORM | [@willsoto](https://github.com/willsoto) | ✅ | MSSQL, MySQL, PostgreSQL, SQLite3, Oracle are supported by [Objection.js](https://vincit.github.io/objection.js/) | +| [Node MongoDB Native Adapter](https://github.com/juicycleff/casbin-mongodb-adapter) | NoSQL | [@juicycleff](https://github.com/juicycleff) | ✅ | For [Node MongoDB Native](https://mongodb.github.io/node-mongodb-native/) | +| [DynamoDB Adapter](https://github.com/fospitia/casbin-dynamodb-adapter) | NoSQL | [@fospitia](https://github.com/fospitia) | ✅ | For [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) | +| [Node PostgreSQL Native Adapter](https://github.com/touchifyapp/casbin-pg-adapter) | SQL | [@touchifyapp](https://github.com/touchifyapp) | ✅ | PostgreSQL adapter with advanced policy subset loading support and improved performances built with [node-postgres](https://node-postgres.com/). | +| [Couchbase Adapter](https://github.com/MarkMYoung/casbin-couchbase-adapter) | NoSQL | [@MarkMYoung](https://github.com/MarkMYoung) | ✅ | For [Couchbase](https://www.couchbase.com/) | +| [Redis Adapter](https://github.com/NandaKishorJeripothula/node-casbin-redis-adapter) | KV store | [@NandaKishorJeripothula](https://github.com/NandaKishorJeripothula) | ❌ | For [Redis](https://redis.io/) | + + +| Adapter | Type | Author | AutoSave | Description | +| ------------------------------------------------------------------------------------ | -------- | ------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [Database Adapter](https://github.com/php-casbin/database-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, SQLite, Microsoft SQL Server are supported by [techone/database](https://github.com/techoner/database) | +| [Zend Db Adapter](https://github.com/php-casbin/zend-db-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, SQLite, Oracle, IBM DB2, Microsoft SQL Server, Other PDO Driver are supported by [zend-db](https://docs.zendframework.com/zend-db/) | +| [Doctrine DBAL Adapter(Recommend)](https://github.com/php-casbin/dbal-adapter) | ORM | Casbin | ✅ | Powerful PHP database abstraction layer ([DBAL](https://github.com/doctrine/dbal)) with many features for database schema introspection and management. | +| [Medoo Adapter](https://github.com/php-casbin/medoo-adapter) | ORM | Casbin | ✅ | [Medoo](https://github.com/catfan/Medoo) is a lightweight PHP Database Framework to Accelerate Development, supports all SQL databases, including `MySQL`, `MSSQL`, `SQLite`, `MariaDB`, `PostgreSQL`, `Sybase`, `Oracle` and more. | +| [Redis Adapter](https://github.com/nsnake/CasbinAdapter-Redis-Adapter) | KV store | [@nsnake](https://github.com/nsnake) | ❌ | For [Redis](https://redis.io/) | + + +| Adapter | Type | Author | AutoSave | Description | +| ------------------------------------------------------------------------------------ | ----- | ------------------------------------------------------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [SQLAlchemy Adapter](https://github.com/pycasbin/sqlalchemy-adapter) | ORM | Casbin | ✅ | PostgreSQL, MySQL, SQLite, Oracle, Microsoft SQL Server, Firebird, Sybase are supported by [SQLAlchemy](https://www.sqlalchemy.org/) | +| [Async Databases Adapter](https://github.com/pycasbin/databases-adapter) | ORM | Casbin | ✅ | PostgreSQL, MySQL, SQLite, Oracle, Microsoft SQL Server, Firebird, Sybase are supported by [Databases](https://www.encode.io/databases/) | +| [Peewee Adapter](https://github.com/shblhy/peewee-adapter) | ORM | [@shblhy](https://github.com/shblhy) | ✅ | PostgreSQL, MySQL, SQLite are supported by [Peewee](http://docs.peewee-orm.com/) | +| [MongoEngine Adapter](https://github.com/zhangbailong945/mongoengine_adapter) | ORM | [@zhangbailong945](https://github.com/zhangbailong945) | ❌ | MongoDB is supported by [MongoEngine](http://mongoengine.org/) | +| [Couchbase Adapter](https://github.com/ScienceLogic/casbin-couchbase-adapter) | NoSQL | [ScienceLogic](https://github.com/ScienceLogic) | ✅ (without `remove_filtered_policy()`) | For [Couchbase](https://www.couchbase.com/) | +| [DynamoDB Adapter](https://github.com/abqadeer/python-dycasbin) | NoSQL | [@abqadeer](https://github.com/abqadeer/) | ✅ | For [DynamoDB](https://aws.amazon.com/dynamodb/) | +| [Pymongo Adapter](https://github.com/pycasbin/pymongo-adapter) | ORM | Casbin | ❌ | MongoDB is supported by [Pymongo](https://pypi.org/project/pymongo/) | + + +| Adapter | Type | Author | AutoSave | Description | +| ------------------------------------------------------------------------------------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [EF Adapter](https://github.com/casbin-net/EF-Adapter) | ORM | Casbin | ❌ | MySQL, PostgreSQL, SQLite, Microsoft SQL Server, Oracle, DB2, etc. are supported by [Entity Framework 6](https://docs.microsoft.com/en-us/ef/ef6/) | +| [EFCore Adapter](https://github.com/casbin-net/EFCore-Adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, SQLite, Microsoft SQL Server, Oracle, DB2, etc. are supported by [Entity Framework Core](https://docs.microsoft.com/en-us/ef/core/) | + + +| Adapter | Type | Author | AutoSave | Description | +| ------------------------------------------------------------------------------------ | ------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [Diesel Adapter](https://github.com/casbin-rs/diesel-adapter) | ORM | Casbin | ✅ | [SQLite, PostgreSQL, MySQL](https://github.com/diesel-rs/diesel/blob/master/guide_drafts/backend_installation.md) are supported by [Diesel](http://diesel.rs/) | +| [Sqlx Adapter](https://github.com/casbin-rs/sqlx-adapter) | ORM | Casbin | ✅ | PostgreSQL, MySQL are supported by [Sqlx](https://github.com/launchbadge/sqlx) with fully asynchronous operation | +| [YAML Adapter](https://github.com/casbin-rs/yaml-adapter) | String | Casbin | ✅ | For [YAML](https://yaml.org/) | + + + +:::note +1. If `casbin.NewEnforcer()` is called with an explicit or implicit adapter, the policy will be loaded automatically. +2. You can call `e.LoadPolicy()` to reload the policy rules from the storage. +3. If the adapter does not support the `Auto-Save` feature, The policy rules cannot be automatically saved back to the storage when you add or remove policies. You have to call `SavePolicy()` manually to save all policy rules. ::: + +## Examples + +Here we provide several examples: + +### File adapter (built-in) + +Below shows how to initialize an enforcer from the built-in file adapter: + + + + +```go +import "github.com/casbin/casbin" + +e := casbin.NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv") +``````php +use Casbin\Enforcer; + +$e = new Enforcer('examples/basic_model.conf', 'examples/basic_policy.csv'); +``````rust +use casbin::prelude::*; + +let mut e = Enforcer::new("examples/basic_model.conf", "examples/basic_policy.csv").await?; +```This is the same with:```go +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) +``````php +use Casbin\Enforcer; +use Casbin\Persist\Adapters\FileAdapter; + +$a = new FileAdapter('examples/basic_policy.csv'); +$e = new Enforcer('examples/basic_model.conf', $a); +``````rust +use casbin::prelude::*; + +let a = FileAdapter::new("examples/basic_policy.csv"); +let e = Enforcer::new("examples/basic_model.conf", a).await?; +```### [MySQL adapter](https://github.com/casbin/mysql-adapter) + +Below shows how to initialize an enforcer from MySQL database. it connects to a MySQL DB on 127.0.0.1:3306 with root and blank password.```go +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) +``````rust +// https://github.com/casbin-rs/diesel-adapter +// make sure you activate feature `mysql` + +use casbin::prelude::*; +use diesel_adapter::{ConnOptions, DieselAdapter}; + +let mut conn_opts = ConnOptions::default(); +conn_opts + .set_hostname("127.0.0.1") + .set_port(3306) + .set_host("127.0.0.1:3306") // overwrite hostname, port config + .set_database("casbin") + .set_auth("casbin_rs", "casbin_rs"); + +let a = DieselAdapter::new(conn_opts)?; +let mut e = Enforcer::new("examples/basic_model.conf", a).await?; +``````php +// https://github.com/php-casbin/dbal-adapter + +use Casbin\Enforcer; +use CasbinAdapter\DBAL\Adapter as DatabaseAdapter; + +$config = [ + // Either 'driver' with one of the following values: + // pdo_mysql,pdo_sqlite,pdo_pgsql,pdo_oci (unstable),pdo_sqlsrv,pdo_sqlsrv, + // mysqli,sqlanywhere,sqlsrv,ibm_db2 (unstable),drizzle_pdo_mysql + 'driver' => 'pdo_mysql', + 'host' => '127.0.0.1', + 'dbname' => 'test', + 'user' => 'root', + 'password' => '', + 'port' => '3306', +]; + +$a = DatabaseAdapter::newAdapter($config); +$e = new Enforcer('examples/basic_model.conf', $a); +```## Use your own storage adapter + +You can use your own adapter like below: + +```go +import ( + "github.com/casbin/casbin" + "github.com/your-username/your-repo" +) + +a := yourpackage.NewAdapter(params) +e := casbin.NewEnforcer("examples/basic_model.conf", a) +``` + +## Load/Save at run-time + +You may also want to reload the model, reload the policy or save the policy after initialization: + +```go +// 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 + +There is a feature called `Auto-Save` for adapters. When an adapter supports `Auto-Save`, it means it can support adding a single policy rule to the storage, or removing a single policy rule from the storage. This is unlike `SavePolicy()`, because the latter will delete all policy rules in the storage and save all policy rules from Casbin enforcer to the storage. So it may suffer performance issue when the number of policy rules is large. + +When the adapter supports `Auto-Save`, you can switch this option via `Enforcer.EnableAutoSave()` function. The option is enabled by default (if the adapter supports it). + +:::note +1. The `Auto-Save` feature is optional. An adapter can choose to implement it or not. +2. `Auto-Save` only works for a Casbin enforcer when the adapter the enforcer uses supports it. +3. See the `AutoSave` column in the above adapter list to see if `Auto-Save` is supported by an adapter. ::: + +Here's an example about how to use `Auto-Save`: + +```go +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(...) +``` + +For more examples, please see: https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go + +### How to write an adapter + +All adapters should implement the [Adapter](https://github.com/casbin/casbin/blob/master/persist/adapter.go) interface by providing at least two mandatory methods:`LoadPolicy(model model.Model) error` and `SavePolicy(model model.Model) error`. + +The other three functions are optional. They should be implemented if the adapter supports the `Auto-Save` feature. + +| Method | Type | Description | +| ---------------------- | --------- | ---------------------------------------------------------- | +| LoadPolicy() | mandatory | Load all policy rules from the storage | +| SavePolicy() | mandatory | Save all policy rules to the storage | +| AddPolicy() | optional | Add a policy rule to the storage | +| RemovePolicy() | optional | Remove a policy rule from the storage | +| RemoveFilteredPolicy() | optional | Remove policy rules that match the filter from the storage | + +:::note If an adapter doesn't support `Auto-Save`, it should provide an empty implementation for the three optional functions. Here's an example for Golang: ::: + +```go +// 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 will ignore the `not implemented` error when calling these three optional functions. + +### Who is responsible to create the DB? + +As a convention, the adapter should be able to automatically create a database named `casbin` if it doesn't exist and use it for policy storage. Please use the Xorm adapter as a reference implementation: https://github.com/casbin/xorm-adapter diff --git a/website/translated_docs/fr-FR/AdminPortal.md b/website/translated_docs/fr-FR/AdminPortal.md new file mode 100644 index 00000000..b9f07f39 --- /dev/null +++ b/website/translated_docs/fr-FR/AdminPortal.md @@ -0,0 +1,41 @@ +--- +id: admin-portal +title: Admin Portal +--- + +We provide a [web-based portal called Casdoor](https://github.com/casbin/casdoor) for model management and policy management: + +![model editor](https://hsluoyz.github.io/casbin/ui_model_editor.png) + +![policy editor](https://hsluoyz.github.io/casbin/ui_policy_editor.png) + +There are also 3rd-party admin portal projects that use Casbin as authorization engine. You can get started to build your own Casbin service based on these projects. + + + + +| Project | Author | Frontend | Backend | Description | +| ---------------------------------------------------------- | -------------------------------------------- | ------------------ | ------- | ---------------------------------------------------------------- | +| [Casdoor](https://github.com/casbin/casdoor) | Casbin | React + Ant Design | Beego | Based on Beego + XORM + React | +| [gin-vue-admin](https://github.com/piexlmax/gin-vue-admin) | [@piexlmax](https://github.com/piexlmax) | Vue + Element UI | Gin | Based on Gin + GORM + Vue | +| [gin-admin](https://github.com/LyricTian/gin-admin) | [@LyricTian](https://github.com/LyricTian) | React + Ant Design | Gin | RBAC scaffolding based on Gin + GORM + Casbin + Ant Design React | +| [go-admin](https://github.com/hequan2017/go-admin) | [@hequan2017](https://github.com/hequan2017) | None | Gin | Go RESTful API gateway based on Gin + GORM + JWT + RBAC (Casbin) | +| [zeus-admin](https://github.com/bullteam/zeus-admin) | [bullteam](https://github.com/bullteam) | Vue + Element UI | Gin | Unified Permission management platform based on JWT + Casbin | +| [IrisAdminApi](https://github.com/snowlyg/IrisAdminApi) | [@snowlyg](https://github.com/snowlyg) | Vue + Element UI | Iris | Backend API based on Iris + Casbin | + + +| Project | Author | Frontend | Backend | Description | +| ---------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------- | ------- | ------------------------------------------------------------------------------------------------- | +| [Casbin-Role-Mgt-Dashboard-RBAC](https://github.com/alikhan866/Casbin-Role-Mgt-Dashboard-RBAC) | [@alikhan866](https://github.com/alikhan866) | React + Material UI | Express | Beginner friendly RBAC management with Enforcer integration to check enforcement result on the go | + + +| Project | Author | Frontend | Backend | Description | +| ---------------------------------------------------------------------------- | ------ | --------- | ------- | --------------------- | +| [openstack-policy-editor](https://github.com/casbin/openstack-policy-editor) | Casbin | Bootstrap | Django | The Web UI for Casbin | + + +| Project | Author | Frontend | Backend | Description | +| -------------------------------------------- | ---------------------------------------- | -------- | -------- | ------------------------------------------------------ | +| [Tadmin](https://github.com/techoner/tadmin) | [@techoner](https://github.com/techoner) | AmazeUI | ThinkPHP | Non-intrusive backend framework based on ThinkPHP 5.1+ | + + diff --git a/website/translated_docs/fr-FR/Adopters.md b/website/translated_docs/fr-FR/Adopters.md new file mode 100644 index 00000000..675ce8bb --- /dev/null +++ b/website/translated_docs/fr-FR/Adopters.md @@ -0,0 +1,50 @@ +--- +id: adopters +title: Our Adopters +--- + +## Direct integration + + + + +| Name | Description | Model | Policy | +| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| [VMware Harbor](https://github.com/goharbor/harbor) | VMware's open source trusted cloud native registry project that stores, signs, and scans content. | [Code](https://github.com/goharbor/harbor/blob/master/src/pkg/permission/evaluator/rbac/casbin.go#L24-L44) | [Beego ORM](https://github.com/goharbor/harbor/blob/master/src/replication/dao/policy.go#L24-L26) | +| [Intel RMD](https://github.com/intel/rmd) | Intel's resource management daemon. | [.conf](https://github.com/intel/rmd/blob/master/etc/rmd/acl/url/model.conf) | [.csv](https://github.com/intel/rmd/blob/master/etc/rmd/acl/url/policy.csv) | +| [VMware Dispatch](https://github.com/vmware/dispatch) | A framework for deploying and managing serverless style applications. | [Code](https://github.com/vmware/dispatch/blob/master/pkg/identity-manager/handlers.go#L46-L55) | [Code](https://github.com/vmware/dispatch/blob/master/pkg/identity-manager/handlers_test.go#L35-L45) | +| [Skydive](https://github.com/skydive-project/skydive) | An open source real-time network topology and protocols analyzer. | [Code](https://github.com/skydive-project/skydive/blob/master/config/config.go#L136-L140) | [.csv](https://github.com/skydive-project/skydive/blob/master/rbac/policy.csv) | +| [Zenpress](https://github.com/insionng/zenpress) | A CMS system written in Golang. | [.conf](https://github.com/insionng/zenpress/blob/master/content/config/rbac_model.conf) | [Gorm](https://github.com/insionng/zenpress/blob/master/model/user.go#L53-L77) | +| [Argo CD](https://github.com/argoproj/argo-cd) | GitOps continuous delivery for Kubernetes. | [.conf](https://github.com/argoproj/argo-cd/blob/master/util/rbac/model.conf) | [.csv](https://github.com/argoproj/argo-cd/blob/master/util/rbac/builtin-policy.csv) | +| [Muxi Cloud](https://github.com/muxiyun/Mae) | PaaS of Muxi Cloud, an easier way to manage Kubernetes cluster. | [.conf](https://github.com/muxiyun/Mae/blob/master/conf/casbinmodel.conf) | [Code](https://github.com/muxiyun/Mae/blob/master/pkg/casbin/initPolicy.go#L21-L95) | +| [EngineerCMS](https://github.com/3xxx/EngineerCMS) | A CMS to manage knowledge for engineers. | [.conf](https://github.com/3xxx/EngineerCMS/blob/master/conf/rbac_model.conf) | [SQLite](https://github.com/3xxx/EngineerCMS/blob/master/database/engineer.db) | +| [Cyber Auth API](https://github.com/CyberlifeCN/cyber-auth-api) | A Golang authentication API project. | [.conf](https://github.com/CyberlifeCN/cyber-auth-api/blob/master/conf/authz_model.conf) | [.csv](https://github.com/CyberlifeCN/cyber-auth-api/blob/master/conf/authz_policy.csv) | +| [IRIS Community](https://github.com/irisnet/iris-community) | Website for IRIS Community Activities. | [.conf](https://github.com/irisnet/iris-community/blob/master/authz/authz_model.conf) | [.csv](https://github.com/irisnet/iris-community/blob/master/authz/authz_policy.csv) | +| [Metadata DB](https://github.com/Bnei-Baruch/mdb) | BB archive metadata database. | [.conf](https://github.com/Bnei-Baruch/mdb/blob/master/data/permissions_model.conf) | [.csv](https://github.com/Bnei-Baruch/mdb/blob/master/data/permissions_policy.csv) | +| [Qilin API](https://github.com/ProtocolONE/qilin.api) | ProtocolONE's licenses managemen tool for game content. | [Code](https://github.com/ProtocolONE/rbac/blob/master/model.go) | [.csv](https://github.com/ProtocolONE/rbac/tree/master/conf) | +| [Devtron Labs](https://github.com/devtron-labs/devtron) | Software Delivery Workflow For Kubernetes. | [.conf](https://github.com/devtron-labs/devtron/blob/main/auth_model.conf) | [Xorm](https://github.com/devtron-labs/devtron/blob/main/internal/casbin/Adapter.go) | + + +| Name | Description | Model | Policy | +| ---------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | +| [lighty.io](https://github.com/PantheonTechnologies/lighty-core) | OpenDaylight's solution for SDN controller. | [README](https://github.com/PantheonTechnologies/lighty-core/blob/6f2ceaae6a68e08c96d14d2fa8ee060ad9f61606/lighty-examples/lighty-controller-springboot-netconf/README.md#security) | N/A | + + +| Name | Description | Model | Policy | +| ------------------------------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| [Notadd](https://github.com/notadd/notadd) | A micro-service development architecture based on Nest.js. | [.conf](https://github.com/notadd/notadd/blob/e58d0a0cf5d691c3fe20170e94cdd8e2c627abd4/apps/nest-upms/src/casbin/rbac_model.conf) | [DB adapter](https://github.com/notadd/notadd/blob/e58d0a0cf5d691c3fe20170e94cdd8e2c627abd4/apps/nest-upms/src/casbin/adapter.ts) | + + +| Name | Description | Model | Policy | +| --------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------- | ------ | +| [dtrace](https://github.com/EduScaled/dtrace) | EduScaled's tracing system. | [Commit](https://github.com/EduScaled/dtrace/commit/6e8d6b52ec2fa120e8ad63f84a4aecc3eae14c02) | N/A | + + + + +## Integration via plugin + +| Name | Description | Plugin | Model | Policy | +| ----------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| [Docker](https://github.com/docker/docker) | The world's leading software container platform | [casbin-authz-plugin](https://github.com/casbin/casbin-authz-plugin) ([recommended by Docker](https://docs.docker.com/engine/extend/legacy_plugins/#authorization-plugins)) | [.conf](https://github.com/casbin/casbin-authz-plugin/blob/master/examples/basic_model.conf) | [.csv](https://github.com/casbin/casbin-authz-plugin/blob/master/examples/basic_policy.csv) | +| [Gobis](https://github.com/orange-cloudfoundry/gobis) | [Orange](https://github.com/orange-cloudfoundry)'s lightweight API Gateway written in go | [casbin](https://github.com/orange-cloudfoundry/gobis-middlewares/tree/master/casbin) | [Code](https://github.com/orange-cloudfoundry/gobis-middlewares/blob/master/casbin/model.go#L52-L65) | [Request](https://github.com/orange-cloudfoundry/gobis-middlewares/blob/master/casbin/adapter.go#L46-L64) | diff --git a/website/translated_docs/fr-FR/Benchmark.md b/website/translated_docs/fr-FR/Benchmark.md new file mode 100644 index 00000000..565c4174 --- /dev/null +++ b/website/translated_docs/fr-FR/Benchmark.md @@ -0,0 +1,26 @@ +--- +id: benchmark +title: Benchmarks +--- + +The overhead of policy enforcement is benchmarked in [model_b_test.go](https://github.com/casbin/casbin/blob/master/model_b_test.go). The testbed is: + +``` +Intel(R) Core(TM) i7-6700HQ CPU @ 2.60GHz, 2601 Mhz, 4 Core(s), 8 Logical Processor(s) +``` + +The benchmarking result of `go test -bench=. -benchmem` is as follows (op = an `Enforce()` call, ms = millisecond, KB = kilo bytes): + +| Test case | Rule size | Time overhead (ms/op) | Memory overhead (KB) | +| ------------------------- | ---------------------------------------- | --------------------- | -------------------- | +| ACL | 2 rules (2 users) | 0.015493 | 5.649 | +| RBAC | 5 rules (2 users, 1 role) | 0.021738 | 7.522 | +| RBAC (small) | 1100 rules (1000 users, 100 roles) | 0.164309 | 80.620 | +| RBAC (medium) | 11000 rules (10000 users, 1000 roles) | 2.258262 | 765.152 | +| RBAC (large) | 110000 rules (100000 users, 10000 roles) | 23.916776 | 7,606 | +| RBAC with resource roles | 6 rules (2 users, 2 roles) | 0.021146 | 7.906 | +| RBAC with domains/tenants | 6 rules (2 users, 1 role, 2 domains) | 0.032696 | 10.755 | +| ABAC | 0 rule (0 user) | 0.007510 | 2.328 | +| RESTful | 5 rules (3 users) | 0.045398 | 91.774 | +| Deny-override | 6 rules (2 users, 1 role) | 0.023281 | 8.370 | +| Priority | 9 rules (2 users, 2 roles) | 0.016389 | 5.313 | diff --git a/website/translated_docs/fr-FR/Dispatchers.md b/website/translated_docs/fr-FR/Dispatchers.md new file mode 100644 index 00000000..27c9c5b0 --- /dev/null +++ b/website/translated_docs/fr-FR/Dispatchers.md @@ -0,0 +1,23 @@ +--- +id: dispatchers +title: Dispatchers +--- + +Dispatcher provide a way to synchronize incremental changes of policy. It should be based on consistency algorithms such as raft to ensure the consistency of all enforcer instances. Through dispatcher users can easily establish distributed clusters. + +The dispatcher's method is divided into two parts. The first is the method combined with casbin. These methods should be called inside casbin. Users can use the more complete api provided by casbin itself. + +The other part is the method defined by the dispatcher itself, including the dispatcher initialization method, and different functions provided by different algorithms, such as dynamic membership, config changes etc. + +:::note we hope dispatcher just ensure the consistency of Casbin enforcer at runtime. So if the policy is inconsistent when initialization, the dispatcher will not work properly. Users need to ensure that the state of all instances is consistent before using dispatcher. ::: + +A complete list of Casbin dispatchers is provided as below. Any 3rd-party contribution on a new dispatcher is welcomed, please inform us and we will put it in this list:) + + + +| Dispatcher | Type | Author | Description | +| ------------------------------------------------------------- | ---- | ------ | -------------------------------------------------------------------- | +| [Etcd Raft Dispatcher](https://github.com/casbin/casbin-raft) | raft | Casbin | Dispatcher based on [etcd/raft](https://github.com/coreos/etcd/raft) | + + + diff --git a/website/translated_docs/fr-FR/Function.md b/website/translated_docs/fr-FR/Function.md new file mode 100644 index 00000000..f28c7937 --- /dev/null +++ b/website/translated_docs/fr-FR/Function.md @@ -0,0 +1,73 @@ +--- +id: function +title: Function +--- + +## Functions in matchers + +You can even specify functions in a matcher to make it more powerful. You can use the built-in functions or specify your own function. All built-in functions take such a format(except `keyGet` and `keyGet2`): + +```C +bool function_name(string arg1, string arg2) +``` + +It returns whether `arg1` matches `arg2`. + +`keyGet` and `keyGet2` will return the string which matching the wildcard, and return `""` if nothing was matched. + +The supported built-in functions are: + +| Function | arg1 | arg2 | Example | +| ---------- | ------------------------------------------ | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| keyMatch | a URL path like `/alice_data/resource1` | a URL path or a `*` pattern like `/alice_data/*` | [keymatch_model.conf](https://github.com/casbin/casbin/blob/master/examples/keymatch_model.conf)/[keymatch_policy.csv](https://github.com/casbin/casbin/blob/master/examples/keymatch_policy.csv) | +| keyGet | a URL path like `/alice_data/resource1` | a URL path or a `*` pattern like `/alice_data/*` | [keyget_model.conf](https://github.com/casbin/casbin/blob/master/examples/keyget_model.conf)/[keymatch_policy.csv](https://github.com/casbin/casbin/blob/master/examples/keymatch_policy.csv) | +| keyMatch2 | a URL path like `/alice_data/resource1` | a URL path or a `:` pattern like `/alice_data/:resource` | [keymatch2_model.conf](https://github.com/casbin/casbin/blob/master/examples/keymatch2_model.conf)/[keymatch2_policy.csv](https://github.com/casbin/casbin/blob/master/examples/keymatch2_policy.csv) | +| keyGet2 | a URL path like `/alice_data/resource1` | a URL path or `:` pattern like `/alice_data/:resource` | [keyget2_model.conf](https://github.com/casbin/casbin/blob/master/examples/keyget2_model.conf)/[keymatch2_policy.csv](https://github.com/casbin/casbin/blob/master/examples/keymatch2_policy.csv) | +| keyMatch3 | a URL path like `/alice_data/resource1` | a URL path or a `{}` pattern like `/alice_data/{resource}` | | +| keyMatch4 | a URL path like `/alice_data/123/book/123` | a URL path or a `{}` pattern like `/alice_data/{id}/book/{id}` | | +| regexMatch | any string | a regular expression pattern | [keymatch_model.conf](https://github.com/casbin/casbin/blob/master/examples/keymatch_model.conf)/[keymatch_policy.csv](https://github.com/casbin/casbin/blob/master/examples/keymatch_policy.csv) | +| ipMatch | an IP address like `192.168.2.123` | an IP address or a CIDR like `192.168.2.0/24` | [ipmatch_model.conf](https://github.com/casbin/casbin/blob/master/examples/ipmatch_model.conf)/[ipmatch_policy.csv](https://github.com/casbin/casbin/blob/master/examples/ipmatch_policy.csv) | + +See details for above functions at: https://github.com/casbin/casbin/blob/master/util/builtin_operators_test.go + +## How to add a customized function + +First prepare your function. It takes several parameters and return a bool: + +```go +func KeyMatch(key1 string, key2 string) bool { + i := strings.Index(key2, "*") + if i == -1 { + return key1 == key2 + } + + if len(key1) > i { + return key1[:i] == key2[:i] + } + return key1 == key2[:i] +} +``` + +Then wrap it with `interface{}` types: + +```go +func KeyMatchFunc(args ...interface{}) (interface{}, error) { + name1 := args[0].(string) + name2 := args[1].(string) + + return (bool)(KeyMatch(name1, name2)), nil +} +``` + +At last, register the function to the Casbin enforcer: + +```go +e.AddFunction("my_func", KeyMatchFunc) +``` + +Now, you can use the function in your model CONF like this: + +```ini +[matchers] +m = r.sub == p.sub && my_func(r.obj, p.obj) && r.act == p.act +``` diff --git a/website/translated_docs/fr-FR/GetStarted.md b/website/translated_docs/fr-FR/GetStarted.md new file mode 100644 index 00000000..921c6334 --- /dev/null +++ b/website/translated_docs/fr-FR/GetStarted.md @@ -0,0 +1,365 @@ +--- +id: get-started +title: Get Started +--- + +## Installation + + + + +``` +go get github.com/casbin/casbin/v2 +``` + + +For Maven: + +``` + + org.casbin + jcasbin + 1.6.0 + +``` + + +``` +# NPM +npm install casbin --save + +# Yarn +yarn add casbin +``` + + +Require this package in the `composer.json` of your project. This will download the package: + +``` +composer require casbin/casbin +``` + + +``` +pip install casbin +``` + + +``` +dotnet add package Casbin.NET +``` + + +``` +cargo install cargo-edit +cargo add casbin + +// If you use async-std as async executor +cargo add async-std + +// If you use tokio as async executor +cargo add tokio // make sure you activate its `macros` feature +``` + + +Casbin4D comes in a package (currently for Delphi 10.3 Rio) and you can install it in the IDE. However, there are no visual components which means that you can use the units independently of packages. Just import the units in your project (assuming you do not mind the number of them). + + + +## New a Casbin enforcer + +The new a Casbin enforcer must provide a [Model](supported-models) and a [Adapter](adapters). + +Casbin has a [FileAdapter](adapters#file-adapter-built-in), see [Adapter](adapters) from more Adapter. + +- Use the Model file and default [FileAdapter](adapters#file-adapter-built-in): + + + + +```go +import "github.com/casbin/casbin/v2" + +e, err := casbin.NewEnforcer("path/to/model.conf", "path/to/policy.csv") +``` + + +```java +import org.casbin.jcasbin.main.Enforcer; + +Enforcer e = new Enforcer("path/to/model.conf", "path/to/policy.csv"); +``` + + +```js +import { newEnforcer } from 'casbin'; + +const e = await newEnforcer('path/to/model.conf', 'path/to/policy.csv'); +``` + + +```php +require_once './vendor/autoload.php'; + +use Casbin\Enforcer; + +$e = new Enforcer("path/to/model.conf", "path/to/policy.csv"); +``` + + +```python +import casbin + +e = casbin.Enforcer("path/to/model.conf", "path/to/policy.csv") +``` + + +```csharp +using NetCasbin; + +var e = new Enforcer("path/to/model.conf", "path/to/policy.csv"); +``` + + +```delphi +var + casbin: ICasbin; +begin + casbin := TCasbin.Create('path/to/model.conf', 'path/to/policy.csv'); + ... +end +``` + + +```rust +use casbin::prelude::*; + +// If you use async_td as async executor +#[cfg(feature = "runtime-async-std")] +#[async_std::main] +async fn main() -> Result<()> { + let mut e = Enforcer::new("path/to/model.conf", "path/to/policy.csv").await?; + Ok(()) +} + +// If you use tokio as async executor +#[cfg(feature = "runtime-tokio")] +#[tokio::main] +async fn main() -> Result<()> { + let mut e = Enforcer::new("path/to/model.conf", "path/to/policy.csv").await?; + Ok(()) +} +``` + + +- Use the Model text with other Adapter: + + + + +```go +import ( + "log" + + "github.com/casbin/casbin/v2" + "github.com/casbin/casbin/v2/model" + xormadapter "github.com/casbin/xorm-adapter/v2" + _ "github.com/go-sql-driver/mysql" +) + +// Initialize a Xorm adapter with MySQL database. +a, err := xormadapter.NewAdapter("mysql", "mysql_username:mysql_password@tcp(127.0.0.1:3306)/casbin") +if err != nil { + log.Fatalf("error: adapter: %s", err) +} + +m, err := model.NewModelFromString(` +[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 +`) +if err != nil { + log.Fatalf("error: model: %s", err) +} + +e, err := casbin.NewEnforcer(m, a) +if err != nil { + log.Fatalf("error: enforcer: %s", err) +} +``` + + +### Check permissions + +Add an enforcement hook into your code right before the access happens: + + + + +```go +sub := "alice" // the user that wants to access a resource. +obj := "data1" // the resource that is going to be accessed. +act := "read" // the operation that the user performs on the resource. + +ok, err := e.Enforce(sub, obj, act) + +if err != nil { + // handle err +} + +if ok == true { + // permit alice to read data1 +} else { + // deny the request, show an error +} + +// You could use BatchEnforce() to enforce some requests in batches. +// This method returns a bool slice, and this slice's index corresponds to the row index of the two-dimensional array. +// e.g. results[0] is the result of {"alice", "data1", "read"} +results, err := e.BatchEnforce([][]interface{}{{"alice", "data1", "read"}, {"bob", "data2", "write"}, {"jack", "data3", "read"}}) +``` + + +```java +String sub = "alice"; // the user that wants to access a resource. +String obj = "data1"; // the resource that is going to be accessed. +String act = "read"; // the operation that the user performs on the resource. + +if (e.enforce(sub, obj, act) == true) { + // permit alice to read data1 +} else { + // deny the request, show an error +} +``` + + +```js +const sub = 'alice'; // the user that wants to access a resource. +const obj = 'data1'; // the resource that is going to be accessed. +const act = 'read'; // the operation that the user performs on the resource. + +if ((await e.enforce(sub, obj, act)) === true) { + // permit alice to read data1 +} else { + // deny the request, show an error +} +``` + + +```php +$sub = "alice"; // the user that wants to access a resource. +$obj = "data1"; // the resource that is going to be accessed. +$act = "read"; // the operation that the user performs on the resource. + +if ($e->enforce($sub, $obj, $act) === true) { + // permit alice to read data1 +} else { + // deny the request, show an error +} +``` + + +```python +sub = "alice" # the user that wants to access a resource. +obj = "data1" # the resource that is going to be accessed. +act = "read" # the operation that the user performs on the resource. + +if e.enforce(sub, obj, act): + # permit alice to read data1 + pass +else: + # deny the request, show an error + pass +``` + + +```csharp +var sub = "alice"; # the user that wants to access a resource. +var obj = "data1"; # the resource that is going to be accessed. +var act = "read"; # the operation that the user performs on the resource. + +if (await e.EnforceAsync(sub, obj, act)) +{ + // permit alice to read data1 +} +else +{ + // deny the request, show an error +} +``` + + +```delphi +if casbin.enforce(['alice,data1,read']) then + // Alice is super happy as she can read data1 +else + // Alice is sad +``` + + +```rust + let sub = "alice"; // the user that wants to access a resource. + let obj = "data1"; // the resource that is going to be accessed. + let act = "read"; // the operation that the user performs on the resource. + + if e.enforce((sub, obj, act)).await? { + // permit alice to read data1 + } else { + // error occurs + } +``` + + + +Casbin also provides API for permission management at run-time. For example, You can get all the roles assigned to a user as below: + + + + +```go +roles := e.GetRolesForUser("alice") +``` + + +```java +Roles roles = e.getRolesForUser("alice"); +``` + + +```js +const roles = await e.getRolesForUser('alice'); +``` + + +```php +$roles = $e->getRolesForUser("alice"); +``` + + +```python +roles = e.get_roles_for_user("alice") +``` + + +```csharp +var roles = e.GetRolesForUser("alice"); +``` + + +```delphi +``` + + +```rust +let roles = e.get_roles_for_user("alice"); +```See [Management API](/docs/en/management-api) and [RBAC API](/docs/en/rbac-api) for more usage. + +Please refer to the test cases for more usage. diff --git a/website/translated_docs/fr-FR/HowItWorks.md b/website/translated_docs/fr-FR/HowItWorks.md new file mode 100644 index 00000000..a7eeadc7 --- /dev/null +++ b/website/translated_docs/fr-FR/HowItWorks.md @@ -0,0 +1,61 @@ +--- +id: how-it-works +title: How it Works +--- + +In Casbin, an access control model is abstracted into a CONF file based on the **PERM metamodel (Policy, Effect, Request, Matchers)**. So switching or upgrading the authorization mechanism for a project is just as simple as modifying a configuration. You can customize your own access control model by combining the available models. For example, you can get RBAC roles and ABAC attributes together inside one model and share one set of policy rules. + +The most basic and simplest model in Casbin is ACL. ACL's model CONF is: + +```ini +# Request definition +[request_definition] +r = sub, obj, act + +# Policy definition +[policy_definition] +p = sub, obj, act + +# Policy effect +[policy_effect] +e = some(where (p.eft == allow)) + +# Matchers +[matchers] +m = r.sub == p.sub && r.obj == p.obj && r.act == p.act + +``` + +An example policy for ACL model is like: + +``` +p, alice, data1, read +p, bob, data2, write +``` + +It means: + +- alice can read data1 +- bob can write data2 + +We also support multi-line mode by appending '\\' in the end: + +```ini +# Matchers +[matchers] +m = r.sub == p.sub && r.obj == p.obj \ + && r.act == p.act +``` + +Further more, if you are using ABAC, you can try operator `in` like following in Casbin **golang** edition (jCasbin and Node-Casbin are not supported yet): + +```ini +# Matchers +[matchers] +m = r.obj == p.obj && r.act == p.act || r.obj in ('data2', 'data3') +``` + +But you **SHOULD** make sure that the length of the array is **MORE** than **1**, otherwise there will cause it to panic. + +For more operators, you may take a look at [govaluate](https://github.com/Knetic/govaluate) + diff --git a/website/translated_docs/fr-FR/LogError.md b/website/translated_docs/fr-FR/LogError.md new file mode 100644 index 00000000..de720a67 --- /dev/null +++ b/website/translated_docs/fr-FR/LogError.md @@ -0,0 +1,188 @@ +--- +id: log-error +title: Log & Error Handling +--- + +## Logging + +Casbin uses the built-in `log` to print logs to console by default like: + +```log +2017/07/15 19:43:56 [Request: alice, data1, read ---> true] +``` + +The logging is not enabled by default. You can toggle it via `Enforcer.EnableLog()` or the last parameter of `NewEnforcer()`. + +:::note +We already support logging the model, enforce request, role, policy in Golang. You can define your own log for logging Casbin. If you are using Python, pycasbin leverages the default Python logging mechanism. The pycasbin package makes a call to logging.getLogger() to set the logger. No special logging configuration is needed other than initializing the logger in the parent application. If no logging is intitilized within the parent application you will not see any log messages from pycasbin. ::: + +### Use different logger for different enforcer + +Every enforcer could have its own logger to log info, and it could be changed at run-time. + +And you could use a proper logger via the last paramter of `NewEnforcer()`, if you using this way to initialize your enforcer, you needn't use the enabled parameter, cause the priority of the enabled field in logger is higher. + +```go +// Set a default logger as enforcer e1's logger. +// This operation could also be seen as changing the logger of e1 at run-time. +e1.SetLogger(&Log.DefaultLogger{}) + +// Set another logger as enforcer e2's logger. +e2.SetLogger(&YouOwnLogger) + +// Set your logger when initialize enforcer e3. +e3, _ := casbin.NewEnforcer("examples/rbac_model.conf", a, logger) +``` + +#### Supported loggers + +We provide some loggers to help you log information.| Logger | Author | Description | +| ------------------------------------------------------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------- | +| [Defatule logger (built-in)](https://github.com/casbin/casbin/blob/master/log/default_logger.go) | Casbin | The default logger using golang log. | +| [Zap logger](https://github.com/casbin/zap-logger) | Casbin | Using [zap](https://github.com/uber-go/zap), provide json encoded log and you could customize more with your own zap-logger. |#### How to write a logger + +Your logger should implement the [Logger](https://github.com/casbin/casbin/blob/master/log/logger.go#L20) interface. + +| Method | Type | Description | +| ------------ | --------- | ----------------------------------------- | +| EnableLog() | mandatory | Control whether print the message. | +| IsEnabled() | mandatory | Show the current logger's enabled status. | +| LogModel() | mandatory | Log info related to model. | +| LogEnforce() | mandatory | Log info related to enforce. | +| LogRole() | mandatory | Log info related to role. | +| LogPolicy() | mandatory | Log info related to policy. | + + +You can pass your custom `logger` to `Enforcer.SetLogger()`. + +Here is an example about how to customize a logger for Golang: + +```go +import ( + "fmt" + "log" + "strings" +) + +// DefaultLogger is the implementation for a Logger using golang log. +type DefaultLogger struct { + enabled bool +} + +func (l *DefaultLogger) EnableLog(enable bool) { + l.enabled = enable +} + +func (l *DefaultLogger) IsEnabled() bool { + return l.enabled +} + +func (l *DefaultLogger) LogModel(model [][]string) { + if !l.enabled { + return + } + var str strings.Builder + str.WriteString("Model: ") + for _, v := range model { + str.WriteString(fmt.Sprintf("%v\n", v)) + } + + log.Println(str.String()) +} + +func (l *DefaultLogger) LogEnforce(matcher string, request []interface{}, result bool, explains [][]string) { + if !l.enabled { + return + } + + var reqStr strings.Builder + reqStr.WriteString("Request: ") + for i, rval := range request { + if i != len(request)-1 { + reqStr.WriteString(fmt.Sprintf("%v, ", rval)) + } else { + reqStr.WriteString(fmt.Sprintf("%v", rval)) + } + } + reqStr.WriteString(fmt.Sprintf(" ---> %t\n", result)) + + reqStr.WriteString("Hit Policy: ") + for i, pval := range explains { + if i != len(explains)-1 { + reqStr.WriteString(fmt.Sprintf("%v, ", pval)) + } else { + reqStr.WriteString(fmt.Sprintf("%v \n", pval)) + } + } + + log.Println(reqStr.String()) +} + +func (l *DefaultLogger) LogPolicy(policy map[string][][]string) { + if !l.enabled { + return + } + + var str strings.Builder + str.WriteString("Policy: ") + for k, v := range policy { + str.WriteString(fmt.Sprintf("%s : %v\n", k, v)) + } + + log.Println(str.String()) +} + +func (l *DefaultLogger) LogRole(roles []string) { + if !l.enabled { + return + } + + log.Println("Roles: ", roles) +} + +``` + +## Error handling + +Error or panic may happen when you use Casbin for reasons like: + +1. Invalid syntax in model file (.conf). +2. Invalid syntax in policy file (.csv). +3. Custom error from storage adapters, e.g., MySQL fails to connect. +4. Casbin's bug. + +There are five main functions you may need to care about for error or panic: + +| Function | Behavior on error | +| ------------------------------------------------------------------------------ | ----------------- | +| [NewEnforcer()](https://godoc.org/github.com/casbin/casbin#NewEnforcer) | Return error | +| [LoadModel()](https://godoc.org/github.com/casbin/casbin#Enforcer.LoadModel) | Return error | +| [LoadPolicy()](https://godoc.org/github.com/casbin/casbin#Enforcer.LoadPolicy) | Return error | +| [SavePolicy()](https://godoc.org/github.com/casbin/casbin#Enforcer.SavePolicy) | Return error | +| [Enforce()](https://godoc.org/github.com/casbin/casbin#Enforcer.Enforce) | Return error | + +:::note `NewEnforcer()` calls `LoadModel()` and `LoadPolicy()` inside. So you don't have to call the latter two calls when using `NewEnforcer()`. ::: + +## Enable & disable + +The enforcer can be disabled via the `Enforcer.EnableEnforce()` function. When it's disabled, `Enforcer.Enforce()` will always return `true`. Other operations like adding or removing policy is not affected. Here's an example: + +```go +e := casbin.NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv") + +// Will return false. +// By default, the enforcer is enabled. +e.Enforce("non-authorized-user", "data1", "read") + +// Disable the enforcer at run-time. +e.EnableEnforce(false) + +// Will return true for any request. +e.Enforce("non-authorized-user", "data1", "read") + +// Enable the enforcer again. +e.EnableEnforce(true) + +// Will return false. +e.Enforce("non-authorized-user", "data1", "read") +``` diff --git a/website/translated_docs/fr-FR/ManagementAPI.md b/website/translated_docs/fr-FR/ManagementAPI.md new file mode 100644 index 00000000..fd5de5a0 --- /dev/null +++ b/website/translated_docs/fr-FR/ManagementAPI.md @@ -0,0 +1,1655 @@ +--- +id: management-api +title: Management API +--- + +The primitive API that provides full support for Casbin policy management. + +## Reference + +global variable `e` is Enforcer instance. + + + + +```go +e, err := NewEnforcer("examples/rbac_model.conf", "examples/rbac_policy.csv") +``` + + +```typescript +const e = await newEnforcer('examples/rbac_model.conf', 'examples/rbac_policy.csv') +``` + + +```php +$e = new Enforcer('examples/rbac_model.conf', 'examples/rbac_policy.csv'); +``` + + +```csharp +var e = new Enforcer("path/to/model.conf", "path/to/policy.csv"); +``` + + +```rust +let mut e = Enforce::new("examples/rbac_model.conf", "examples/rbac_policy.csv").await?; +``` + + + +### `GetAllSubjects()` + +GetAllSubjects gets the list of subjects that show up in the current policy. + +For example: + + + + +```go +allSubjects := e.GetAllSubjects() +``` + + +```typescript +const allSubjects = await e.getAllSubjects() +``` + + +```php +$allSubjects = $e->getAllSubjects(); +``` + + +```csharp +var allSubjects = e.GetAllSubjects(); +``` + + +```rust +let all_subjects = e.get_all_subjects(); +``` + + + +### `GetAllNamedSubjects()` + +GetAllNamedSubjects gets the list of subjects that show up in the current named policy. + +For example: + + + + +```go +allNamedSubjects := e.GetAllNamedSubjects("p") +``` + + +```typescript +const allNamedSubjects = await e.getAllNamedSubjects('p') +``` + + +```php +$allNamedSubjects = $e->getAllNamedSubjects("p"); +``` + + +```csharp +var allNamedSubjects = e.GetAllNamedSubjects("p"); +``` + + +```rust +let all_named_subjects = e.get_all_named_subjects("p"); +``` + + + +### `GetAllObjects()` + +GetAllObjects gets the list of objects that show up in the current policy. + +For example: + + + + +```go +allObjects := e.GetAllObjects() +``` + + +```typescript +const allObjects = await e.getAllObjects() +``` + + +```php +$allObjects = $e->getAllObjects(); +``` + + +```csharp +var allObjects = e.GetAllObjects(); +``` + + +```rust +let all_objects = e.get_all_objects(); +``` + + + +### `GetAllNamedObjects()` + +GetAllNamedObjects gets the list of objects that show up in the current named policy. + +For example: + + + + +```go +allNamedObjects := e.GetAllNamedObjects("p") +``` + + +```typescript +const allNamedObjects = await e.getAllNamedObjects('p') +``` + + +```php +$allNamedObjects = $e->getAllNamedObjects("p"); +``` + + +```csharp +var allNamedObjects = e.GetAllNamedObjects("p"); +``` + + +```rust +let all_named_objects = e.get_all_named_objects("p"); +``` + + + +### `GetAllActions()` + +GetAllActions gets the list of actions that show up in the current policy. + +For example: + + + + +```go +allActions := e.GetAllActions() +``` + + +```typescript +const allActions = await e.getAllActions() +``` + + +```php +$allActions = $e->getAllActions(); +``` + + +```csharp +var allActions = e.GetAllActions(); +``` + + +```rust +let all_actions = e.get_all_actions(); +``` + + + +### `GetAllNamedActions()` + +GetAllNamedActions gets the list of actions that show up in the current named policy. + +For example: + + + + +```go +allNamedActions := e.GetAllNamedActions("p") +``` + + +```typescript +const allNamedActions = await e.getAllNamedActions('p') +``` + + +```php +$allNamedActions = $e->getAllNamedActions("p"); +``` + + +```csharp +var allNamedActions = e.GetAllNamedActions("p"); +``` + + +```rust +let all_named_actions = e.get_all_named_actions("p"); +``` + + + +### `GetAllRoles()` + +GetAllRoles gets the list of roles that show up in the current policy. + +For example: + + + + +``` +allRoles = e.GetAllRoles() +``` + + +```typescript +const allRoles = await e.getAllRoles() +``` + + +```php +$allRoles = $e->getAllRoles(); +``` + + +```csharp +var allRoles = e.GetAllRoles(); +``` + + +```rust +let all_roles = e.get_all_roles(); +``` + + + +### `GetAllNamedRoles()` + +GetAllNamedRoles gets the list of roles that show up in the current named policy. + +For example: + + + + +```go +allNamedRoles := e.GetAllNamedRoles("g") +``` + + +```typescript +const allNamedRoles = await e.getAllNamedRoles('g') +``` + + +```php +$allNamedRoles = $e->getAllNamedRoles('g'); +``` + + +```csharp +var allNamedRoles = e.GetAllNamedRoles("g"); +``` + + +```rust +let all_named_roles = e.get_all_named_roles("g"); +``` + + + +### `GetPolicy()` + +GetPolicy gets all the authorization rules in the policy. + +For example: + + + + +```go +policy = e.GetPolicy() +``` + + +```typescript +const policy = await e.getPolicy() +``` + + +```php +$policy = $e->getPolicy(); +``` + + +```csharp +var policy = e.GetPolicy(); +``` + + +```rust +let policy = e.get_policy(); +``` + + + + +### `GetFilteredPolicy()` + +GetFilteredPolicy gets all the authorization rules in the policy, field filters can be specified. + +For example: + + + + +```go +filteredPolicy := e.GetFilteredPolicy(0, "alice") +``` + + +```typescript +const filteredPolicy = await e.getFilteredPolicy(0, 'alice') +``` + + +```php +$filteredPolicy = $e->getFilteredPolicy(0, "alice"); +``` + + +```csharp +var filteredPolicy = e.GetFilteredPolicy(0, "alice"); +``` + + +```rust +let filtered_policy = e.get_filtered_policy(0, vec!["alice".to_owned()]); +``` + + + +### `GetNamedPolicy()` + +GetNamedPolicy gets all the authorization rules in the named policy. + +For example: + + + + +```go +namedPolicy := e.GetNamedPolicy("p") +``` + + +```typescript +const namedPolicy = await e.getNamedPolicy('p') +``` + + +```php +$namedPolicy = $e->getNamedPolicy("p"); +``` + + +```csharp +var namedPolicy = e.GetNamedPolicy("p"); +``` + + +```rust +let named_policy = e.get_named_policy("p"); +``` + + + + +### `GetFilteredNamedPolicy()` + +GetFilteredNamedPolicy gets all the authorization rules in the named policy, field filters can be specified. + +For example: + + + + +```go +filteredNamedPolicy = e.GetFilteredNamedPolicy("p", 0, "bob") +``` + + +```typescript +const filteredNamedPolicy = await e.getFilteredNamedPolicy('p', 0, 'bob') +``` + + +```php +$filteredNamedPolicy = $e->getFilteredNamedPolicy("p", 0, "bob"); +``` + + +```csharp +var filteredNamedPolicy = e.GetFilteredNamedPolicy("p", 0, "alice"); +``` + + +```rust +let filtered_named_policy = e.get_filtered_named_policy("p", 0, vec!["bob".to_owned()]); +``` + + + +### `GetGroupingPolicy()` + +GetGroupingPolicy gets all the role inheritance rules in the policy. + +For example: + + + + +```go +groupingPolicy := e.GetGroupingPolicy() +``` + + +```typescript +const groupingPolicy = await e.getGroupingPolicy() +``` + + +```php +$groupingPolicy = $e->getGroupingPolicy(); +``` + + +```csharp +var groupingPolicy = e.GetGroupingPolicy(); +``` + + +```rust +let grouping_policy = e.get_grouping_policy(); +``` + + + +### `GetFilteredGroupingPolicy()` + +GetFilteredGroupingPolicy gets all the role inheritance rules in the policy, field filters can be specified. + +For example: + + + + +```go +filteredGroupingPolicy := e.GetFilteredGroupingPolicy(0, "alice") +``` + + +```typescript +const filteredGroupingPolicy = await e.getFilteredGroupingPolicy(0, 'alice') +``` + + +```php +$filteredGroupingPolicy = $e->getFilteredGroupingPolicy(0, "alice"); +``` + + +```csharp +var filteredGroupingPolicy = e.GetFilteredGroupingPolicy(0, "alice"); +``` + + +```rust +let filtered_grouping_policy = e.get_filtered_grouping_policy(0, vec!["alice".to_owned()]); +``` + + + +### `GetNamedGroupingPolicy()` + +GetNamedGroupingPolicy gets all the role inheritance rules in the policy. + +For example: + + + + +```go +namedGroupingPolicy := e.GetNamedGroupingPolicy("g") +``` + + +```typescript +const namedGroupingPolicy = await e.getNamedGroupingPolicy('g') +``` + + +```php +$namedGroupingPolicy = $e->getNamedGroupingPolicy("g"); +``` + + +```csharp +var namedGroupingPolicy = e.GetNamedGroupingPolicy("g"); +``` + + +```rust +let named_grouping_policy = e.get_named_grouping_policy("g"); +``` + + + + +### `GetFilteredNamedGroupingPolicy()` + +GetFilteredNamedGroupingPolicy gets all the role inheritance rules in the policy. + +For example: + + + + +```go +namedGroupingPolicy := e.GetFilteredNamedGroupingPolicy("g", 0, "alice") +``` + + +```typescript +const namedGroupingPolicy = await e.getFilteredNamedGroupingPolicy('g', 0, 'alice') +``` + + +```php +$namedGroupingPolicy = $e->getFilteredNamedGroupingPolicy("g", 0, "alice"); +``` + + +```csharp +var namedGroupingPolicy = e.GetFilteredNamedGroupingPolicy("g", 0, "alice"); +``` + + +```rust +let named_grouping_policy = e.get_filtered_named_groupingPolicy("g", 0, vec!["alice".to_owned()]); +``` + + + +### `HasPolicy()` + +HasPolicy determines whether an authorization rule exists. + +For example: + + + + +```go +hasPolicy := e.HasPolicy("data2_admin", "data2", "read") +``` + + +```typescript +const hasPolicy = await e.hasPolicy('data2_admin', 'data2', 'read') +``` + + +```php +$hasPolicy = $e->hasPolicy('data2_admin', 'data2', 'read'); +``` + + +```csharp +var hasPolicy = e.HasPolicy("data2_admin", "data2", "read"); +``` + + +```rust +let has_policy = e.has_policy(vec!["data2_admin".to_owned(), "data2".to_owned(), "read".to_owned()]); +``` + + + +### `HasNamedPolicy()` + +HasNamedPolicy determines whether a named authorization rule exists. + +For example: + + + + +```go +hasNamedPolicy := e.HasNamedPolicy("p", "data2_admin", "data2", "read") +``` + + +```typescript +const hasNamedPolicy = await e.hasNamedPolicy('p', 'data2_admin', 'data2', 'read') +``` + + +```php +$hasNamedPolicy = $e->hasNamedPolicy("p", "data2_admin", "data2", "read"); +``` + + +```csharp +var hasNamedPolicy = e.HasNamedPolicy("p", "data2_admin", "data2", "read"); +``` + + +```rust +let has_named_policy = e.has_named_policy("p", vec!["data2_admin".to_owned(), "data2".to_owned(), "read".to_owned()]); +``` + + + +### `AddPolicy()` + +AddPolicy adds an authorization rule to the current policy. If the rule already exists, the function returns false and the rule will not be added. Otherwise the function returns true by adding the new rule. + +For example: + + + + +```go +added := e.AddPolicy("eve", "data3", "read") +``` + + +```typescript +const p = ['eve', 'data3', 'read'] +const added = await e.addPolicy(...p) +``` + + +```php +$added = $e->addPolicy('eve', 'data3', 'read'); +``` + + +```csharp +var added = e.AddPolicy("eve", "data3", "read"); +or +var added = await e.AddPolicyAsync("eve", "data3", "read"); +``` + + +```rust +let added = e.add_policy(vec!["eve".to_owned(), "data3".to_owned(), "read".to_owned()]); +``` + + + +### `AddPolicies()` + +AddPolicies adds authorization rules to the current policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is added to the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is added to the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesAdded := e.AddPolicies(rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["katy".to_owned(), "data4".to_owned(), "write".to_owned()], + vec!["leyo".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["ham".to_owned(), "data4".to_owned(), "write".to_owned()], +]; + +let are_rules_added = e.add_policies(rules).await? +``` + + +```typescript +const rules = [ + ['jack', 'data4', 'read'], + ['katy', 'data4', 'write'], + ['leyo', 'data4', 'read'], + ['ham', 'data4', 'write'] +]; + +const areRulesAdded = await e.addPolicies(rules); +``` + + + +### `AddNamedPolicy()` + +AddNamedPolicy adds an authorization rule to the current named policy. If the rule already exists, the function returns false and the rule will not be added. Otherwise the function returns true by adding the new rule. + +For example: + + + + +```go +added := e.AddNamedPolicy("p", "eve", "data3", "read") +``` + + +```typescript +const p = ['eve', 'data3', 'read'] +const added = await e.addNamedPolicy('p', ...p) +``` + + +```php +$added = $e->addNamedPolicy("p", "eve", "data3", "read"); +``` + + +```csharp +var added = e.AddNamedPolicy("p", "eve", "data3", "read"); +or +var added = await e.AddNamedPolicyAsync("p", "eve", "data3", "read"); +``` + + +```rust +let added = e.add_named_policy("p", vec!["eve".to_owned(), "data3".to_owned(), "read".to_owned()]).await?; +``` + + + +### `AddNamedPolicies()` + +AddNamedPolicies adds authorization rules to the current named policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is added to the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is added to the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesAdded := e.AddNamedPolicies("p", rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["katy".to_owned(), "data4".to_owned(), "write".to_owned()], + vec!["leyo".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["ham".to_owned(), "data4".to_owned(), "write".to_owned()], +]; + +let are_rules_added := e.add_named_policies("p", rules).await?; +``` + + +```typescript +const rules = [ + ['jack', 'data4', 'read'], + ['katy', 'data4', 'write'], + ['leyo', 'data4', 'read'], + ['ham', 'data4', 'write'] +]; + +const areRulesAdded = await e.addNamedPolicies('p', rules); +``` + + + +### `RemovePolicy()` + +RemovePolicy removes an authorization rule from the current policy. + +For example: + + + + +```go +removed := e.RemovePolicy("alice", "data1", "read") +``` + + +```typescript +const p = ['alice', 'data1', 'read'] +const removed = await e.removePolicy(...p) +``` + + +```php +$removed = $e->removePolicy("alice", "data1", "read"); +``` + + +```csharp +var removed = e.RemovePolicyAsync("alice", "data1", "read"); +or +var removed = await e.RemovePolicyAsync("alice", "data1", "read"); +``` + + +```rust +let removed = e.remove_policy(vec!["alice".to_owned(), "data1".to_owned(), "read".to_owned()]).await?; +``` + + + +### `RemovePolicies()` + +RemovePolicies removes authorization rules from the current policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is removed from the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is removed from the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesRemoved := e.RemovePolicies(rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["katy".to_owned(), "data4".to_owned(), "write".to_owned()], + vec!["leyo".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["ham".to_owned(), "data4".to_owned(), "write".to_owned()], +]; + +let are_rules_removed = e.remove_policies(rules).await?; +``` + + +```typescript +const rules = [ + ['jack', 'data4', 'read'], + ['katy', 'data4', 'write'], + ['leyo', 'data4', 'read'], + ['ham', 'data4', 'write'] +]; + +const areRulesRemoved = await e.removePolicies(rules); +``` + + + + +### `RemoveFilteredPolicy()` + +RemoveFilteredPolicy removes an authorization rule from the current policy, field filters can be specified. RemovePolicy removes an authorization rule from the current policy. + +For example: + + + + +```go +removed := e.RemoveFilteredPolicy(0, "alice", "data1", "read") +``` + + +```typescript +const p = ['alice', 'data1', 'read'] +const removed = await e.removeFilteredPolicy(0, ...p) +``` + + +```php +$removed = $e->removeFilteredPolicy(0, "alice", "data1", "read"); +``` + + +```csharp +var removed = e.RemoveFilteredPolicy("alice", "data1", "read"); +or +var removed = await e.RemoveFilteredPolicyAsync("alice", "data1", "read"); +``` + + +```rust +let removed = e.remove_filtered_policy(0, vec!["alice".to_owned(), "data1".to_owned(), "read".to_owned()]).await?; +``` + + + +### `RemoveNamedPolicy()` + +RemoveNamedPolicy removes an authorization rule from the current named policy. + +For example: + + + + +```go +removed := e.RemoveNamedPolicy("p", "alice", "data1", "read") +``` + + +```typescript +const p = ['alice', 'data1', 'read'] +const removed = await e.removeNamedPolicy('p', ...p) +``` + + +```php +$removed = $e->removeNamedPolicy("p", "alice", "data1", "read"); +``` + + +```csharp +var removed = e.RemoveNamedPolicy("p", "alice", "data1", "read"); +or +var removed = await e.RemoveNamedPolicyAsync("p", "alice", "data1", "read"); +``` + + +```rust +let removed = e.remove_named_policy("p", vec!["alice".to_owned(), "data1".to_owned(), "read".to_owned()]).await?; +``` + + + +### `RemoveNamedPolicies()` + +RemoveNamedPolicies removes authorization rules from the current named policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is removed from the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is removed from the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesRemoved := e.RemoveNamedPolicies("p", rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["katy".to_owned(), "data4".to_owned(), "write".to_owned()], + vec!["leyo".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["ham".to_owned(), "data4".to_owned(), "write".to_owned()], +]; + +let areRulesRemoved = e.remove_named_policies("p", rules).await?; +``` + + +```typescript +const rules = [ + ['jack', 'data4', 'read'], + ['katy', 'data4', 'write'], + ['leyo', 'data4', 'read'], + ['ham', 'data4', 'write'] +]; + +const areRulesRemoved = await e.removeNamedPolicies('p', rules); +``` + + + +### `RemoveFilteredNamedPolicy()` + +RemoveFilteredNamedPolicy removes an authorization rule from the current named policy, field filters can be specified. + +For example: + + + + +```go +removed := e.RemoveFilteredNamedPolicy("p", 0, "alice", "data1", "read") +``` + + +```typescript +const p = ['alice', 'data1', 'read'] +const removed = await e.removeFilteredNamedPolicy('p', 0, ...p) +``` + + +```php +$removed = $e->removeFilteredNamedPolicy("p", 0, "alice", "data1", "read"); +``` + + +```csharp +var removed = e.RemoveFilteredNamedPolicy("p", 0, "alice", "data1", "read"); +or +var removed = e.RemoveFilteredNamedPolicyAync("p", 0, "alice", "data1", "read"); +``` + + +```rust +let removed = e.remove_filtered_named_policy("p", 0, vec!["alice".to_owned(), "data1".to_owned(), "read".to_owned()]).await?; +``` + + + +### `HasGroupingPolicy()` + +HasGroupingPolicy determines whether a role inheritance rule exists. + +For example: + + + + +```go +has := e.HasGroupingPolicy("alice", "data2_admin") +``` + + +```typescript +const has = await e.hasGroupingPolicy('alice', 'data2_admin') +``` + + +```php +$has = $e->hasGroupingPolicy("alice", "data2_admin"); +``` + + +```csharp +var has = e.HasGroupingPolicy("alice", "data2_admin"); +``` + + +```rust +let has = e.has_grouping_policy(vec!["alice".to_owned(), "data2_admin".to_owned()]); +``` + + + +### `HasNamedGroupingPolicy()` + +HasNamedGroupingPolicy determines whether a named role inheritance rule exists. + +For example: + + + + +```go +has := e.HasNamedGroupingPolicy("g", "alice", "data2_admin") +``` + + +```typescript +const has = await e.hasNamedGroupingPolicy('g', 'alice', 'data2_admin') +``` + + +```php +$has = $e->hasNamedGroupingPolicy("g", "alice", "data2_admin"); +``` + + +```csharp +var has = e.HasNamedGroupingPolicy("g", "alice", "data2_admin"); +``` + + +```rust +let has = e.has_named_grouping_policy("g", vec!["alice".to_owned(), "data2_admin".to_owned()]); +``` + + + + +### `AddGroupingPolicy()` + +AddGroupingPolicy adds a role inheritance rule to the current policy. If the rule already exists, the function returns false and the rule will not be added. Otherwise the function returns true by adding the new rule. + +For example: + + + + +```go +added := e.AddGroupingPolicy("group1", "data2_admin") +``` + + +```typescript +const added = await e.addGroupingPolicy('group1', 'data2_admin') +``` + + +```php +$added = $e->addGroupingPolicy("group1", "data2_admin"); +``` + + +```csharp +var added = e.AddGroupingPolicy("group1", "data2_admin"); +or +var added = await e.AddGroupingPolicyAsync("group1", "data2_admin"); +``` + + +```rust +let added = e.add_grouping_policy(vec!["group1".to_owned(), "data2_admin".to_owned()]).await?; +``` + + + +### `AddGroupingPolicies()` + +AddGroupingPolicies adds role inheritance rules to the current policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is added to the current policy. If all authorization the rules are consistent with the policy rules, the function returns true and each policy rule is added to the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesAdded := e.AddGroupingPolicies(rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["katy".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["leyo".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["ham".to_owned(), "group1".to_owned(), "domain1".to_owned()], +]; + +let areRulesAdded = e.add_grouping_policies(rules).await?; +``` + +```typescript +const groupingRules = [ + ['ham', 'data4_admin'], + ['jack', 'data5_admin'] + ]; + +const areRulesAdded = await e.addGroupingPolicies(groupingRules); +``` + + + +### `AddNamedGroupingPolicy()` + +AddNamedGroupingPolicy adds a named role inheritance rule to the current policy. If the rule already exists, the function returns false and the rule will not be added. Otherwise the function returns true by adding the new rule. + +For example: + + + + +```go +added := e.AddNamedGroupingPolicy("g", "group1", "data2_admin") +``` + + +```typescript +const added = await e.addNamedGroupingPolicy('g', 'group1', 'data2_admin') +``` + + +```php +$added = $e->addNamedGroupingPolicy("g", "group1", "data2_admin"); +``` + + +```csharp +var added = e.AddNamedGroupingPolicy("g", "group1", "data2_admin"); +or +var added = await e.AddNamedGroupingPolicyAsync("g", "group1", "data2_admin"); +``` + + +```rust +let added = e.add_named_grouping_policy("g", vec!["group1".to_owned(), "data2_admin".to_owned()]).await?; +``` + + + + +### `AddNamedGroupingPolicies()` + +AddNamedGroupingPolicies adds named role inheritance rules to the current policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is added to the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is added to the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesAdded := e.AddNamedGroupingPolicies("g", rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["katy".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["leyo".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["ham".to_owned(), "group1".to_owned(), "domain1".to_owned()], +]; + +let are_rules_added = e.add_named_grouping_policies("g", rules).await?; +``` + + +```typescript +const groupingRules = [ + ['ham', 'data4_admin'], + ['jack', 'data5_admin'] + ]; + +const areRulesAdded = await e.addNamedGroupingPolicies('g', groupingRules); +``` + + + +### `RemoveGroupingPolicy()` + +RemoveGroupingPolicy removes a role inheritance rule from the current policy. + +For example: + + + + +```go +removed := e.RemoveGroupingPolicy("alice", "data2_admin") +``` + + +```typescript +const removed = await e.removeGroupingPolicy('alice', 'data2_admin') +``` + + +```php +$removed = $e->removeGroupingPolicy("alice", "data2_admin"); +``` + + +```csharp +var removed = e.RemoveGroupingPolicy("alice", "data2_admin"); +or +var removed = await e.RemoveGroupingPolicyAsync("alice", "data2_admin"); +``` + + +```rust +let removed = e.remove_grouping_policy(vec!["alice".to_owned(), "data2_admin".to_owned()]).await?; +``` + + + +### `RemoveGroupingPolicies()` + +RemoveGroupingPolicies removes role inheritance rules from the current policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is removed from the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is removed from the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesRemoved := e.RemoveGroupingPolicies(rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["katy".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["leyo".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["ham".to_owned(), "group1".to_owned(), "domain1".to_owned()], +]; + +let are_rules_removed = e.remove_grouping_policies(rules).await?; +``` + + +```typescript +const groupingRules = [ + ['ham', 'data4_admin'], + ['jack', 'data5_admin'] + ]; + +const areRulesRemoved = await e.removeGroupingPolicies(groupingRules); +``` + + + +### `RemoveFilteredGroupingPolicy()` + +RemoveFilteredGroupingPolicy removes a role inheritance rule from the current policy, field filters can be specified. + +For example: + + + + +```go +removed := e.RemoveFilteredGroupingPolicy(0, "alice") +``` + + +```typescript +const removed = await e.removeFilteredGroupingPolicy(0, 'alice') +``` + + +```php +$removed = $e->removeFilteredGroupingPolicy(0, "alice"); +``` + + +```csharp +var removed = e.RemoveFilteredGroupingPolicy(0, "alice"); +or +var removed = await e.RemoveFilteredGroupingPolicyAsync(0, "alice"); +``` + + +```rust +let removed = e.remove_filtered_grouping_policy(0, vec!["alice".to_owned()]).await?; +``` + + + +### `RemoveNamedGroupingPolicy()` + +RemoveNamedGroupingPolicy removes a role inheritance rule from the current named policy. + +For example: + + + + +```go +removed := e.RemoveNamedGroupingPolicy("g", "alice") +``` + + +```typescript +const removed = await e.removeNamedGroupingPolicy('g', 'alice') +``` + + +```php +$removed = $e->removeNamedGroupingPolicy("g", "alice"); +``` + + +```csharp +var removed = e.RemoveNamedGroupingPolicy("g", "alice"); +or +var removed = await e.RemoveNamedGroupingPolicyAsync("g", "alice"); +``` + + +```rust +let removed = e.remove_named_grouping_policy("g", vec!["alice".to_owned()]).await?; +``` + + + +### `RemoveNamedGroupingPolicies()` + +RemoveNamedGroupingPolicies removes named role inheritance rules from the current policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is removed from the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is removed from the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesRemoved := e.RemoveNamedGroupingPolicies("g", rules) +``` + + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["katy".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["leyo".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["ham".to_owned(), "group1".to_owned(), "domain1".to_owned()], +]; + +let are_rules_removed = e.remove_named_grouping_policies("g", rules).await?; +``` + + +```typescript +const groupingRules = [ + ['ham', 'data4_admin'], + ['jack', 'data5_admin'] + ]; + +const areRulesRemoved = await e.removeNamedGroupingPolicies('g', groupingRules); +``` + + + +### `RemoveFilteredNamedGroupingPolicy()` + +RemoveFilteredNamedGroupingPolicy removes a role inheritance rule from the current named policy, field filters can be specified. + +For example: + + + + +```go +removed := e.RemoveFilteredNamedGroupingPolicy("g", 0, "alice") +``` + + +```typescript +const removed = await e.removeFilteredNamedGroupingPolicy('g', 0, 'alice') +``` + + +```php +$removed = $e->removeFilteredNamedGroupingPolicy("g", 0, "alice"); +``` + + +```csharp +var removed = e.RemoveFilteredNamedGroupingPolicy("g", 0, "alice"); +or +var removed = await e.RemoveFilteredNamedGroupingPolicyAsync("g", 0, "alice"); +``` + + +```rust +let removed = e.remove_filtered_named_groupingPolicy("g", 0, vec!["alice".to_owned()]).await?; +``` + + + +### `UpdatePolicy()` + +UpdatePolicy update a old policy to new policy. + +For example: + + + + +```go +updated, err := e.UpdatePolicy([]string{"eve", "data3", "read"}, []string{"eve", "data3", "write"}) +``` + + + +### `UpdatePolicies()` + +UpdatePolicies updates all old policies to new policies. + +For example: + + + + +```go +updated, err := e.UpdatePolicies([][]string{{"eve", "data3", "read"}, {"jack", "data3", "read"}}, [][]string{{"eve", "data3", "write"}, {"jack", "data3", "write"}}) +``` + + + +### `AddFunction()` + +AddFunction adds a customized function. + +For example: + + + + +```go +func CustomFunction(key1 string, key2 string) bool { + if key1 == "/alice_data2/myid/using/res_id" && key2 == "/alice_data/:resource" { + return true + } else if key1 == "/alice_data2/myid/using/res_id" && key2 == "/alice_data2/:id/using/:resId" { + return true + } else { + return false + } +} + +func CustomFunctionWrapper(args ...interface{}) (interface{}, error) { + key1 := args[0].(string) + key2 := args[1].(string) + + return bool(CustomFunction(key1, key2)), nil +} + +e.AddFunction("keyMatchCustom", CustomFunctionWrapper) +``` + + +```text +Method is not implemented +``` + + +```php +func customFunction($key1, $key2) { + if ($key1 == "/alice_data2/myid/using/res_id" && $key2 == "/alice_data/:resource") { + return true; + } elseif ($key1 == "/alice_data2/myid/using/res_id" && $key2 == "/alice_data2/:id/using/:resId") { + return true; + } else { + return false; + } +} + +func customFunctionWrapper(...$args){ + $key1 := $args[0]; + $key2 := $args[1]; + + return customFunction($key1, $key2); +} + +$e->addFunction("keyMatchCustom", customFunctionWrapper); +``` + + + +```rust +fn custom_function(key1: STring, key2: String) { + key1 == "/alice_data2/myid/using/res_id" && key2 == "/alice_data/:resource" || key1 == "/alice_data2/myid/using/res_id" && key2 == "/alice_data2/:id/using/:resId" +} + + +e.add_function("keyMatchCustom", custom_function); +``` + + diff --git a/website/translated_docs/fr-FR/Middlewares.md b/website/translated_docs/fr-FR/Middlewares.md new file mode 100644 index 00000000..c316a69d --- /dev/null +++ b/website/translated_docs/fr-FR/Middlewares.md @@ -0,0 +1,83 @@ +--- +id: middlewares +title: Middlewares +--- + +### Web frameworks + + + + +| Name | Description | +| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Gin](https://github.com/gin-gonic/gin) | A HTTP web framework featuring a Martini-like API with much better performance, via plugin: [authz](https://github.com/gin-contrib/authz) or [gin-casbin](https://github.com/maxwellhertz/gin-casbin) (thanks to [@maxwellhertz](https://github.com/maxwellhertz)) | +| [Beego](https://github.com/astaxie/beego) | An open-source, high-performance web framework for Go, via built-in plugin: [plugins/authz](https://github.com/astaxie/beego/blob/master/plugins/authz) | +| [Caddy](https://github.com/mholt/caddy) | Fast, cross-platform HTTP/2 web server with automatic HTTPS, via plugin: [caddy-authz](https://github.com/casbin/caddy-authz) | +| [Go kit](https://github.com/go-kit/kit) | A toolkit for microservices, via built-in plugin: [plugins/authz](https://github.com/go-kit/kit/tree/master/auth/casbin) | +| [Fiber](https://github.com/gofiber/fiber) | An Express inspired web framework written in Go, via middleware: [fiber-casbin](https://github.com/arsmn/fiber-casbin) or [fiber-casbinrest](https://github.com/prongbang/fiber-casbinrest) | +| [Revel](https://github.com/revel/revel) | A high productivity, full-stack web framework for the Go language, via plugin: [auth/casbin](https://github.com/revel/modules/tree/master/auth/casbin) | +| [Echo](https://github.com/labstack/echo) | High performance, minimalist Go web framework, via plugin: [echo-authz](https://github.com/labstack/echo-contrib/tree/master/casbin) (thanks to [@xqbumu](https://github.com/xqbumu)) or [casbinrest](https://github.com/prongbang/casbinrest) (thanks to [@prongbang](https://github.com/prongbang)) | +| [Iris](https://github.com/kataras/iris) | The fastest web framework for Go in (THIS) Earth. HTTP/2 Ready-To-GO, via plugin: [casbin](https://github.com/iris-contrib/middleware/tree/master/casbin) (thanks to [@hiveminded](https://github.com/hiveminded)) or [iris-middleware-casbin](https://github.com/kokobing/iris-middleware-casbin) | +| [Negroni](https://github.com/urfave/negroni) | Idiomatic HTTP Middleware for Golang, via plugin: [negroni-authz](https://github.com/casbin/negroni-authz) | +| [Chi](https://github.com/pressly/chi) | A lightweight, idiomatic and composable router for building HTTP services, via plugin: [chi-authz](https://github.com/casbin/chi-authz) | +| [Buffalo](https://github.com/gobuffalo/buffalo) | A Go web development eco-system, designed to make your life easier, via plugin: [buffalo-mw-rbac](https://github.com/kgosse/buffalo-mw-rbac) (thanks to [@kgosse](https://github.com/kgosse)) | +| [gqlgen](https://gqlgen.com/) | Go library for building GraphQL servers without any fuss, via plugin: [gqlgen_casbin_RBAC_example](https://github.com/WenyXu/gqlgen_casbin_RBAC_example) | +| [Macaron](https://github.com/go-macaron/macaron) | A high productive and modular web framework in Go, via plugin: [authz](https://github.com/go-macaron/authz) | +| [DotWeb](https://github.com/devfeel/dotweb) | Simple and easy go web micro framework, via plugin: [authz](https://github.com/devfeel/middleware/tree/master/authz) | +| [Tango](https://github.com/lunny/tango) | Micro & pluggable web framework for Go, via plugin: [authz](https://gitea.com/tango/authz) | +| [Baa](https://github.com/go-baa/baa) | An express Go web framework with routing, middleware, dependency injection and http context, via plugin: [authz](https://github.com/baa-middleware/authz) | + + +| Name | Description | +| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Spring Boot](https://projects.spring.io/spring-boot/) | Makes it easy to create Spring-powered applications and services, via plugin: [casbin-spring-boot-starter](https://github.com/jcasbin/casbin-spring-boot-starter) or [jcasbin-springboot-plugin](https://github.com/jcasbin/jcasbin-springboot-plugin) or [Simple SpringBoot security demo with jCasbin](https://github.com/jveverka/spring-examples/tree/master/spring-jcasbin) | +| [Apache Shiro](https://shiro.apache.org/) | A powerful and easy-to-use Java security framework that performs authentication, authorization, cryptography, and session management, via plugin: [shiro-casbin](https://github.com/jcasbin/shiro-casbin) or [shiro-jcasbin-spring-boot-starter](https://github.com/mapleafgo/shiro-jcasbin-spring-boot-starter) | +| [Vert.x](https://vertx.io/) | A tool-kit for building reactive applications on the JVM, via plugin: [vertx-auth-jcasbin](https://github.com/vert-x3/vertx-auth/pull/215) | +| [JFinal](http://www.jfinal.com/) | A simple, light, rapid, independent and extensible Java WEB + ORM framework, via plugin: [jfinal-authz](https://github.com/jcasbin/jfinal-authz) | +| [Nutz](https://nutzam.com/) | Web framework (MVC/IOC/AOP/DAO/JSON) for all Java developers, via plugin: [nutz-authz](https://github.com/jcasbin/nutz-authz) | +| [mangoo I/O](https://github.com/svenkubiak/mangooio) | An intuitive, lightweight, high performance full stack Java web framework, via built-in plugin: [AuthorizationService.java](https://github.com/svenkubiak/mangooio/blob/e8c647a3f7c427bce27377025bec074f6d767f50/mangooio-core/src/main/java/io/mangoo/services/AuthorizationService.java) | + + +| Name | Description | +| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Express](https://github.com/expressjs/express) | Fast, unopinionated, minimalist web framework for node, via plugin: [express-authz](https://github.com/node-casbin/express-authz) | +| [Koa](https://github.com/koajs/koa) | Expressive middleware for node.js using ES2017 async functions, via plugin: [koa-authz](https://github.com/node-casbin/koa-authz) or [koajs-starter](https://github.com/djordjep/koajs-starter) or [koa-casbin](https://github.com/zcong1993/koa-casbin) | +| [LoopBack 4](https://github.com/koajs/koa) | A highly extensible Node.js and TypeScript framework for building APIs and microservices, via plugin: [loopback4-authorization](https://github.com/sourcefuse/loopback4-authorization) | +| [Nest](https://nestjs.com/) | Progressive Node.js framework for building efficient and scalable server-side applications on top of TypeScript & JavaScript. via plugin: [nest-authz](https://github.com/dreamdevil00/nest-authz) or [nest-casbin](https://github.com/pardjs/nest-casbin) or [NestJS Casbin Module](https://github.com/switchit-conseil/nestjs-casbin-module) or [nestjs-casbin](https://github.com/juicycleff/nestjs-casbin) | +| [Fastify](https://github.com/fastify/fastify) | Fast and low overhead web framework, for Node.js. via plugin: [fastify-casbin](https://github.com/nearform/fastify-casbin) or [fastify-casbin-rest](https://github.com/nearform/fastify-casbin-rest) | +| [Egg](https://github.com/eggjs/egg) | Born to build better enterprise frameworks and apps with Node.js & Koa, via plugin: [egg-authz](https://github.com/node-casbin/egg-authz) or [egg-zrole](https://github.com/klren0312/egg-zrole) | +| [hapi](https://hapi.dev/) | The Simple, Secure Framework Developers Trust. via plugin: [hapi-authz](https://github.com/node-casbin/hapi-authz) | +| [Casbin JWT Express](https://github.com/tiagostutz/casbin-jwt-express) | Authorization middleware that uses stateless JWT token to validate ACL rules using Casbin | + + +| Name | Description | +| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Laravel](https://laravel.com/) | The PHP framework for web artisans, via plugin: [laravel-authz](https://github.com/php-casbin/laravel-authz) | +| [Yii PHP Framework](https://www.yiiframework.com/) | A fast, secure, and efficient PHP framework, via plugin: [yii-permission](https://github.com/php-casbin/yii-permission) | +| [CakePHP](https://cakephp.org/) | Build fast, grow solid PHP Framework, via plugin: [cake-casbin](https://github.com/php-casbin/cake-casbin) | +| [CodeIgniter4](https://codeigniter.com/) | Associate users with roles and permissions in CodeIgniter4 Web Framework, via plugin: [CodeIgniter Permission](https://github.com/php-casbin/codeigniter-permission) | +| [ThinkPHP 5.1](http://www.thinkphp.cn/) | The ThinkPHP 5.1 framework, via plugin: [think-casbin](https://github.com/php-casbin/think-casbin) | +| [ThinkPHP 6.0](http://www.thinkphp.cn/) | The ThinkPHP 6.0 framework, via plugin: [think-authz](https://github.com/php-casbin/think-authz) | +| [Symfony](https://symfony.com/) | The Symfony PHP framework, via plugin: [symfony-casbin](https://github.com/videni/symfony-casbin) | +| [Hyperf](https://github.com/hyperf/hyperf) | A coroutine framework that focuses on hyperspeed and flexibility, via plugin: [hyperf-casbin](https://github.com/donjan-deng/hyperf-casbin) | + + +| Name | Description | +| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Django](https://www.djangoproject.com/) | A high-level Python Web framework, via plugin: [django-casbin](https://github.com/pycasbin/django-casbin) | +| [Flask](http://flask.pocoo.org/) | A microframework for Python based on Werkzeug, Jinja 2 and good intentions, via plugin: [flask-authz](https://github.com/pycasbin/flask-authz) or [Flask-Casbin (3rd-party, but maybe more friendly)](https://github.com/daymien/Flask-Casbin) | + + +| Name | Description | +| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core) | An open-source and cross-platform framework for building modern cloud based internet connected applications, such as web apps, IoT apps and mobile backends, via plugin: [Casbin.AspNetCore](https://github.com/casbin-net/Casbin.AspNetCore) | +| [ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core) | A simple demo of using Casbin at ASP.NET Core framework, via plugin: [CasbinACL-aspNetCore](https://github.com/MustafaMustafayev/CasbinACL-aspNetCore) | + + +| Name | Description | +| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Actix](https://github.com/actix/actix) | A Rust actors framework, via plugin: [actix-casbin](https://github.com/casbin-rs/actix-casbin) | +| [Actix web](https://github.com/actix/actix-web) | A small, pragmatic, and extremely fast rust web framework, via plugin: [actix-casbin-auth](https://github.com/casbin-rs/actix-casbin-auth) | +| [Rocket](https://github.com/SergioBenitez/Rocket) | a web framework for Rust that makes it simple to write fast, secure web applications without sacrificing flexibility, usability, or type safety, template: [rocket-casbin-demo](https://github.com/simoin/Rocket_Casbin_Demo) | + + diff --git a/website/translated_docs/fr-FR/ModelStorage.md b/website/translated_docs/fr-FR/ModelStorage.md new file mode 100644 index 00000000..5c9a9c9d --- /dev/null +++ b/website/translated_docs/fr-FR/ModelStorage.md @@ -0,0 +1,91 @@ +--- +id: model-storage +title: Model Storage +--- + +Unlike the policy, the model can be loaded only, it cannot be saved. Because we think the model is not a dynamic component and should not be modified at run-time, so we don't implement an API to save the model into a storage. + +However, the good news is, we provide three equivalent ways to load a model either statically or dynamically: + +## Load model from .CONF file + +This is the most common way to use Casbin. It's easy to understand for beginners and convenient for sharing when you ask Casbin team for help. + +The content of the `.CONF` file [examples/rbac_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_model.conf): + +```ini +[request_definition] +r = sub, obj, act + +[policy_definition] +p = sub, obj, act + +[role_definition] +g = _, _ + +[policy_effect] +e = some(where (p.eft == allow)) + +[matchers] +m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act +``` + +Then you can load the model file as: + +```go +e := casbin.NewEnforcer("examples/rbac_model.conf", "examples/rbac_policy.csv") +``` + +## Load model from code + +The model can be initialized dynamically from code instead of using `.CONF` file. Here's an example for the RBAC model: + +```go +// Initialize the model from Go code. +m := model.NewModel() +m.AddDef("r", "r", "sub, obj, act") +m.AddDef("p", "p", "sub, obj, act") +m.AddDef("g", "g", "_, _") +m.AddDef("e", "e", "some(where (p.eft == allow))") +m.AddDef("m", "m", "g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act") + +// Load the policy rules from the .CSV file adapter. +// Replace it with your adapter to avoid files. +a := persist.NewFileAdapter("examples/rbac_policy.csv") + +// Create the enforcer. +e := casbin.NewEnforcer(m, a) +``` + +## Load model from string + +Or you can just load the entire model text from a multi-line string. The good point for this way is that you do not need to maintain a model file. + +```go +// Initialize the model from a string. +text := +` +[request_definition] +r = sub, obj, act + +[policy_definition] +p = sub, obj, act + +[role_definition] +g = _, _ + +[policy_effect] +e = some(where (p.eft == allow)) + +[matchers] +m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act +` +m, _ := NewModelFromString(text) + +// Load the policy rules from the .CSV file adapter. +// Replace it with your adapter to avoid files. +a := persist.NewFileAdapter("examples/rbac_policy.csv") + +// Create the enforcer. +e := casbin.NewEnforcer(m, a) +``` diff --git a/website/translated_docs/fr-FR/MultiThreading.md b/website/translated_docs/fr-FR/MultiThreading.md new file mode 100644 index 00000000..e6206442 --- /dev/null +++ b/website/translated_docs/fr-FR/MultiThreading.md @@ -0,0 +1,8 @@ +--- +id: multi-threading +title: Multi-threading +--- + +If you use Casbin in a multi-threading manner, you can use the synchronized wrapper of the Casbin enforcer: https://github.com/casbin/casbin/blob/master/enforcer_synced.go. + +It also supports the `AutoLoad` feature, which means the Casbin enforcer will automatically load the latest policy rules from DB if it has changed. Call `StartAutoLoadPolicy()` to start automatically loading policy periodically and call `StopAutoLoadPolicy()` to stop it. diff --git a/website/translated_docs/fr-FR/OnlineEditor.md b/website/translated_docs/fr-FR/OnlineEditor.md new file mode 100644 index 00000000..25469b99 --- /dev/null +++ b/website/translated_docs/fr-FR/OnlineEditor.md @@ -0,0 +1,6 @@ +--- +id: online-editor +title: Online Editor +--- + +You can also use the online editor (https://casbin.org/en/editor/) to write your Casbin model and policy in your web browser. It provides functionality such as `syntax highlighting` and `code completion`, just like an IDE for a programming language. diff --git a/website/translated_docs/fr-FR/Overview.md b/website/translated_docs/fr-FR/Overview.md new file mode 100644 index 00000000..cb6dbcf4 --- /dev/null +++ b/website/translated_docs/fr-FR/Overview.md @@ -0,0 +1,52 @@ +--- +id: overview +title: Overview +--- + +Casbin is a powerful and efficient open-source access control library. It provides support for enforcing authorization based on various access control models. + +## All the languages supported by Casbin: + +| [![golang](https://casbin.org/img/langs/golang.png)](https://github.com/casbin/casbin) | [![java](https://casbin.org/img/langs/java.png)](https://github.com/casbin/jcasbin) | [![nodejs](https://casbin.org/img/langs/nodejs.png)](https://github.com/casbin/node-casbin) | [![php](https://casbin.org/img/langs/php.png)](https://github.com/php-casbin/php-casbin) | +| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| [Casbin](https://github.com/casbin/casbin) | [jCasbin](https://github.com/casbin/jcasbin) | [node-Casbin](https://github.com/casbin/node-casbin) | [PHP-Casbin](https://github.com/php-casbin/php-casbin) | +| production-ready | production-ready | production-ready | production-ready | + +| [![python](https://casbin.org/img/langs/python.png)](https://github.com/casbin/pycasbin) | [![dotnet](https://casbin.org/img/langs/dotnet.png)](https://github.com/casbin/Casbin.NET) | [![c++](https://casbin.org/img/langs/cpp.png)](https://github.com/casbin/casbin-cpp) | [![rust](https://casbin.org/img/langs/rust.png)](https://github.com/casbin/casbin-rs) | +| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | +| [PyCasbin](https://github.com/casbin/pycasbin) | [Casbin.NET](https://github.com/casbin/Casbin.NET) | [Casbin-CPP](https://github.com/casbin/casbin-cpp) | [Casbin-RS](https://github.com/casbin/casbin-rs) | +| production-ready | production-ready | production-ready | production-ready | + +## Feature set for different languages + +| Feature | Go | Java | Node.js | PHP | Python | C# | Delphi | Rust | C++ | +| ----------------------- | -- | ---- | ------- | --- | ------ | -- | ------ | ---- | --- | +| Enforcement | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| RBAC | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ABAC | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Scaling ABAC (`eval()`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | +| Adapter | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Management API | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| RBAC API | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Batch API | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | +| Filtered Adapter | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | +| Watcher | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Role Manager | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | +| Multi-Threading | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | + +We are always working our best to make Casbin have the same set of features for all languages. But the reality is not that beautiful. The current progress is as the above table. ✅ for Watcher or Role Manager only means having the interface in the core library. Whether there is an available watcher or role manager implementation is another question. + +## What is Casbin? + +What Casbin does: + +1. enforce the policy in the classic `{subject, object, action}` form or a customized form as you defined, both allow and deny authorizations are supported. +2. handle the storage of the access control model and its policy. +3. manage the role-user mappings and role-role mappings (aka role hierarchy in RBAC). +4. support built-in superuser like `root` or `administrator`. A superuser can do anything without explicit permissions. +5. multiple built-in operators to support the rule matching. For example, `keyMatch` can map a resource key `/foo/bar` to the pattern `/foo*`. + +What Casbin does NOT do: + +1. authentication (aka verify `username` and `password` when a user logs in) +2. manage the list of users or roles. I believe it's more convenient for the project itself to manage these entities. Users usually have their passwords, and Casbin is not designed as a password container. However, Casbin stores the user-role mapping for the RBAC scenario. diff --git a/website/translated_docs/fr-FR/Performance.md b/website/translated_docs/fr-FR/Performance.md new file mode 100644 index 00000000..b2959335 --- /dev/null +++ b/website/translated_docs/fr-FR/Performance.md @@ -0,0 +1,28 @@ +--- +id: performance +title: Performance Optimization +--- + +When applied in a production environment with millions of users or permissions, you may encounter performance downgrade in Casbin enforcement, there are usually two causes: + +#### High Volume Traffic + +The number of coming requests per second is too large, e.g., 10,000 request/s for a single Casbin instance. In such case, a single Casbin instance is usually not enough to handle all the requests. There are 2 possible solutions: + +1. Use multi-threading to enable multiple Casbin instances, so you can fully utilize all the cores in the machine. See details at: [Multi-threading](/docs/en/multi-threading). + +2. Deploy Casbin instances to a cluster (multiple machines). Use Watcher to guarantee all Casbin instances are consistent. See details at: [Watchers](/docs/en/watchers). + +:::note You can use the above methods both at the same time, e.g., deploy Casbin to a 10-machine cluster. Each machine has 5 threads simultaneously to serve Casbin enforcement requests. ::: + +#### High Number of Policy Rules + +Millions of policy rules may be required in a cloud or multi-tenant environment. Each enforcement call or even loading the policy rules at the initial time is very slow. Such cases can usually be mitigated in several ways: + +1. Your Casbin model or policy is not well-designed. A well-written model and policy will abstract out the duplicated logic for each user/tenant and reduce the number of rules to a very small level (< 100): e.g., you can share some default rules across all tenants and let users customize their rules later. Customized rules can override the default rules. If you still have question, please send GitHub issue to the Casbin repos. + +2. Do sharding to let a Casbin enforcer only load a small set of policy rules, e.g., enforcer_0 only serves for tenant_0 to tenant_99, enforcer_1 only serves for tenant_100 to tenant_199. To load only a subset of all policy rules, see details at: [Policy Subset Loading](/docs/en/policy-subset-loading). + +3. Grant permissions to RBAC roles instead of users directly. Casbin's RBAC is implemented by a role inheritance tree (as a cache). So given a user like Alice, Casbin only uses O(1) time to query the RBAC tree for role-user relationship and do enforcement. If your g rules don't change often, then the RBAC tree won't need to update. See details at this dicussion: https://github.com/casbin/casbin/issues/681#issuecomment-763801583 + +:::note You can try the above methods all at the same time. ::: diff --git a/website/translated_docs/fr-FR/PolicyStorage.md b/website/translated_docs/fr-FR/PolicyStorage.md new file mode 100644 index 00000000..c27a8b01 --- /dev/null +++ b/website/translated_docs/fr-FR/PolicyStorage.md @@ -0,0 +1,6 @@ +--- +id: policy-storage +title: Policy Storage +--- + +In Casbin, the policy storage is implemented as an adapter. Please go to: [/docs/en/adapters](/docs/en/adapters) diff --git a/website/translated_docs/fr-FR/PolicySubsetLoading.md b/website/translated_docs/fr-FR/PolicySubsetLoading.md new file mode 100644 index 00000000..5ac7a67a --- /dev/null +++ b/website/translated_docs/fr-FR/PolicySubsetLoading.md @@ -0,0 +1,27 @@ +--- +id: policy-subset-loading +title: Policy Subset Loading +--- + +Some adapters support filtered policy management. This means that the policy loaded by Casbin is a subset of the policy in storage based on a given filter. This allows for efficient policy enforcement in large, multi-tenant environments when parsing the entire policy becomes a performance bottleneck. + +To use filtered policies with a supported adapter, simply call the `LoadFilteredPolicy` method. The valid format for the filter parameter depends on the adapter used. To prevent accidental data loss, the `SavePolicy` method is disabled when a filtered policy is loaded. + +For example, the following code snippet uses the built-in filtered file adapter and the RBAC model with domains. In this case, the filter limits the policy to a single domain. Any policy lines for domains other than `"domain1"` are omitted from the loaded policy: + +```go +import "github.com/casbin/casbin" + +enforcer := casbin.NewEnforcer() + +adapter := fileadapter.NewFilteredAdapter("examples/rbac_with_domains_policy.csv") +enforcer.InitWithAdapter("examples/rbac_with_domains_model.conf", adapter) + +filter := &fileadapter.Filter{ + P: []string{"", "domain1"}, + G: []string{"", "", "domain1"}, +} +enforcer.LoadFilteredPolicy(filter) + +// The loaded policy now only contains the entries pertaining to "domain1". +``` diff --git a/website/translated_docs/fr-FR/PrivacyPolicy.md b/website/translated_docs/fr-FR/PrivacyPolicy.md new file mode 100644 index 00000000..8ebfcbf0 --- /dev/null +++ b/website/translated_docs/fr-FR/PrivacyPolicy.md @@ -0,0 +1,20 @@ +--- +id: privacy-policy +title: Privacy Policy +--- + +Your privacy is important to us. It is Casbin's policy to respect your privacy regarding any information we may collect from you across our website, https://casbin.org, and other sites we own and operate. + +We only ask for personal information when we truly need it to provide a service to you. We collect it by fair and lawful means, with your knowledge and consent. We also let you know why we’re collecting it and how it will be used. + +We only retain collected information for as long as necessary to provide you with your requested service. What data we store, we’ll protect within commercially acceptable means to prevent loss and theft, as well as unauthorized access, disclosure, copying, use or modification. + +We don’t share any personally identifying information publicly or with third-parties, except when required to by law. + +Our website may link to external sites that are not operated by us. Please be aware that we have no control over the content and practices of these sites, and cannot accept responsibility or liability for their respective privacy policies. + +You are free to refuse our request for your personal information, with the understanding that we may be unable to provide you with some of your desired services. + +Your continued use of our website will be regarded as acceptance of our practices around privacy and personal information. If you have any questions about how we handle user data and personal information, feel free to contact us. + +This policy is effective as of 29 June 2020. diff --git a/website/translated_docs/fr-FR/RBAC.md b/website/translated_docs/fr-FR/RBAC.md new file mode 100644 index 00000000..c172cfbc --- /dev/null +++ b/website/translated_docs/fr-FR/RBAC.md @@ -0,0 +1,121 @@ +--- +id: rbac +title: RBAC +--- + +## Role definition + +`[role_definition]` is the definition for the RBAC role inheritance relations. Casbin supports multiple instances of RBAC systems, e.g., users can have roles and their inheritance relations, and resources can have roles and their inheritance relations too. These two RBAC systems won't interfere. + +This section is optional. If you don't use RBAC roles in the model, then omit this section. + +```ini +[role_definition] +g = _, _ +g2 = _, _ +``` + +The above role definition shows that `g` is a RBAC system, and `g2` is another RBAC system. `_, _` means there are two parties inside an inheritance relation. As a common case, you usually use `g` alone if you only need roles on users. You can also use `g` and `g2` when you need roles (or groups) on both users and resources. Please see the [rbac_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_model.conf) and [rbac_model_with_resource_roles.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_with_resource_roles_model.conf) for examples. + +Casbin stores the actual user-role mapping (or resource-role mapping if you are using roles on resources) in the policy, for example: + +``` +p, data2_admin, data2, read +g, alice, data2_admin +``` + +It means `alice` inherits/is a member of role `data2_admin`. `alice` here can be a user, a resource or a role. Casbin only recognizes it as a string. + +Then in a matcher, you should check the role as below: + +```ini +[matchers] +m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act +``` + +It means `sub` in the request should have the role `sub` in the policy. + +:::note +1. Casbin only stores the user-role mapping. +2. Casbin doesn't verify whether a user is a valid user, or role is a valid role. That should be taken care of by authentication. +3. Do not use the same name for a user and a role inside a RBAC system, because Casbin recognizes users and roles as strings, and there's no way for Casbin to know whether you are specifying user `alice` or role `alice`. You can simply solve it by using `role_alice`. +4. If `A` has role `B`, `B` has role `C`, then `A` has role `C`. This transitivity is infinite for now. ::: + +## Role hierarchy + +Casbin's RBAC supports RBAC1's role hierarchy feature, meaning if `alice` has `role1`, `role1` has `role2`, then `alice` will also have `role2` and inherit its permissions. + +Here is a concept called hierarchy level. So the hierarchy level for this example is 2. For the built-in role manager in Casbin, you can specify the max hierarchy level. The default value is 10. It means an end user like `alice` can only inherit 10 levels of roles. + +```go +// NewRoleManager is the constructor for creating an instance of the +// default RoleManager implementation. +func NewRoleManager(maxHierarchyLevel int) rbac.RoleManager { + rm := RoleManager{} + rm.allRoles = &sync.Map{} + rm.maxHierarchyLevel = maxHierarchyLevel + rm.hasPattern = false + + return &rm +} +``` + +## How to distinguish role from user? + +Casbin doesn't distinguish role from user in its RBAC. They are all treated as strings. If you only use single-level RBAC (a role will never be a member of another role). You can use `e.GetAllSubjects()` to get all users and `e.GetAllRoles()` to get all roles. They just list all `u` and all `r` respectively in all `g, u, r` rules. + +But if you are using multi-level RBAC (with role hierarchy), and your application doesn't record whether a name (string) is a user or a role, or you have user and role with same name. You can add a prefix to role like `role::admin` before passing it to Casbin. So you will know if it's a role by checking this prefix. + +## How to query implicit roles or permissions? + +When a user inherits a role or permission via RBAC hierarchy instead of directly assigning them in a policy rule, we call such type of assignment as `implicit`. To query such implicit relations, you need to use these 2 APIs: `GetImplicitRolesForUser()` and `GetImplicitPermissionsForUser` instead of `GetRolesForUser()` and `GetPermissionsForUser`. For more details, please see [this GitHub issue](https://github.com/casbin/casbin/issues/137). + +## Use pattern matching in RBAC + +Sometimes, you want some subjects, object or domains/tenants with the specific pattern to be automatically granted to a role. Pattern matching functions in RBAC can help you do that. A pattern matching function shares the same parameters and return value as the previous [matcher function](https://casbin.org/docs/en/syntax-for-models#functions-in-matchers). + +The pattern matching function supports each parameter of g. + +We know that normally RBAC is expressed as `g(r.sub, p.sub)` in matcher. Then we will use policy like: + +``` +p, alice, book_group, read +g, /book/1, book_group +g, /book/2, book_group +``` + +So `alice` can read all books including `book 1` and `book 2`. But there can be thousands of books and it's very tedious to add each book to the book role (or group) with one `g` policy rule. + +But with pattern matching functions, you can write the policy with only one line: + +``` +g, /book/:id, book_group +``` + +Casbin will automatically match `/book/1` and `/book/2` into pattern `/book/:id` for you. You only need to register the function with the enforcer like: + +```go +r := e.GetRoleManager() +r.(*defaultrolemanager.RoleManager).AddMatchingFunc("KeyMatch2",util.KeyMatch2) +``` + +When Using a pattern matching function in domains/tenants, You need to register the function to enforcer and model. + +register `keyMatch2` to enforcer: + +```go +r := e.GetRoleManager() +r.(*defaultrolemanager.RoleManager).AddDomainMatchingFunc("KeyMatch2",util.KeyMatch2) +``` + +register `keyMatch2` to model: + +``` +m = g(r.sub, p.sub, r.dom) && keyMatch2(r.dom, p.dom) && r.obj == p.obj && r.act == p.act +``` + +You can see the full example [here](https://github.com/casbin/casbin/blob/dbdb6cbe2e7a80863e4951f9ff36da07fef01b75/model_test.go#L278-L307). + +## Role manager + +See [Role Managers](/docs/en/role-managers) section for details. diff --git a/website/translated_docs/fr-FR/RBACAPI.md b/website/translated_docs/fr-FR/RBACAPI.md new file mode 100644 index 00000000..1a68ed88 --- /dev/null +++ b/website/translated_docs/fr-FR/RBACAPI.md @@ -0,0 +1,672 @@ +--- +id: rbac-api +title: RBAC API +--- + +A more friendly API for RBAC. This API is a subset of Management API. The RBAC users could use this API to simplify the code. + +## Reference + +global variable `e` is Enforcer instance. + + + + +```go +e, err := NewEnforcer("examples/rbac_model.conf", "examples/rbac_policy.csv") +``` + + +```typescript +const e = await newEnforcer('examples/rbac_model.conf', 'examples/rbac_policy.csv') +``` + + +```php +$e = new Enforcer('examples/rbac_model.conf', 'examples/rbac_policy.csv'); +``` + + +```csharp +var e = new Enforcer("path/to/model.conf", "path/to/policy.csv"); +``` + + +```rust +let mut e = Enforcer::new("examples/rbac_model.conf", "examples/rbac_policy.csv").await?; +``` + + + + +### `GetRolesForUser()` + +GetRolesForUser gets the roles that a user has. + +For example: + + + + +```go +res := e.GetRolesForUser("alice") +``` + + +```typescript +const res = await e.getRolesForUser('alice') +``` + + +```php +$res = $e->getRolesForUser("alice"); +``` + + +```csharp +var res = e.GetRolesForUser("alice"); +``` + + +```rust +let roles = e.get_roles_for_user("alice", None); // No domain +``` + + + +### `GetUsersForRole()` + +GetUsersForRole gets the users that has a role. + +For example: + + + + +```go +res := e.GetUsersForRole("data1_admin") +``` + + +```typescript +const res = await e.getUsersForRole('data1_admin') +``` + + +```php +$res = $e->getUsersForRole("data1_admin"); +``` + + +```csharp +var res = e.GetUsersForRole("data1_admin"); +``` + + +```rust +let users = e.get_users_for_role("data1_admin", None); // No domain +``` + + + +### `HasRoleForUser()` + +HasRoleForUser determines whether a user has a role. + +For example: + + + + +```go +res := e.HasRoleForUser("alice", "data1_admin") +``` + + +```typescript +const res = await e.hasRoleForUser('alice', 'data1_admin') +``` + + +```php +$res = $e->hasRoleForUser("alice", "data1_admin"); +``` + + +```csharp +var res = e.HasRoleForUser("alice", "data1_admin"); +``` + + +```rust +let has = e.has_role_for_user("alice", "data1_admin", None); // No domain +``` + + + +### `AddRoleForUser()` + +AddRoleForUser adds a role for a user. Returns false if the user already has the role (aka not affected). + +For example: + + + + +```go +e.AddRoleForUser("alice", "data2_admin") +``` + + +```typescript +await e.addRoleForUser('alice', 'data2_admin') +``` + + +```PHP +$e->addRoleForUser("alice", "data2_admin"); +``` + + +```csharp +var added = e.AddRoleForUser("alice", "data2_admin"); +or +var added = await e.AddRoleForUserAsync("alice", "data2_admin"); +``` + + +```rust +let added = e.add_role_for_user("alice", "data2_admin", None).await?; // No domain +``` + + + + +### `AddRolesForUser()` + +AddRolesForUser adds multiple roles for a user. Returns false if the user already has one of these roles (aka not affected). + +For example: + + + + +```rust +let roles = vec!["data1_admin".to_owned(), "data2_admin".to_owned()]; +let all_added = e.add_roles_for_user("alice", roles, None).await?; // No domain +``` + + + + +### `DeleteRoleForUser()` + +DeleteRoleForUser deletes a role for a user. Returns false if the user does not have the role (aka not affected). + +For example: + + + + +```go +e.DeleteRoleForUser("alice", "data1_admin") +``` + + +```typescript +await e.deleteRoleForUser('alice', 'data1_admin') +``` + + +```php +$e->deleteRoleForUser("alice", "data1_admin"); +``` + + +```csharp +var deleted = e.DeleteRoleForUser("alice", "data1_admin"); +or +var deleted = await e.DeleteRoleForUser("alice", "data1_admin"); +``` + + +```rust +let deleted = e.delete_role_for_user("alice", "data1_admin", None).await?; // No domain +``` + + + + +### `DeleteRolesForUser()` + +DeleteRolesForUser deletes all roles for a user. Returns false if the user does not have any roles (aka not affected). + +For example: + + + + +```go +e.DeleteRolesForUser("alice") +``` + + +```typescript +await e.deleteRolesForUser('alice') +``` + + +```php +$e->deleteRolesForUser("alice"); +``` + + +```csharp +var deletedAtLeastOne = e.DeleteRolesForUser("alice"); +or +var deletedAtLeastOne = await e.DeleteRolesForUserAsync("alice"); +``` + + +```rust +let deleted_at_least_one = e.delete_roles_for_user("alice", None).await?; // No domain +``` + + + +### `DeleteUser()` + +DeleteUser deletes a user. Returns false if the user does not exist (aka not affected). + +For example: + + + + +``` +e.DeleteUser("alice") +``` + + +```typescript +await e.deleteUser('alice') +``` + + +```php +$e->deleteUser("alice"); +``` + + +```csharp +var deleted = e.DeleteUser("alice"); +or +var deleted = await e.DeleteUserAsync("alice"); +``` + + +```rust +let deleted = e.delete_user("alice").await?; +``` + + + +### `DeleteRole()` + +DeleteRole deletes a role. + +For example: + + + + +```go +e.DeleteRole("data2_admin") +``` + + +```typescript +await e.deleteRole("data2_admin") +``` + + +```php +$e->deleteRole("data2_admin"); +``` + + +```csharp +var deleted = e.DeleteRole("data2_admin"); +or +var deleted = await e.DeleteRoleAsync("data2_admin"); +``` + + +```rust +let deleted = e.delete_role("data2_admin").await?; +``` + + + +### `DeletePermission()` + +DeletePermission deletes a permission. Returns false if the permission does not exist (aka not affected). + +For example: + + + + +```go +e.DeletePermission("read") +``` + + +```typescript +await e.deletePermission('read') +``` + + +```php +$e->deletePermission("read"); +``` + + +```csharp +var deleted = e.DeletePermission("read"); +or +var deleted = await e.DeletePermissionAsync("read"); +``` + + +```rust +let deleted = e.delete_permission(vec!["read".to_owned()]).await?; +``` + + + + +### `AddPermissionForUser()` + +AddPermissionForUser adds a permission for a user or role. Returns false if the user or role already has the permission (aka not affected). + +For example: + + + + +```go +e.AddPermissionForUser("bob", "read") +``` + + +```typescript +await e.addPermissionForUser('bob', 'read') +``` + + +```php +$e->addPermissionForUser("bob", "read"); +``` + + +```csharp +var added = e.AddPermissionForUser("bob", "read"); +or +var added = await e.AddPermissionForUserAsync("bob", "read"); +``` + + +```rust +let added = e.add_permission_for_user("bob", vec!["read".to_owned()]).await?; +``` + + + +### `AddPermissionsForUser()` + +AddPermissionsForUser adds multiple permissions for a user or role. Returns false if the user or role already has one of the permissions (aka not affected). + +For example: + + + + +```rust +let permissions = vec![ + vec!["data1".to_owned(), "read".to_owned()], + vec!["data2".to_owned(), "write".to_owned()], +]; + +let all_added = e.add_permissions_for_user("bob", permissions).await?; +``` + + + + +### `DeletePermissionForUser()` + +DeletePermissionForUser deletes a permission for a user or role. Returns false if the user or role does not have the permission (aka not affected). + +For example: + + + + +```go +e.DeletePermissionForUser("bob", "read") +``` + + +```typescript +await e.deletePermissionForUser("bob", "read") +``` + + +```php +$e->deletePermissionForUser("bob", "read"); +``` + + +```csharp +var deleted = e.DeletePermissionForUser("bob", "read"); +or +var deleted = await e.DeletePermissionForUserAsync("bob", "read"); +``` + + +```rust +let deleted = e.delete_permission_for_user("bob", vec!["read".to_owned()]).await?; +``` + + + + +### `DeletePermissionsForUser()` + +DeletePermissionsForUser deletes permissions for a user or role. Returns false if the user or role does not have any permissions (aka not affected). + +For example: + + + + +```go +e.DeletePermissionsForUser("bob") +``` + + +```typescript +await e.deletePermissionsForUser('bob') +``` + + +```php +$e->deletePermissionsForUser("bob"); +``` + + +```csharp +var deletedAtLeastOne = e.DeletePermissionsForUser("bob"); +or +var deletedAtLeastOne = await e.DeletePermissionsForUserAsync("bob"); +``` + + +```rust +let deleted_at_least_one = e.delete_permissions_for_user("bob").await?; +``` + + + +### `GetPermissionsForUser()` + +GetPermissionsForUser gets permissions for a user or role. + +For example: + + + + +```go +e.GetPermissionsForUser("bob") +``` + + +```typescript +await e.getPermissionsForUser('bob') +``` + + +```php +$e->getPermissionsForUser("bob"); +``` + + +```csharp +var permissions = e.GetPermissionsForUser("bob"); +``` + + + +### `HasPermissionForUser()` + +HasPermissionForUser determines whether a user has a permission. + +For example: + + + + +```go +e.HasPermissionForUser("alice", []string{"read"}) +``` + + +```typescript +await e.hasPermissionForUser('alice', 'read') +``` + + +```php +$e->hasPermissionForUser("alice", []string{"read"}); +``` + + +```csharp +var has = e.HasPermissionForUser("bob", "read"); +``` + + +```rust +let has = e.has_permission_for_user("alice", vec!["data1".to_owned(), "read".to_owned()]); +``` + + + +### `GetImplicitRolesForUser()` + +GetImplicitRolesForUser gets implicit roles that a user has. Compared to GetRolesForUser(), this function retrieves indirect roles besides direct roles. + +For example: +g, alice, role:admin +g, role:admin, role:user + +GetRolesForUser("alice") can only get: ["role:admin"]. +But GetImplicitRolesForUser("alice") will get: ["role:admin", "role:user"]. + + +For example: + + + + +```go +e.GetImplicitRolesForUser("alice") +``` + + +```typescript +await e.getImplicitRolesForUser("alice") +``` + + +```php +$e->getImplicitRolesForUser("alice"); +``` + + +```csharp +var implicitRoles = e.GetImplicitRolesForUser("alice"); +``` + + +```rust +e.get_implicit_roles_for_user("alice", None); // No domain +``` + + + +### `GetImplicitPermissionsForUser()` + +GetImplicitPermissionsForUser gets implicit permissions for a user or role. +Compared to GetPermissionsForUser(), this function retrieves permissions for inherited roles. + +For example: +p, admin, data1, read +p, alice, data2, read +g, alice, admin + +GetPermissionsForUser("alice") can only get: [["alice", "data2", "read"]]. +But GetImplicitPermissionsForUser("alice") will get: [["admin", "data1", "read"], ["alice", "data2", "read"]]. + +For example: + + + + +```go +e.GetImplicitPermissionsForUser("alice") +``` + + +```text +await e.getImplicitPermissionsForUser("alice") +``` + + +```php +$e->getImplicitPermissionsForUser("alice"); +``` + + +```csharp +var implicitPermissions = e.GetImplicitPermissionsForUser("alice"); +``` + + +```rust +e.get_implicit_permissions_for_user("alice", None); // No domain +``` + + diff --git a/website/translated_docs/fr-FR/RBACWithDomains.md b/website/translated_docs/fr-FR/RBACWithDomains.md new file mode 100644 index 00000000..089a68cc --- /dev/null +++ b/website/translated_docs/fr-FR/RBACWithDomains.md @@ -0,0 +1,36 @@ +--- +id: rbac-with-domains +title: RBAC with Domains +--- + +## Role definition with domains tenants + +The RBAC roles in Casbin can be global or domain-specific. Domain-specify roles mean that the roles for a user can be different when the user is at different domains/tenants. This is very useful for large systems like a cloud, as the users are usually in different tenants. + +The role definition with domains/tenants should be something like: + +```ini +[role_definition] +g = _, _, _ +``` + +The 3rd `_` means the name of domain/tenant, this part should not be changed. Then the policy can be: + +``` +p, admin, tenant1, data1, read +p, admin, tenant2, data2, read + +g, alice, admin, tenant1 +g, alice, user, tenant2 +``` + +It means `admin` role in `tenant1` can read `data1`. And `alice` has `admin` role in `tenant1`, and has `user` role in `tenant2`. So she can read `data1`. However, since `alice` is not an `admin` in `tenant2`, she cannot read `data2`. + +Then in a matcher, you should check the role as below: + +```ini +[matchers] +m = g(r.sub, p.sub, r.dom) && r.dom == p.dom && r.obj == p.obj && r.act == p.act +``` + +Please see the [rbac_with_domains_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_with_domains_model.conf) for examples. diff --git a/website/translated_docs/fr-FR/RoleManagers.md b/website/translated_docs/fr-FR/RoleManagers.md new file mode 100644 index 00000000..ced3c279 --- /dev/null +++ b/website/translated_docs/fr-FR/RoleManagers.md @@ -0,0 +1,49 @@ +--- +id: role-managers +title: Role Managers +--- + +The role manager is used to manage the RBAC role hierarchy (user-role mapping) in Casbin. A role manager can retrieve the role data from Casbin policy rules or external sources such as LDAP, Okta, Auth0, Azure AD, etc. We support different implementations of a role manager. To keep light-weight, we don't put role manager code in the main library (except the default role manager). A complete list of Casbin role managers is provided as below. Any 3rd-party contribution on a new role manager is welcomed, please inform us and I will put it in this list:) + + + + +| Role manager | Author | Description | +| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Default Role Manager (built-in)](https://github.com/casbin/casbin/blob/master/rbac/default-role-manager/role_manager.go) | Casbin | Supports role hierarchy stored in Casbin policy | +| [Session Role Manager](https://github.com/casbin/session-role-manager) | [EDOMO Systems](https://github.com/edomosystems) | Supports role hierarchy stored in Casbin policy, with time-range-based sessions | +| [Okta Role Manager](https://github.com/casbin/okta-role-manager) | Casbin | Supports role hierarchy stored in [Okta](https://www.okta.com/) | +| [Auth0 Role Manager](https://github.com/casbin/auth0-role-manager) | Casbin | Supports role hierarchy stored in [Auth0](https://auth0.com/)'s [Authorization Extension](https://auth0.com/docs/extensions/authorization-extension/v2) | + +For developers: all role managers must implement the [RoleManager](https://github.com/casbin/casbin/blob/master/rbac/role_manager.go) interface. [Session Role Manager](https://github.com/casbin/session-role-manager) can be used as a reference implementation. + + +| Role manager | Author | Description | +| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------- | +| [Default Role Manager (built-in)](https://github.com/casbin/jcasbin/blob/master/src/main/java/org/casbin/jcasbin/rbac/DefaultRoleManager.java) | Casbin | Supports role hierarchy stored in Casbin policy | + +For developers: all role managers must implement the [RoleManager](https://github.com/casbin/jcasbin/blob/master/src/main/java/org/casbin/jcasbin/rbac/RoleManager.java) interface. [Default Role Manager](https://github.com/casbin/jcasbin/blob/master/src/main/java/org/casbin/jcasbin/rbac/DefaultRoleManager.java) can be used as a reference implementation. + + +| Role manager | Author | Description | +| ------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------- | +| [Default Role Manager (built-in)](https://github.com/casbin/node-casbin/blob/master/src/rbac/defaultRoleManager.ts) | Casbin | Supports role hierarchy stored in Casbin policy | +| [Session Role Manager](https://github.com/node-casbin/session-role-manager) | Casbin | Supports role hierarchy stored in Casbin policy, with time-range-based sessions | + +For developers: all role managers must implement the [RoleManager](https://github.com/casbin/node-casbin/blob/master/src/rbac/roleManager.ts) interface. [Default Role Manager](https://github.com/casbin/node-casbin/blob/master/src/rbac/defaultRoleManager.ts) can be used as a reference implementation. + + +| Role manager | Author | Description | +| ----------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------- | +| [Default Role Manager (built-in)](https://github.com/php-casbin/php-casbin/blob/master/src/Rbac/DefaultRoleManager/RoleManager.php) | Casbin | Supports role hierarchy stored in Casbin policy | + +For developers: all role managers must implement the [RoleManager](https://github.com/php-casbin/php-casbin/blob/master/src/Rbac/RoleManager.php) interface. [Default Role Manager](https://github.com/php-casbin/php-casbin/blob/master/src/Rbac/DefaultRoleManager/RoleManager.php) can be used as a reference implementation. + + +| Role manager | Author | Description | +| ---------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------- | +| [Default Role Manager (built-in)](https://github.com/casbin/pycasbin/blob/master/casbin/rbac/default_role_manager/role_manager.py) | Casbin | Supports role hierarchy stored in Casbin policy | + +For developers: all role managers must implement the [RoleManager](https://github.com/casbin/pycasbin/blob/master/casbin/rbac/role_manager.py) interface. [Default Role Manager](https://github.com/casbin/pycasbin/blob/master/casbin/rbac/default_role_manager/role_manager.py) can be used as a reference implementation. + + diff --git a/website/translated_docs/fr-FR/Service.md b/website/translated_docs/fr-FR/Service.md new file mode 100644 index 00000000..7dba6f9e --- /dev/null +++ b/website/translated_docs/fr-FR/Service.md @@ -0,0 +1,13 @@ +--- +id: service +title: Casbin Service +--- + +## How to use Casbin as a service? + +| Name | Description | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Casbin Server](https://github.com/casbin/casbin-server) | The official `Casbin as a Service` solution based on [gRPC](https://grpc.io/), both Management API and RBAC API are provided. | +| [PaySuper Casbin Server](https://github.com/paysuper/casbin-server) | PaySuper's fork of the above official `Casbin-Server` but more actively maintained. It provides [go-micro](https://micro.mu/) interface for Casbin authorization. | +| [Go-Simple-API-Gateway (Archived)](https://github.com/Soontao/go-simple-api-gateway) | A simple API gateway written by golang, supports for authentication and authorization. | +| [middleware-acl](https://github.com/luk4z7/middleware-acl) | RESTful access control middleware based on Casbin. | diff --git a/website/translated_docs/fr-FR/SupportedModels.md b/website/translated_docs/fr-FR/SupportedModels.md new file mode 100644 index 00000000..6bbcffdc --- /dev/null +++ b/website/translated_docs/fr-FR/SupportedModels.md @@ -0,0 +1,33 @@ +--- +id: supported-models +title: Supported Models +--- + +1. [**ACL (Access Control List)**](https://en.wikipedia.org/wiki/Access_control_list) +2. **ACL with [superuser](https://en.wikipedia.org/wiki/Superuser)** +3. **ACL without users**: especially useful for systems that don't have authentication or user log-ins. +3. **ACL without resources**: some scenarios may target for a type of resources instead of an individual resource by using permissions like `write-article`, `read-log`. It doesn't control the access to a specific article or log. +4. **[RBAC (Role-Based Access Control)](https://en.wikipedia.org/wiki/Role-based_access_control)** +5. **RBAC with resource roles**: both users and resources can have roles (or groups) at the same time. +6. **RBAC with domains/tenants**: users can have different role sets for different domains/tenants. +7. **[ABAC (Attribute-Based Access Control)](https://en.wikipedia.org/wiki/Attribute-Based_Access_Control)**: syntax sugar like `resource.Owner` can be used to get the attribute for a resource. +8. **[RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer)**: supports paths like `/res/*`, `/res/:id` and HTTP methods like `GET`, `POST`, `PUT`, `DELETE`. +9. **Deny-override**: both allow and deny authorizations are supported, deny overrides the allow. +10. **Priority**: the policy rules can be prioritized like firewall rules. + +## Examples + +| Model | Model file | Policy file | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | +| ACL | [basic_model.conf](https://github.com/casbin/casbin/blob/master/examples/basic_model.conf) | [basic_policy.csv](https://github.com/casbin/casbin/blob/master/examples/basic_policy.csv) | +| ACL with superuser | [basic_with_root_model.conf](https://github.com/casbin/casbin/blob/master/examples/basic_with_root_model.conf) | [basic_policy.csv](https://github.com/casbin/casbin/blob/master/examples/basic_policy.csv) | +| ACL without users | [basic_without_users_model.conf](https://github.com/casbin/casbin/blob/master/examples/basic_without_users_model.conf) | [basic_without_users_policy.csv](https://github.com/casbin/casbin/blob/master/examples/basic_without_users_policy.csv) | +| ACL without resources | [basic_without_resources_model.conf](https://github.com/casbin/casbin/blob/master/examples/basic_without_resources_model.conf) | [basic_without_resources_policy.csv](https://github.com/casbin/casbin/blob/master/examples/basic_without_resources_policy.csv) | +| RBAC | [rbac_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_model.conf) | [rbac_policy.csv](https://github.com/casbin/casbin/blob/master/examples/rbac_policy.csv) | +| RBAC with resource roles | [rbac_with_resource_roles_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_with_resource_roles_model.conf) | [rbac_with_resource_roles_policy.csv](https://github.com/casbin/casbin/blob/master/examples/rbac_with_resource_roles_policy.csv) | +| RBAC with domains/tenants | [rbac_with_domains_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_with_domains_model.conf) | [rbac_with_domains_policy.csv](https://github.com/casbin/casbin/blob/master/examples/rbac_with_domains_policy.csv) | +| ABAC | [abac_model.conf](https://github.com/casbin/casbin/blob/master/examples/abac_model.conf) | N/A | +| RESTful | [keymatch_model.conf](https://github.com/casbin/casbin/blob/master/examples/keymatch_model.conf) | [keymatch_policy.csv](https://github.com/casbin/casbin/blob/master/examples/keymatch_policy.csv) | +| Deny-override | [rbac_with_not_deny_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_with_not_deny_model.conf) | [rbac_with_deny_policy.csv](https://github.com/casbin/casbin/blob/master/examples/rbac_with_deny_policy.csv) | +| Allow-and-deny | [rbac_with_deny_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_with_deny_model.conf) | [rbac_with_deny_policy.csv](https://github.com/casbin/casbin/blob/master/examples/rbac_with_deny_policy.csv) | +| Priority | [priority_model.conf](https://github.com/casbin/casbin/blob/master/examples/priority_model.conf) | [priority_policy.csv](https://github.com/casbin/casbin/blob/master/examples/priority_policy.csv) | diff --git a/website/translated_docs/fr-FR/SyntaxForModels.md b/website/translated_docs/fr-FR/SyntaxForModels.md new file mode 100644 index 00000000..055b8f0a --- /dev/null +++ b/website/translated_docs/fr-FR/SyntaxForModels.md @@ -0,0 +1,121 @@ +--- +id: syntax-for-models +title: Syntax for Models +--- + +- A model CONF should have at least four sections: `[request_definition], [policy_definition], [policy_effect], [matchers]`. + +- If a model uses RBAC, it should also add the `[role_definition]` section. + +- A model CONF can contain comments. The comments start with `#`, and `#` will comment the rest of the line. + +## Request definition + +`[request_definition]` is the definition for the access request. It defines the arguments in `e.Enforce(...)` function. + +```ini +[request_definition] +r = sub, obj, act +``` + +`sub, obj, act` represents the classic triple: accessing entity (Subject), accessed resource (Object) and the access method (Action). However, you can customize your own request form, like `sub, act` if you don't need to specify an particular resource, or `sub, sub2, obj, act` if you somehow have two accessing entities. + +## Policy definition + +`[policy_definition]` is the definition for the policy. It defines the meaning of the policy. For example, we have the following model: + +```ini +[policy_definition] +p = sub, obj, act +p2 = sub, act +``` + +And we have the following policy (if in a policy file) + +``` +p, alice, data1, read +p2, bob, write-all-objects +``` + +Each line in a policy is called a policy rule. Each policy rule starts with a `policy type`, e.g., `p`, `p2`. It is used to match the policy definition if there are multiple definitions. The above policy shows the following binding. The binding can be used in the matcher. + +``` +(alice, data1, read) -> (p.sub, p.obj, p.act) +(bob, write-all-objects) -> (p2.sub, p2.act) +``` + +:::note Currently only single policy definition `p` is supported. `p2` is yet not supported. Because for common cases, our user doesn't have the need to use multiple policy definitions. If your requirement has to use additional policy definitions, please send an issue about it. ::: + +:::tip The elements in a policy rule are always regarded as`string`. If you have any question about this, please see the discussion at: https://github.com/casbin/casbin/issues/113 ::: + +## Policy effect + +`[policy_effect]` is the definition for the policy effect. It defines whether the access request should be approved if multiple policy rules match the request. For example, one rule permits and the other denies. + +```ini +[policy_effect] +e = some(where (p.eft == allow)) +``` + +The above policy effect means if there's any matched policy rule of `allow`, the final effect is `allow` (aka allow-override). `p.eft` is the effect for a policy, it can be `allow` or `deny`. It's optional and the default value is `allow`. So as we didn't specify it above, it uses the default value. + +Another example for policy effect is: + +```ini +[policy_effect] +e = !some(where (p.eft == deny)) +``` + +It means if there's no matched policy rules of`deny`, the final effect is `allow` (aka deny-override). `some` means: if there exists one matched policy rule. `any` means: all matched policy rules (not used here). The policy effect can even be connected with logic expressions: + +```ini +[policy_effect] +e = some(where (p.eft == allow)) && !some(where (p.eft == deny)) +``` + +It means at least one matched policy rule of`allow`, and there is no matched policy rule of`deny`. So in this way, both the allow and deny authorizations are supported, and the deny overrides. + +:::note Although we designed the syntax of policy effect as above, the current implementations only use hard-coded policy effect, as we found there's no much need for that sort of flexibility. So for now, you must use one of the built-in policy effects instead of customizing your own one. ::: + +The supported built-in policy effects are: + +| Policy effect | Meaning | Example | +| ------------------------------------------------------------ | -------------- | ----------------------------------------------------- | +| some(where (p.eft == allow)) | allow-override | [ACL, RBAC, etc.](/docs/en/supported-models#examples) | +| !some(where (p.eft == deny)) | deny-override | [Deny-override](/docs/en/supported-models#examples) | +| some(where (p.eft == allow)) && !some(where (p.eft == deny)) | allow-and-deny | [Allow-and-deny](/docs/en/supported-models#examples) | +| priority(p.eft) || deny | priority | [Priority](/docs/en/supported-models#examples) | + +## Matchers + +`[matchers]` is the definition for policy matchers. The matchers are expressions. It defines how the policy rules are evaluated against the request. + +```ini +[matchers] +m = r.sub == p.sub && r.obj == p.obj && r.act == p.act +``` + +The above matcher is the simplest, it means that the subject, object and action in a request should match the ones in a policy rule. + +You can use arithmetic like `+, -, *, /` and logical operators like `&&, ||, !` in matchers. + +:::note Although it seems like there will be multiple matchers such as `m1`, `m2` like other primitives, currently, we only support one matcher `m`. You can always use the above logical operators to implement complicated logic judgment in one matcher. So we believe there is no need to support multiple matchers for now. Let me know if you have other opinions. ::: + +### Expression evaluator + +The matcher evaluation in Casbin is implemented by expression evaluators in each language. Casbin integrates their powers to provide the unified PERM language. Besides all the model syntax provided here, those expression evaluators may provide extra functionality, which may be not supported by another language or implementation. Use it at your own risk. + +The expression evaluators used by each Casbin implementation are: + +| Implementation | Language | Expression evaluator | +| -------------- | -------- | -------------------------------------------------------------------------------------------------- | +| Casbin | Golang | https://github.com/Knetic/govaluate | +| jCasbin | Java | https://github.com/killme2008/aviator | +| Node-Casbin | Node.js | https://github.com/donmccurdy/expression-eval | +| PHP-Casbin | PHP | https://github.com/symfony/expression-language | +| PyCasbin | Python | https://github.com/danthedeckie/simpleeval | +| Casbin.NET | C# | https://github.com/davideicardi/DynamicExpresso | +| Casbin4D | Delphi | https://github.com/casbin4d/Casbin4D/tree/master/SourceCode/Common/Third%20Party/TExpressionParser | +| casbin-rs | Rust | https://github.com/jonathandturner/rhai | + +:::note If you encounter performance issue about Casbin, it's probably caused by the low efficiency of the expression evaluator. You can both send issue to Casbin or the expression evaluator directly for advice to speed up. See [Benchmarks](/docs/en/benchmark) section for details. ::: diff --git a/website/translated_docs/fr-FR/TermsOfService.md b/website/translated_docs/fr-FR/TermsOfService.md new file mode 100644 index 00000000..9200d7ec --- /dev/null +++ b/website/translated_docs/fr-FR/TermsOfService.md @@ -0,0 +1,46 @@ +--- +id: terms-of-service +title: Terms of Service +--- + +1. Terms + +By accessing the website at https://casbin.org, you are agreeing to be bound by these terms of service, all applicable laws and regulations, and agree that you are responsible for compliance with any applicable local laws. If you do not agree with any of these terms, you are prohibited from using or accessing this site. The materials contained in this website are protected by applicable copyright and trademark law. + +2. Use License + +a. Permission is granted to temporarily download one copy of the materials (information or software) on Casbin's website for personal, non-commercial transitory viewing only. This is the grant of a license, not a transfer of title, and under this license you may not: + +- i. modify or copy the materials; +- ii. use the materials for any commercial purpose, or for any public display (commercial or non-commercial); +- iii. attempt to decompile or reverse engineer any software contained on Casbin's website; +- iv. remove any copyright or other proprietary notations from the materials; or +- v. transfer the materials to another person or "mirror" the materials on any other server. + +b. This license shall automatically terminate if you violate any of these restrictions and may be terminated by Casbin at any time. Upon terminating your viewing of these materials or upon the termination of this license, you must destroy any downloaded materials in your possession whether in electronic or printed format. + +3. Disclaimer + +a. The materials on Casbin's website are provided on an 'as is' basis. Casbin makes no warranties, expressed or implied, and hereby disclaims and negates all other warranties including, without limitation, implied warranties or conditions of merchantability, fitness for a particular purpose, or non-infringement of intellectual property or other violation of rights. + +b. Further, Casbin does not warrant or make any representations concerning the accuracy, likely results, or reliability of the use of the materials on its website or otherwise relating to such materials or on any sites linked to this site. + +4. Limitations + +In no event shall Casbin or its suppliers be liable for any damages (including, without limitation, damages for loss of data or profit, or due to business interruption) arising out of the use or inability to use the materials on Casbin's website, even if Casbin or a Casbin authorized representative has been notified orally or in writing of the possibility of such damage. Because some jurisdictions do not allow limitations on implied warranties, or limitations of liability for consequential or incidental damages, these limitations may not apply to you. + +5. Accuracy of materials + +The materials appearing on Casbin's website could include technical, typographical, or photographic errors. Casbin does not warrant that any of the materials on its website are accurate, complete or current. Casbin may make changes to the materials contained on its website at any time without notice. However Casbin does not make any commitment to update the materials. + +6. Links + +Casbin has not reviewed all of the sites linked to its website and is not responsible for the contents of any such linked site. The inclusion of any link does not imply endorsement by Casbin of the site. Use of any such linked website is at the user's own risk. + +7. Modifications + +Casbin may revise these terms of service for its website at any time without notice. By using this website you are agreeing to be bound by the then current version of these terms of service. + +8. Governing Law + +These terms and conditions are governed by and construed in accordance with the laws of San Francisco, CA and you irrevocably submit to the exclusive jurisdiction of the courts in that State or location. diff --git a/website/translated_docs/fr-FR/Tutorial.md b/website/translated_docs/fr-FR/Tutorial.md new file mode 100644 index 00000000..a02dc184 --- /dev/null +++ b/website/translated_docs/fr-FR/Tutorial.md @@ -0,0 +1,143 @@ +--- +id: tutorials +title: Tutorials +--- + +Some tutorials are for the Casbin's model and work for all Casbin implementations in different languages. Some other tutorials are language-specific. + +### Our Papers + +- [PML: An Interpreter-Based Access Control Policy Language for Web Services](https://arxiv.org/abs/1903.09756) + +This paper digs deeply into the design details about Casbin. Please cite the following BibTex if you use Casbin/PML as a reference in your paper: + +```bibtex +@article{luo2019pml, + title={PML: An Interpreter-Based Access Control Policy Language for Web Services}, + author={Luo, Yang and Shen, Qingni and Wu, Zhonghai}, + journal={arXiv preprint arXiv:1903.09756}, + year={2019} +} +``` + +- [Access Control Policy Specification Language Based on Metamodel (in Chinese)](http://www.jos.org.cn/1000-9825/5624.htm) + +This is another longer-version paper published in Journal of Software. The citation for different formats (Refworks, EndNote, etc.) can be found at: https://kns.cnki.net/kcms/detail/Detail.aspx?dbname=CJFDLAST2020&filename=RJXB202002012&v= + +### Videos + +- [A Secure Vault - implementing authorization middleware with Casbin - JuniorDevSG](https://www.youtube.com/watch?v=OTT84oplR9o) +- [Sharing user permissions in a micro-service architecture based on Casbin (in Russian)](https://www.youtube.com/watch?v=Z5dUxH4PqYM) +- [Nest.js - Casbin RESTful RBAC authorization midleware](https://www.youtube.com/watch?v=mWlPNrCgVdE) +- [Gin Tutorial Chapter 10: Learn Casbin basic models in 30 minutes](https://www.bilibili.com/video/BV1qz4y167XP) +- [Gin Tutorial Chapter 11: Coding, API and custom function in Casbin](https://www.bilibili.com/video/BV13r4y1M7AC) +- [Gin + Casbin: Learning Permissions in Action (in Chinese)](https://www.jtthink.com/course/132) +- [jCasbin Basics: A simple RBAC example (in Chinese)](https://www.jtthink.com/course/play/2706) +- [Golang's RBAC based on Casbin (in Chinese)](https://www.bilibili.com/video/BV1Kf4y1U7iJ) +- [Learning Gin + Casbin (1): Opening & Overview (in Chinese)](https://www.bilibili.com/video/BV1bp4y1a7je) +- [ThinkPHP 5.1 + Casbin: Introduction (in Chinese)](https://www.bilibili.com/video/BV1kz4y1Z7vd) +- [ThinkPHP 5.1 + Casbin: RBAC authorization (in Chinese)](https://www.bilibili.com/video/BV1A541187M4) +- [ThinkPHP 5.1 + Casbin: RESTful & Middleware (in Chinese)](https://www.bilibili.com/video/BV1uk4y117up) +- [Quick Start for PHP-Casbin (in Chinese)](https://www.bilibili.com/video/BV1dK4y1L7xy) + +### PERM Meta-Model (Policy, Effect, Request, Matchers) + +- [Modeling Authorization with PERM in Casbin](https://vicarie.in/posts/generalized-authz.html) +- [Designing a Flexible Permissions System with Casbin](https://medium.com/silo-blog/designing-a-flexible-permissions-system-with-casbin-f5d97fef17b8) +- [Access control with PERM and Casbin (in Persian)](https://vrgl.ir/npwoy) +- [RBAC? ABAC? .. PERM! New Way of Authorization for Cloud-Based Web Services and Apps (in Russian)](https://habr.com/ru/post/539778/) +- [Practice & Examples of Flexible Authorization Using Casbin & PERM (in Russian)](https://habr.com/ru/post/540454/) +- [Permission management with Casbin (in Chinese)](http://www.cnblogs.com/wang_yb/archive/2018/11/20/9987397.html) +- [Analysis of Casbin (in Chinese)](https://www.cnblogs.com/xiaohunshi/p/10372881.html) +- [Design of System Permissions (in Chinese)](https://github.com/xizhibei/blog/issues/101) +- [Casbin: A Permission Engine (in Chinese)](https://github.com/xizhibei/blog/issues/102) +- [Implementing ABAC with Casbin (in Chinese)](https://www.cnblogs.com/studyzy/p/11380736.html) +- [Source code analysis of Casbin (in Chinese)](https://www.cnblogs.com/yjf512/p/12200206.html) +- [Permission evaluation with Casbin (in Chinese)](https://cloud.tencent.com/developer/article/1534674) +- [Casbin: Library of the day for Go (in Chinese)](https://juejin.im/post/5ee6c93ce51d45787d3484a1) + + + + + +### HTTP & RESTful + +- [Basic Role-Based HTTP Authorization in Go with Casbin](https://zupzup.org/casbin-http-role-auth) (or [Chinese translation](https://studygolang.com/articles/12323)) + +### Beego + +- [Using Casbin with Beego: 1. Get started and test (in Chinese)](https://blog.csdn.net/hotqin888/article/details/78460385) +- [Using Casbin with Beego: 2. Policy storage (in Chinese)](https://blog.csdn.net/hotqin888/article/details/78571240) +- [Using Casbin with Beego: 3. Policy query (in Chinese)](https://blog.csdn.net/hotqin888/article/details/78992250) +- [Using Casbin with Beego: 4. Policy update (in Chinese)](https://blog.csdn.net/hotqin888/article/details/80032538) +- [Using Casbin with Beego: 5. Policy update (continued) (in Chinese)](https://blog.csdn.net/hotqin888/article/details/80092285) + +### Gin + +- [Tutorial: Integrate Gin with Cabsin](https://dev.to/maxwellhertz/tutorial-integrate-gin-with-cabsin-56m0) +- [Policy enforcements on K8s with Pipeline](https://banzaicloud.com/blog/policy-enforcement-k8s/) +- [Authentication and authorization in Gin application with JWT and Casbin](https://medium.com/@tienbm90/authentication-and-authorization-in-gin-application-with-jwt-and-casbin-a56bbbdec90b) +- [Backend API with Go: 1. Authentication based on JWT (in Chinese)](https://studygolang.com/topics/6998) +- [Backend API with Go: 2. Authorization based on Casbin (in Chinese)](https://studygolang.com/topics/6999) +- [Using Go's authorization library Casbin with Gin and GORM (in Japanese)](https://www.zaneli.com/blog/20181203) + +### Echo + +- [Web authorization with Casbin](http://klotzandrew.com/blog/authorization-with-casbin) + +### Iris + +- [Iris + Casbin: Practice for permission management (in Chinese)](https://zxc0328.github.io/2018/05/14/casbin-iris/) +- [Role-based access control for HTTP based on Casbin (in Chinese)](https://studyiris.com/example/exper/casbin.html) +- [Learning iris + Casbin from scratch](https://learnku.com/articles/41416) + +### VMware Harbor + +- [Casbin: Golang access control framework (in Chinese)](http://www.growingdev.com/articles/2020/01/12/1578838858526.html) +- [Access control in Harbor (in Chinese)](http://www.growingdev.com/articles/2020/01/10/1578670203670.html) + +### Argo CD + +- [Organizational RBAC in Argo CD with Casbin](https://argoproj.github.io/argo-cd/operator-manual/rbac/) + +### GShark + +- [GShark: Scan for sensitive information in Github easily and effectively (in Chinese)](https://mp.weixin.qq.com/s?__biz=MzI3MjA3MTY3Mw==&mid=2247483770&idx=1&sn=9f02c2803e1c946e8c23b16ff3eba757&chksm=eb396fecdc4ee6fa2f378e846f354f45acf6e6f540cfd54190e9353df47c7707e3a2aadf714f&token=115330850&lang=zh_CN#rd) + + + +### SprintBoot + +- [jCasbin: a more light-weight permission management solution (in Chinese)](https://blog.csdn.net/waynelee0809/article/details/85702551) +- [Integrating jCasbin with JFinal (in Chinese)](http://www.jfinal.com/share/842) + + + +### Express + +- [How to Add Role-Based-Access-Control to Your Serverless HTTP API on AWS](https://dev.to/matttyler/how-to-add-role-based-access-control-to-your-serverless-http-api-on-aws-17bk) + +### Nest + +- [How to Create Role based Authorization Middleware with Casbin and Nest.js](https://dev.to/dwipr/how-to-create-role-based-authorization-middleware-with-casbin-and-nest-js-52gm) +- [nest.js: Casbin RESTful RBAC authorization middleware (Video)](https://www.youtube.com/watch?v=mWlPNrCgVdE) +- [A Demo App of Attribute-based Access Control in Node.js Based on Casbin](https://github.com/Jarvie8176/casbin-example) +- [Multi tenant SaaS starter kit with cqrs graphql microservice architecture](https://github.com/juicycleff/ultimate-backend) + +### Fastify + +- [Access Control in Node.js with Fastify and Casbin](https://www.nearform.com/blog/access-control-node-js-fastify-and-casbin/) + + + +- [Casbin, Powerful and Efficient ACL for Your Projects](http://phpmagazine.net/2018/11/casbin-powerful-and-efficient-acl-for-your-projects.html) + +### Laravel + +- [Laravel authorization: authorization library supporting ACL, RBAC, ABAC and other models](https://developpaper.com/laravel-authorization-authorization-library-supporting-acl-rbac-abac-and-other-models/) + + + +- [Basic Role-Based HTTP Authorization in Rust with Casbin](https://www.zupzup.org/rust-casbin-example/) + + diff --git a/website/translated_docs/fr-FR/Watchers.md b/website/translated_docs/fr-FR/Watchers.md new file mode 100644 index 00000000..c3ad271e --- /dev/null +++ b/website/translated_docs/fr-FR/Watchers.md @@ -0,0 +1,49 @@ +--- +id: watchers +title: Watchers +--- + +We support to use distributed messaging systems like [etcd](https://github.com/coreos/etcd) to keep consistence between multiple Casbin enforcer instances. So our users can concurrently use multiple Casbin enforcers to handle large number of permission checking requests. + +Similar to policy storage adapters, we don't put watcher code in the main library. Any support for a new messaging system should be implemented as a watcher. A complete list of Casbin watchers is provided as below. Any 3rd-party contribution on a new watcher is welcomed, please inform us and I will put it in this list:) + + + + +| Watcher | Type | Author | Description | +| ------------------------------------------------------------------------------------------------------------------ | ---------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| [Etcd Watcher](https://github.com/casbin/etcd-watcher) | KV store | Casbin | Watcher for [etcd](https://github.com/coreos/etcd) | +| [NATS Watcher](https://github.com/Soluto/casbin-nats-watcher) | Messaging system | [Soluto](https://github.com/Soluto) | Watcher for [NATS](https://nats.io/) | +| [ZooKeeper Watcher](https://github.com/grepsr/casbin-zk-watcher) | KV store | [Grepsr](https://github.com/grepsr) | Watcher for [Apache ZooKeeper](https://zookeeper.apache.org/) | +| [Redis Watcher](https://github.com/billcobbler/casbin-redis-watcher) | KV store | [@billcobbler](https://github.com/billcobbler) | Watcher for [Redis](http://redis.io/) | +| [NATS, RabbitMQ, GCP Pub/Sub, AWS SNS & SQS, Kafka, InMemory](https://github.com/rusenask/casbin-go-cloud-watcher) | Messaging System | [rusenask](https://github.com/rusenask/) | Watcher based on [Go Cloud Dev Kit](https://gocloud.dev/) that works with leading cloud providers and self-hosted infrastructure | + + +| Watcher | Type | Author | Description | +| ---------------------------------------------------------- | -------- | ------------------------------------------ | -------------------------------------------------- | +| [Etcd Adapter](https://github.com/mapleafgo/jcasbin-extra) | KV store | [@mapleafgo](https://github.com/mapleafgo) | Watcher for [etcd](https://github.com/coreos/etcd) | + + +| Watcher | Type | Author | Description | +| ----------------------------------------------------------------- | ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------ | +| [Etcd Watcher](https://github.com/node-casbin/etcd-watcher) | KV store | Casbin | Watcher for [etcd](https://github.com/coreos/etcd) | +| [Redis Watcher](https://github.com/node-casbin/redis-watcher) | KV store | Casbin | Watcher for [Redis](http://redis.io/) | +| [Pub/Sub Watcher](https://github.com/node-casbin/pubsub-watcher) | Messaging system | Casbin | Watcher for [Google Cloud Pub/Sub](https://cloud.google.com/pubsub/docs) | +| [Postgres Watcher](https://github.com/mcollina/casbin-pg-watcher) | Database | [Matteo Collina](https://github.com/mcollina/) | Watcher for [PostgreSQL](https://www.postgresql.org/) | + + +| Watcher | Type | Author | Description | +| --------------------------------------------------------------------------- | -------- | ----------------------------------------------- | ----------------------------------------------------- | +| [Redis Watcher](https://github.com/ScienceLogic/flask-casbin-redis-watcher) | KV store | [ScienceLogic](https://github.com/ScienceLogic) | Watcher for [Redis](http://redis.io/) | +| [PostgreSQL Watcher](https://github.com/pycasbin/postgresql-watcher) | Database | Casbin | Watcher for [PostgreSQL](https://www.postgresql.org/) | + + +| Watcher | Type | Author | Description | +| ----------------------------------------------------------------- | -------- | -------------------------------- | ------------------------------------- | +| [Redis Watcher](https://github.com/Sbou/Casbin.NET-Redis-Watcher) | KV store | [@Sbou](https://github.com/Sbou) | Watcher for [Redis](http://redis.io/) | + + + +## WatcherEx + +In order to support incremental synchronization between multiple instances, we provide the `WatcherEx` interface. We hope it can notify other instances when the policy changes, but there is currently no implementation of `WatcherEx`. We recommend that you use dispatcher to achieve this. diff --git a/website/translated_docs/fr-FR/WebpageController.md b/website/translated_docs/fr-FR/WebpageController.md new file mode 100644 index 00000000..1bc184c3 --- /dev/null +++ b/website/translated_docs/fr-FR/WebpageController.md @@ -0,0 +1,133 @@ +--- +id: frontend +title: Frontend Usage +--- + +[Casbin.js](https://github.com/casbin/casbin.js) is a Casbin addon that facilites your access-control management in the frontend application. + + +## Installation + +``` +npm install casbin.js +``` +or +``` +yarn add casbin.js +``` + +## Quick Start +You can use `manual` mode in your frontend application, and set the permission whenever you wish: +```Javascript +const casbinjs = require("casbin.js"); + +// Set the user's permission: +// He/She can read `data1` and `data2` objects and can write `data1` object +const permission = { + "read": ["data1", "data2"], + "write": ["data1"] +} + +// Run casbin.js in manual mode, which requires you to set the permission manually. +const authorizer = new casbinjs.Authorizer("manual"); + +authorizer.setPermission(permission); +console.log(authorizer.can("read", "data1")); // True +console.log(authorizer.cannot("write", "data2")); // True +``` + +You can refer to our [React example](https://github.com/casbin-js/examples) to see a practical usage of Casbin.js + + + + + + + +## Advanced Usage + +Casbin.js provides a perfect solution to integrating your frontend access-control management with your backend Casbin service. + + +Use `auto` mode and specify your endpoint when initializing the Casbin.js `Authorizer`, it will automatically sync the permission and manipulate the frontend status. + +```Javascript +const casbinjs = require('casbin.js'); + +// Set your backend casbin service url +const authorizer = new casbinjs.Authorizer( + 'auto', // mode + {endpoint: 'http://your_endpoint/api/casbin'} +); + +// Set your visitor. +// Casbin.js will automatically sync the permission with your backend Casbin service. +authorizer.setUser("Tom"); + +// Evaluate the permission +if authorizer.can("read", "data1") { + // Some frontend procedure ... +} +``` + +Correspondingly, you need to expose an interface (e.g. a RestAPI) to generate the permission object and pass it to the frontend. In your API controller, call `CasbinJsGetUserPermission` to construct the permission object. Here is an example in Beego: + +```Go +// Router +beego.Router("api/casbin", &controllers.APIController{}, "GET:GetFrontendPermission") + +// Controller +func (c *APIController) GetFrontendPermission() { + // Get the visitor from the GET parameters. (The key is "casbin_subject") + visitor := c.Input().Get("casbin_subject") + // `e` is an initialized instance of Casbin Enforcer + c.Data["perm"] = casbin.CasbinJsGetPermissionForUser(e, visitor) + // Pass the data to the fronend. + c.ServeJSON() +} +``` + +:::note Currently, `CasbinJsGetPermissionForUser` api is only supported in Go Casbin and Node-Casbin. If you want this api to be supported in other languages, please [raise an issue](https://github.com/casbin/casbin.js/issues) or leave a comment below. ::: + + +## API List + +#### `setPermission(permission: string)` +Set the permission object. Always used in `manual` mode. + +#### `setUser(user: string)` +Set the visitor identity and update the permission. Always used in `auto` mode. + +#### `can(action: string, object: string)` +Check if the user can perform `action` on `object`. + +#### `cannot(action: string, object: string)` +Check if the user **cannot** perform `action` on `object`. + +#### `canAll(action: string, objects: Array)` +Check if the user can perform `action` on **all** object in `objects`. + +#### `canAny(action: string, objects: Array)` +Check if the user can perform `action` on **any one** of the `objects`. + + +## Why Casbin.js + +People may wonder the difference between Node-Casbin and Casbin.js. In a word, Node-Casbin is the core of Casbin implemented in NodeJS environment, and it's normally used as an access-controlling management toolkit at the server ends. Casbin.js is an frontend library that help you use Casbin to authorize your webpage user at the client side. + +Normally, it is not proper to directly build up a Casbin service and do the authorization/enforcement tasks at a web frontend application due to the following problems: +1. When someone turn on the client, the enforcer will be initialized, and it will pull all the policies from the backend persistent layers. A high concurrency could bring tough pressure on the databases and cost a lot of network throughput.  +2. Loading all policies to the client sides could bring secure risks. +3. Difficult for the seperation between client and server as well as the agile development. + +We wish a tool that eases the process of using Casbin at the frontend. Actually, the core of Casbin.js is the manipulation of current user's permission at the client side. As you mentioned, Casbin.js does a fetch from a specified endpoint. This procedure will sync the permission of the user with the backend Casbin service. After having the permission data, developers can use Casbin.js interfaces to manage the behaviors of the user at the frontend side. + +Casbin.js avoid the two problems that mentioned above: Casbin service will no longer be pulled up repeatedly, and the size of passing messages between the client and the server are reduced. We also avoid to store all the policies at the frontend. User can only accessible to his own permission, but have no idea about anything about things like the access-control model and other users' permissions. Besides, Casbin.js can also efficiently decouple the client and the server in authorization management. diff --git a/website/translated_docs/uk-UA/ABAC.md b/website/translated_docs/uk-UA/ABAC.md new file mode 100644 index 00000000..03a53a11 --- /dev/null +++ b/website/translated_docs/uk-UA/ABAC.md @@ -0,0 +1,75 @@ +--- +id: abac +title: ABAC +--- + +## What is the ABAC model actually? + +ABAC is `Attribute-Based Access Control`, meaning you can use the attributes (properties) of the subject, object or action instead of themselves (the string) to control the access. You may already hear of a complicated ABAC access control language named XACML. Compared to XACML, Casbin's ABAC is very simple: in ABAC, you can use structs (or class instances based on the programming language) instead of string for model elements. + +Use the official ABAC example for example: + +```ini +[request_definition] +r = sub, obj, act + +[policy_definition] +p = sub, obj, act + +[policy_effect] +e = some(where (p.eft == allow)) + +[matchers] +m = r.sub == r.obj.Owner +``` + +We use `r.obj.Owner` instead of `r.obj` in the matcher. The `r.obj` passed in the `Enforce()` function will be a struct or class instance instead of string. Casbin will use reflection to retrieve the `obj` member variable in that struct or class for you. + +Here is a definition for the `r.obj` struct or class: + +```go +type testResource struct { + Name string + Owner string +} +``` + +## How to use ABAC? + +Simply speaking, to use ABAC, you need to do two things: + +1. Specify the attributes in the model matcher. +2. Pass in the struct or class instance for the element as the argument in Casbin's `Enforce()` function. + +:::warning Currently, only request elements like `r.sub`, `r.obj`, `r.act` and so on support ABAC. You cannot use it on policy elements like `p.sub`, because there is no way to define a struct or class in Casbin's policy. ::: + +:::tip You can use multiple ABAC attributes in a matcher, for example: `m = r.sub.Domain == r.obj.Domain`. ::: + +## Scaling the model for complex and large number of ABAC rules. + +The above instance of ABAC implementation is at its core very simple, but oftentimes the authorization system needs a very complex and large number of ABAC rules. To fit this necessity the above implementation will increase the verbosity of the model to a large extent. So, it’s wise to add the rules in the policy instead of in the model. This is done by introducing a `eval()` functional construct. Below is the example instance to manage such ABAC models. + +This is the definition of the `CONF` file used for defining the ABAC model. + +```ini +[request_definition] +r = sub, obj, act + +[policy_definition] +p = sub_rule, obj, act + +[policy_effect] +e = some(where (p.eft == allow)) + +[matchers] +m = eval(p.sub_rule) && r.obj == p.obj && r.act == p.act +``` + +Here, `p.sub_rule` is of type struct or class(user-defined type) which consists of necessary attributes to be used in the policy. + +This is the policy that is used against the model for `Enforcement`. Now, you can use the object instance which is passed to `eval()` as a parameter to define certain ABAC constraints. + +``` +p, r.sub.Age > 18, /data1, read +p, r.sub.Age < 60, /data2, write +``` \ No newline at end of file diff --git a/website/translated_docs/uk-UA/Adapters.md b/website/translated_docs/uk-UA/Adapters.md new file mode 100644 index 00000000..6f2bc35b --- /dev/null +++ b/website/translated_docs/uk-UA/Adapters.md @@ -0,0 +1,321 @@ +--- +id: adapters +title: Adapters +--- + +In Casbin, the policy storage is implemented as an adapter (aka middleware for Casbin). A Casbin user can use an adapter to load policy rules from a storage (aka `LoadPolicy()`), or save policy rules to it (aka `SavePolicy()`). To keep light-weight, we don't put adapter code in the main library. + +## Supported adapters + +A complete list of Casbin adapters is provided as below. Any 3rd-party contribution on a new adapter is welcomed, please inform us and we will put it in this list:) + + + + +| Adapter | Type | Author | AutoSave | Description | +| ------------------------------------------------------------------------------------ | -------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [Filtered File Adapter (built-in)](https://casbin.org/docs/en/policy-subset-loading) | File | [@faceless-saint](https://github.com/faceless-saint) | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files with policy subset loading support | +| [SQL Adapter](https://github.com/Blank-Xu/sql-adapter) | SQL | [@Blank-Xu](https://github.com/Blank-Xu) | ✅ | MySQL, PostgreSQL, SQL Server, SQLite3 are supported in `master` branch and Oracle is supported in `oracle` branch by `database/sql` | +| [Xorm Adapter](https://github.com/casbin/xorm-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, TiDB, SQLite, SQL Server, Oracle are supported by [Xorm](https://github.com/go-xorm/xorm/) | +| [Gorm Adapter](https://github.com/casbin/gorm-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, Sqlite3, SQL Server are supported by [Gorm](https://github.com/jinzhu/gorm/) | +| [Beego ORM Adapter](https://github.com/casbin/beego-orm-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, Sqlite3 are supported by [Beego ORM](https://beego.me/docs/mvc/model/overview.md) | +| [SQLX Adapter](https://github.com/memwey/casbin-sqlx-adapter) | ORM | [@memwey](https://github.com/memwey) | ✅ | MySQL, PostgreSQL, SQLite, Oracle are supported by [SQLX](https://github.com/jmoiron/sqlx) | +| [Sqlx Adapter](https://github.com/Blank-Xu/sqlx-adapter) | SQL | [@Blank-Xu](https://github.com/Blank-Xu) | ✅ | MySQL, PostgreSQL, SQL Server, SQLite3 are supported in `master` branch and Oracle is supported in `oracle` branch by [sqlx](https://github.com/jmoiron/sqlx) | +| [GF ORM Adapter](https://github.com/vance-liu/gdb-adapter) | ORM | [@vance-liu](https://github.com/vance-liu) | ✅ | MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by [GoFrame ORM](https://goframe.org/pages/viewpage.action?pageId=1114686) | +| [GoFrame ORM Adapter](https://github.com/kotlin2018/adapter) | ORM | [@kotlin2018](https://github.com/kotlin2018) | ✅ | MySQL, SQLite, PostgreSQL, Oracle, SQL Server are supported by [GoFrame ORM](https://goframe.org/pages/viewpage.action?pageId=1114686) | +| [Filtered PostgreSQL Adapter](https://github.com/casbin/casbin-pg-adapter) | SQL | Casbin | ✅ | For [PostgreSQL](https://www.postgresql.org/) | +| [PostgreSQL Adapter](https://github.com/cychiuae/casbin-pg-adapter) | SQL | [@cychiuae](https://github.com/cychiuae) | ✅ | For [PostgreSQL](https://www.postgresql.org/) | +| [PostgreSQL Adapter (Archived)](https://github.com/going/casbin-postgres-adapter) | SQL | [Going](https://github.com/going) | ❌ | For [PostgreSQL](https://www.postgresql.org/) | +| [RQLite Adapter](https://github.com/edomosystems/rqlite-adapter) | SQL | [EDOMO Systems](https://github.com/edomosystems) | ✅ | For [RQLite](https://github.com/rqlite/rqlite/) | +| [MongoDB Adapter](https://github.com/casbin/mongodb-adapter) | NoSQL | Casbin | ✅ | For [MongoDB](https://www.mongodb.com) based on [MongoDB driver for Go](https://github.com/globalsign/mgo) | +| [RethinkDB Adapter](https://github.com/adityapandey9/rethinkdb-adapter) | NoSQL | [@adityapandey9](https://github.com/adityapandey9) | ✅ | For [RethinkDB](https://rethinkdb.com/) | +| [Cassandra Adapter](https://github.com/casbin/cassandra-adapter) | NoSQL | Casbin | ❌ | For [Apache Cassandra DB](http://cassandra.apache.org) | +| [DynamoDB Adapter](https://github.com/HOOQTV/dynacasbin) | NoSQL | [HOOQ](https://github.com/HOOQTV) | ❌ | For [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) | +| [Dynacasbin](https://github.com/NewbMiao/dynacasbin) | NoSQL | [NewbMiao](https://github.com/NewbMiao) | ✅ | For [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) | +| [ArangoDB Adapter](https://github.com/adamwasila/arangodb-adapter) | NoSQL | [@adamwasila](https://github.com/adamwasila) | ✅ | For [ArangoDB](https://www.arangodb.com/) | +| [Amazon S3 Adapter](https://github.com/Soluto/casbin-minio-adapter) | Cloud | [Soluto](https://github.com/Soluto) | ❌ | For [Minio](https://github.com/minio/minio) and [Amazon S3](https://aws.amazon.com/s3/) | +| [Azure Cosmos DB Adapter](https://github.com/spacycoder/cosmos-casbin-adapter) | Cloud | [@spacycoder](https://github.com/spacycoder) | ✅ | For [Microsoft Azure Cosmos DB](https://docs.microsoft.com/en-us/azure/cosmos-db/introduction) | +| [GCP Firestore Adapter](https://github.com/reedom/casbin-firestore-adapter) | Cloud | [@reedom](https://github.com/reedom) | ❌ | For [Google Cloud Platform Firestore](https://cloud.google.com/firestore/) | +| [Consul Adapter](https://github.com/ankitm123/consul-adapter) | KV store | [@ankitm123](https://github.com/ankitm123) | ❌ | For [HashiCorp Consul](https://www.consul.io/) | +| [Redis Adapter](https://github.com/casbin/redis-adapter) | KV store | Casbin | ❌ | For [Redis](https://redis.io/) | +| [Etcd Adapter](https://github.com/sebastianliu/etcd-adapter) | KV store | [@sebastianliu](https://github.com/sebastianliu) | ❌ | For [etcd](https://github.com/coreos/etcd) | +| [BoltDB Adapter](https://github.com/speza/casbin-bolt-adapter) | KV store | [@speza](https://github.com/speza) | ✅ | For [Bolt](https://github.com/boltdb/bolt) | +| [Bolt Adapter](https://github.com/wirepair/bolt-adapter) | KV store | [@wirepair](https://github.com/wirepair) | ❌ | For [Bolt](https://github.com/boltdb/bolt) | +| [BadgerDB Adapter](https://github.com/inits/casbin-badgerdb-adapter) | KV store | [@inits](https://github.com/inits) | ✅ | For [BadgerDB](https://github.com/dgraph-io/badger) | +| [Protobuf Adapter](https://github.com/casbin/protobuf-adapter) | Stream | Casbin | ❌ | For [Google Protocol Buffers](https://developers.google.com/protocol-buffers/) | +| [JSON Adapter](https://github.com/casbin/json-adapter) | String | Casbin | ❌ | For [JSON](https://www.json.org/) | +| [String Adapter](https://github.com/qiangmzsx/string-adapter) | String | [@qiangmzsx](https://github.com/qiangmzsx) | ❌ | For String | +| [HTTP File Adapter](https://github.com/h4ckedneko/casbin-httpfs) | HTTP | [@h4ckedneko](https://github.com/h4ckedneko) | ❌ | For [http.FileSystem](https://golang.org/src/net/http/fs.go) | + + +| Adapter | Type | Author | AutoSave | Description | +| ------------------------------------------------------------------------------------ | ----- | ------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [JDBC Adapter](https://github.com/jcasbin/jdbc-adapter) | JDBC | Casbin | ✅ | MySQL, Oracle, PostgreSQL, DB2, Sybase, SQL Server are supported by [JDBC](https://docs.oracle.com/cd/E19226-01/820-7688/gawms/index.html) | +| [Hibernate Adapter](https://github.com/jcasbin/hibernate-adapter) | ORM | Casbin | ✅ | Oracle, DB2, SQL Server, Sybase, MySQL, PostgreSQL are supported by [Hibernate](http://www.hibernate.org/) | +| [MyBatis Adapter](https://github.com/jcasbin/mybatis-adapter) | ORM | Casbin | ✅ | MySQL, Oracle, PostgreSQL, DB2, Sybase, SQL Server (the same as JDBC) are supported by [MyBatis 3](https://mybatis.org/mybatis-3/) | +| [Hutool Adapter](https://github.com/mapleafgo/jcasbin-extra) | ORM | [@mapleafgo](https://github.com/mapleafgo) | ✅ | MySQL, Oracle, PostgreSQL, SQLite are supported by [Hutool](https://github.com/looly/hutool) | +| [DynamoDB Adapter](https://github.com/jcasbin/dynamodb-adapter) | NoSQL | Casbin | ❌ | For [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) | + + +| Adapter | Type | Author | AutoSave | Description | +| ----------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [Filtered File Adapter (built-in)](https://casbin.org/docs/en/policy-subset-loading) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files with policy subset loading support | +| [String Adapter (built-in)](https://github.com/casbin/node-casbin/blob/master/src/persist/stringAdapter.ts) | String | [@calebfaruki](https://github.com/calebfaruki) | ❌ | For String | +| [Basic Adapter](https://github.com/node-casbin/basic-adapter) | Native ORM | Casbin | ✅ | pg, mysql, mysql2, sqlite3, oracledb, mssql are supported by the adapter itself | +| [Sequelize Adapter](https://github.com/node-casbin/sequelize-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, SQLite, Microsoft SQL Server are supported by [Sequelize](https://github.com/sequelize/sequelize) | +| [TypeORM Adapter](https://github.com/node-casbin/typeorm-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, MariaDB, SQLite, MS SQL Server, Oracle, WebSQL, MongoDB are supported by [TypeORM](https://github.com/typeorm/typeorm) | +| [Mongoose Adapter](https://github.com/node-casbin/mongoose-adapter) | ORM | [elastic.io](https://github.com/elasticio) and Casbin | ✅ | MongoDB is supported by [Mongoose](https://mongoosejs.com/) | +| [Knex Adapter](https://github.com/knex/casbin-knex-adapter) | ORM | [@sarneeh](https://github.com/sarneeh) and [knex](https://github.com/knex) | ✅ | MSSQL, MySQL, PostgreSQL, SQLite3, Oracle are supported by [Knex.js](https://knexjs.org/) | +| [Objection.js Adapter](https://github.com/willsoto/casbin-objection-adapter) | ORM | [@willsoto](https://github.com/willsoto) | ✅ | MSSQL, MySQL, PostgreSQL, SQLite3, Oracle are supported by [Objection.js](https://vincit.github.io/objection.js/) | +| [Node MongoDB Native Adapter](https://github.com/juicycleff/casbin-mongodb-adapter) | NoSQL | [@juicycleff](https://github.com/juicycleff) | ✅ | For [Node MongoDB Native](https://mongodb.github.io/node-mongodb-native/) | +| [DynamoDB Adapter](https://github.com/fospitia/casbin-dynamodb-adapter) | NoSQL | [@fospitia](https://github.com/fospitia) | ✅ | For [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) | +| [Node PostgreSQL Native Adapter](https://github.com/touchifyapp/casbin-pg-adapter) | SQL | [@touchifyapp](https://github.com/touchifyapp) | ✅ | PostgreSQL adapter with advanced policy subset loading support and improved performances built with [node-postgres](https://node-postgres.com/). | +| [Couchbase Adapter](https://github.com/MarkMYoung/casbin-couchbase-adapter) | NoSQL | [@MarkMYoung](https://github.com/MarkMYoung) | ✅ | For [Couchbase](https://www.couchbase.com/) | +| [Redis Adapter](https://github.com/NandaKishorJeripothula/node-casbin-redis-adapter) | KV store | [@NandaKishorJeripothula](https://github.com/NandaKishorJeripothula) | ❌ | For [Redis](https://redis.io/) | + + +| Adapter | Type | Author | AutoSave | Description | +| ------------------------------------------------------------------------------------ | -------- | ------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [Database Adapter](https://github.com/php-casbin/database-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, SQLite, Microsoft SQL Server are supported by [techone/database](https://github.com/techoner/database) | +| [Zend Db Adapter](https://github.com/php-casbin/zend-db-adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, SQLite, Oracle, IBM DB2, Microsoft SQL Server, Other PDO Driver are supported by [zend-db](https://docs.zendframework.com/zend-db/) | +| [Doctrine DBAL Adapter(Recommend)](https://github.com/php-casbin/dbal-adapter) | ORM | Casbin | ✅ | Powerful PHP database abstraction layer ([DBAL](https://github.com/doctrine/dbal)) with many features for database schema introspection and management. | +| [Medoo Adapter](https://github.com/php-casbin/medoo-adapter) | ORM | Casbin | ✅ | [Medoo](https://github.com/catfan/Medoo) is a lightweight PHP Database Framework to Accelerate Development, supports all SQL databases, including `MySQL`, `MSSQL`, `SQLite`, `MariaDB`, `PostgreSQL`, `Sybase`, `Oracle` and more. | +| [Redis Adapter](https://github.com/nsnake/CasbinAdapter-Redis-Adapter) | KV store | [@nsnake](https://github.com/nsnake) | ❌ | For [Redis](https://redis.io/) | + + +| Adapter | Type | Author | AutoSave | Description | +| ------------------------------------------------------------------------------------ | ----- | ------------------------------------------------------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [SQLAlchemy Adapter](https://github.com/pycasbin/sqlalchemy-adapter) | ORM | Casbin | ✅ | PostgreSQL, MySQL, SQLite, Oracle, Microsoft SQL Server, Firebird, Sybase are supported by [SQLAlchemy](https://www.sqlalchemy.org/) | +| [Async Databases Adapter](https://github.com/pycasbin/databases-adapter) | ORM | Casbin | ✅ | PostgreSQL, MySQL, SQLite, Oracle, Microsoft SQL Server, Firebird, Sybase are supported by [Databases](https://www.encode.io/databases/) | +| [Peewee Adapter](https://github.com/shblhy/peewee-adapter) | ORM | [@shblhy](https://github.com/shblhy) | ✅ | PostgreSQL, MySQL, SQLite are supported by [Peewee](http://docs.peewee-orm.com/) | +| [MongoEngine Adapter](https://github.com/zhangbailong945/mongoengine_adapter) | ORM | [@zhangbailong945](https://github.com/zhangbailong945) | ❌ | MongoDB is supported by [MongoEngine](http://mongoengine.org/) | +| [Couchbase Adapter](https://github.com/ScienceLogic/casbin-couchbase-adapter) | NoSQL | [ScienceLogic](https://github.com/ScienceLogic) | ✅ (without `remove_filtered_policy()`) | For [Couchbase](https://www.couchbase.com/) | +| [DynamoDB Adapter](https://github.com/abqadeer/python-dycasbin) | NoSQL | [@abqadeer](https://github.com/abqadeer/) | ✅ | For [DynamoDB](https://aws.amazon.com/dynamodb/) | +| [Pymongo Adapter](https://github.com/pycasbin/pymongo-adapter) | ORM | Casbin | ❌ | MongoDB is supported by [Pymongo](https://pypi.org/project/pymongo/) | + + +| Adapter | Type | Author | AutoSave | Description | +| ------------------------------------------------------------------------------------ | ---- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [EF Adapter](https://github.com/casbin-net/EF-Adapter) | ORM | Casbin | ❌ | MySQL, PostgreSQL, SQLite, Microsoft SQL Server, Oracle, DB2, etc. are supported by [Entity Framework 6](https://docs.microsoft.com/en-us/ef/ef6/) | +| [EFCore Adapter](https://github.com/casbin-net/EFCore-Adapter) | ORM | Casbin | ✅ | MySQL, PostgreSQL, SQLite, Microsoft SQL Server, Oracle, DB2, etc. are supported by [Entity Framework Core](https://docs.microsoft.com/en-us/ef/core/) | + + +| Adapter | Type | Author | AutoSave | Description | +| ------------------------------------------------------------------------------------ | ------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [File Adapter (built-in)](https://casbin.org/docs/en/adapters#file-adapter-built-in) | File | Casbin | ❌ | For [.CSV (Comma-Separated Values)](https://en.wikipedia.org/wiki/Comma-separated_values) files | +| [Diesel Adapter](https://github.com/casbin-rs/diesel-adapter) | ORM | Casbin | ✅ | [SQLite, PostgreSQL, MySQL](https://github.com/diesel-rs/diesel/blob/master/guide_drafts/backend_installation.md) are supported by [Diesel](http://diesel.rs/) | +| [Sqlx Adapter](https://github.com/casbin-rs/sqlx-adapter) | ORM | Casbin | ✅ | PostgreSQL, MySQL are supported by [Sqlx](https://github.com/launchbadge/sqlx) with fully asynchronous operation | +| [YAML Adapter](https://github.com/casbin-rs/yaml-adapter) | String | Casbin | ✅ | For [YAML](https://yaml.org/) | + + + +:::note +1. If `casbin.NewEnforcer()` is called with an explicit or implicit adapter, the policy will be loaded automatically. +2. You can call `e.LoadPolicy()` to reload the policy rules from the storage. +3. If the adapter does not support the `Auto-Save` feature, The policy rules cannot be automatically saved back to the storage when you add or remove policies. You have to call `SavePolicy()` manually to save all policy rules. ::: + +## Examples + +Here we provide several examples: + +### File adapter (built-in) + +Below shows how to initialize an enforcer from the built-in file adapter: + + + + +```go +import "github.com/casbin/casbin" + +e := casbin.NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv") +``````php +use Casbin\Enforcer; + +$e = new Enforcer('examples/basic_model.conf', 'examples/basic_policy.csv'); +``````rust +use casbin::prelude::*; + +let mut e = Enforcer::new("examples/basic_model.conf", "examples/basic_policy.csv").await?; +```This is the same with:```go +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) +``````php +use Casbin\Enforcer; +use Casbin\Persist\Adapters\FileAdapter; + +$a = new FileAdapter('examples/basic_policy.csv'); +$e = new Enforcer('examples/basic_model.conf', $a); +``````rust +use casbin::prelude::*; + +let a = FileAdapter::new("examples/basic_policy.csv"); +let e = Enforcer::new("examples/basic_model.conf", a).await?; +```### [MySQL adapter](https://github.com/casbin/mysql-adapter) + +Below shows how to initialize an enforcer from MySQL database. it connects to a MySQL DB on 127.0.0.1:3306 with root and blank password.```go +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) +``````rust +// https://github.com/casbin-rs/diesel-adapter +// make sure you activate feature `mysql` + +use casbin::prelude::*; +use diesel_adapter::{ConnOptions, DieselAdapter}; + +let mut conn_opts = ConnOptions::default(); +conn_opts + .set_hostname("127.0.0.1") + .set_port(3306) + .set_host("127.0.0.1:3306") // overwrite hostname, port config + .set_database("casbin") + .set_auth("casbin_rs", "casbin_rs"); + +let a = DieselAdapter::new(conn_opts)?; +let mut e = Enforcer::new("examples/basic_model.conf", a).await?; +``````php +// https://github.com/php-casbin/dbal-adapter + +use Casbin\Enforcer; +use CasbinAdapter\DBAL\Adapter as DatabaseAdapter; + +$config = [ + // Either 'driver' with one of the following values: + // pdo_mysql,pdo_sqlite,pdo_pgsql,pdo_oci (unstable),pdo_sqlsrv,pdo_sqlsrv, + // mysqli,sqlanywhere,sqlsrv,ibm_db2 (unstable),drizzle_pdo_mysql + 'driver' => 'pdo_mysql', + 'host' => '127.0.0.1', + 'dbname' => 'test', + 'user' => 'root', + 'password' => '', + 'port' => '3306', +]; + +$a = DatabaseAdapter::newAdapter($config); +$e = new Enforcer('examples/basic_model.conf', $a); +```## Use your own storage adapter + +You can use your own adapter like below: + +```go +import ( + "github.com/casbin/casbin" + "github.com/your-username/your-repo" +) + +a := yourpackage.NewAdapter(params) +e := casbin.NewEnforcer("examples/basic_model.conf", a) +``` + +## Load/Save at run-time + +You may also want to reload the model, reload the policy or save the policy after initialization: + +```go +// 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 + +There is a feature called `Auto-Save` for adapters. When an adapter supports `Auto-Save`, it means it can support adding a single policy rule to the storage, or removing a single policy rule from the storage. This is unlike `SavePolicy()`, because the latter will delete all policy rules in the storage and save all policy rules from Casbin enforcer to the storage. So it may suffer performance issue when the number of policy rules is large. + +When the adapter supports `Auto-Save`, you can switch this option via `Enforcer.EnableAutoSave()` function. The option is enabled by default (if the adapter supports it). + +:::note +1. The `Auto-Save` feature is optional. An adapter can choose to implement it or not. +2. `Auto-Save` only works for a Casbin enforcer when the adapter the enforcer uses supports it. +3. See the `AutoSave` column in the above adapter list to see if `Auto-Save` is supported by an adapter. ::: + +Here's an example about how to use `Auto-Save`: + +```go +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(...) +``` + +For more examples, please see: https://github.com/casbin/xorm-adapter/blob/master/adapter_test.go + +### How to write an adapter + +All adapters should implement the [Adapter](https://github.com/casbin/casbin/blob/master/persist/adapter.go) interface by providing at least two mandatory methods:`LoadPolicy(model model.Model) error` and `SavePolicy(model model.Model) error`. + +The other three functions are optional. They should be implemented if the adapter supports the `Auto-Save` feature. + +| Method | Type | Description | +| ---------------------- | --------- | ---------------------------------------------------------- | +| LoadPolicy() | mandatory | Load all policy rules from the storage | +| SavePolicy() | mandatory | Save all policy rules to the storage | +| AddPolicy() | optional | Add a policy rule to the storage | +| RemovePolicy() | optional | Remove a policy rule from the storage | +| RemoveFilteredPolicy() | optional | Remove policy rules that match the filter from the storage | + +:::note If an adapter doesn't support `Auto-Save`, it should provide an empty implementation for the three optional functions. Here's an example for Golang: ::: + +```go +// 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 will ignore the `not implemented` error when calling these three optional functions. + +### Who is responsible to create the DB? + +As a convention, the adapter should be able to automatically create a database named `casbin` if it doesn't exist and use it for policy storage. Please use the Xorm adapter as a reference implementation: https://github.com/casbin/xorm-adapter diff --git a/website/translated_docs/uk-UA/AdminPortal.md b/website/translated_docs/uk-UA/AdminPortal.md new file mode 100644 index 00000000..b9f07f39 --- /dev/null +++ b/website/translated_docs/uk-UA/AdminPortal.md @@ -0,0 +1,41 @@ +--- +id: admin-portal +title: Admin Portal +--- + +We provide a [web-based portal called Casdoor](https://github.com/casbin/casdoor) for model management and policy management: + +![model editor](https://hsluoyz.github.io/casbin/ui_model_editor.png) + +![policy editor](https://hsluoyz.github.io/casbin/ui_policy_editor.png) + +There are also 3rd-party admin portal projects that use Casbin as authorization engine. You can get started to build your own Casbin service based on these projects. + + + + +| Project | Author | Frontend | Backend | Description | +| ---------------------------------------------------------- | -------------------------------------------- | ------------------ | ------- | ---------------------------------------------------------------- | +| [Casdoor](https://github.com/casbin/casdoor) | Casbin | React + Ant Design | Beego | Based on Beego + XORM + React | +| [gin-vue-admin](https://github.com/piexlmax/gin-vue-admin) | [@piexlmax](https://github.com/piexlmax) | Vue + Element UI | Gin | Based on Gin + GORM + Vue | +| [gin-admin](https://github.com/LyricTian/gin-admin) | [@LyricTian](https://github.com/LyricTian) | React + Ant Design | Gin | RBAC scaffolding based on Gin + GORM + Casbin + Ant Design React | +| [go-admin](https://github.com/hequan2017/go-admin) | [@hequan2017](https://github.com/hequan2017) | None | Gin | Go RESTful API gateway based on Gin + GORM + JWT + RBAC (Casbin) | +| [zeus-admin](https://github.com/bullteam/zeus-admin) | [bullteam](https://github.com/bullteam) | Vue + Element UI | Gin | Unified Permission management platform based on JWT + Casbin | +| [IrisAdminApi](https://github.com/snowlyg/IrisAdminApi) | [@snowlyg](https://github.com/snowlyg) | Vue + Element UI | Iris | Backend API based on Iris + Casbin | + + +| Project | Author | Frontend | Backend | Description | +| ---------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------- | ------- | ------------------------------------------------------------------------------------------------- | +| [Casbin-Role-Mgt-Dashboard-RBAC](https://github.com/alikhan866/Casbin-Role-Mgt-Dashboard-RBAC) | [@alikhan866](https://github.com/alikhan866) | React + Material UI | Express | Beginner friendly RBAC management with Enforcer integration to check enforcement result on the go | + + +| Project | Author | Frontend | Backend | Description | +| ---------------------------------------------------------------------------- | ------ | --------- | ------- | --------------------- | +| [openstack-policy-editor](https://github.com/casbin/openstack-policy-editor) | Casbin | Bootstrap | Django | The Web UI for Casbin | + + +| Project | Author | Frontend | Backend | Description | +| -------------------------------------------- | ---------------------------------------- | -------- | -------- | ------------------------------------------------------ | +| [Tadmin](https://github.com/techoner/tadmin) | [@techoner](https://github.com/techoner) | AmazeUI | ThinkPHP | Non-intrusive backend framework based on ThinkPHP 5.1+ | + + diff --git a/website/translated_docs/uk-UA/Adopters.md b/website/translated_docs/uk-UA/Adopters.md new file mode 100644 index 00000000..675ce8bb --- /dev/null +++ b/website/translated_docs/uk-UA/Adopters.md @@ -0,0 +1,50 @@ +--- +id: adopters +title: Our Adopters +--- + +## Direct integration + + + + +| Name | Description | Model | Policy | +| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| [VMware Harbor](https://github.com/goharbor/harbor) | VMware's open source trusted cloud native registry project that stores, signs, and scans content. | [Code](https://github.com/goharbor/harbor/blob/master/src/pkg/permission/evaluator/rbac/casbin.go#L24-L44) | [Beego ORM](https://github.com/goharbor/harbor/blob/master/src/replication/dao/policy.go#L24-L26) | +| [Intel RMD](https://github.com/intel/rmd) | Intel's resource management daemon. | [.conf](https://github.com/intel/rmd/blob/master/etc/rmd/acl/url/model.conf) | [.csv](https://github.com/intel/rmd/blob/master/etc/rmd/acl/url/policy.csv) | +| [VMware Dispatch](https://github.com/vmware/dispatch) | A framework for deploying and managing serverless style applications. | [Code](https://github.com/vmware/dispatch/blob/master/pkg/identity-manager/handlers.go#L46-L55) | [Code](https://github.com/vmware/dispatch/blob/master/pkg/identity-manager/handlers_test.go#L35-L45) | +| [Skydive](https://github.com/skydive-project/skydive) | An open source real-time network topology and protocols analyzer. | [Code](https://github.com/skydive-project/skydive/blob/master/config/config.go#L136-L140) | [.csv](https://github.com/skydive-project/skydive/blob/master/rbac/policy.csv) | +| [Zenpress](https://github.com/insionng/zenpress) | A CMS system written in Golang. | [.conf](https://github.com/insionng/zenpress/blob/master/content/config/rbac_model.conf) | [Gorm](https://github.com/insionng/zenpress/blob/master/model/user.go#L53-L77) | +| [Argo CD](https://github.com/argoproj/argo-cd) | GitOps continuous delivery for Kubernetes. | [.conf](https://github.com/argoproj/argo-cd/blob/master/util/rbac/model.conf) | [.csv](https://github.com/argoproj/argo-cd/blob/master/util/rbac/builtin-policy.csv) | +| [Muxi Cloud](https://github.com/muxiyun/Mae) | PaaS of Muxi Cloud, an easier way to manage Kubernetes cluster. | [.conf](https://github.com/muxiyun/Mae/blob/master/conf/casbinmodel.conf) | [Code](https://github.com/muxiyun/Mae/blob/master/pkg/casbin/initPolicy.go#L21-L95) | +| [EngineerCMS](https://github.com/3xxx/EngineerCMS) | A CMS to manage knowledge for engineers. | [.conf](https://github.com/3xxx/EngineerCMS/blob/master/conf/rbac_model.conf) | [SQLite](https://github.com/3xxx/EngineerCMS/blob/master/database/engineer.db) | +| [Cyber Auth API](https://github.com/CyberlifeCN/cyber-auth-api) | A Golang authentication API project. | [.conf](https://github.com/CyberlifeCN/cyber-auth-api/blob/master/conf/authz_model.conf) | [.csv](https://github.com/CyberlifeCN/cyber-auth-api/blob/master/conf/authz_policy.csv) | +| [IRIS Community](https://github.com/irisnet/iris-community) | Website for IRIS Community Activities. | [.conf](https://github.com/irisnet/iris-community/blob/master/authz/authz_model.conf) | [.csv](https://github.com/irisnet/iris-community/blob/master/authz/authz_policy.csv) | +| [Metadata DB](https://github.com/Bnei-Baruch/mdb) | BB archive metadata database. | [.conf](https://github.com/Bnei-Baruch/mdb/blob/master/data/permissions_model.conf) | [.csv](https://github.com/Bnei-Baruch/mdb/blob/master/data/permissions_policy.csv) | +| [Qilin API](https://github.com/ProtocolONE/qilin.api) | ProtocolONE's licenses managemen tool for game content. | [Code](https://github.com/ProtocolONE/rbac/blob/master/model.go) | [.csv](https://github.com/ProtocolONE/rbac/tree/master/conf) | +| [Devtron Labs](https://github.com/devtron-labs/devtron) | Software Delivery Workflow For Kubernetes. | [.conf](https://github.com/devtron-labs/devtron/blob/main/auth_model.conf) | [Xorm](https://github.com/devtron-labs/devtron/blob/main/internal/casbin/Adapter.go) | + + +| Name | Description | Model | Policy | +| ---------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | +| [lighty.io](https://github.com/PantheonTechnologies/lighty-core) | OpenDaylight's solution for SDN controller. | [README](https://github.com/PantheonTechnologies/lighty-core/blob/6f2ceaae6a68e08c96d14d2fa8ee060ad9f61606/lighty-examples/lighty-controller-springboot-netconf/README.md#security) | N/A | + + +| Name | Description | Model | Policy | +| ------------------------------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| [Notadd](https://github.com/notadd/notadd) | A micro-service development architecture based on Nest.js. | [.conf](https://github.com/notadd/notadd/blob/e58d0a0cf5d691c3fe20170e94cdd8e2c627abd4/apps/nest-upms/src/casbin/rbac_model.conf) | [DB adapter](https://github.com/notadd/notadd/blob/e58d0a0cf5d691c3fe20170e94cdd8e2c627abd4/apps/nest-upms/src/casbin/adapter.ts) | + + +| Name | Description | Model | Policy | +| --------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------- | ------ | +| [dtrace](https://github.com/EduScaled/dtrace) | EduScaled's tracing system. | [Commit](https://github.com/EduScaled/dtrace/commit/6e8d6b52ec2fa120e8ad63f84a4aecc3eae14c02) | N/A | + + + + +## Integration via plugin + +| Name | Description | Plugin | Model | Policy | +| ----------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| [Docker](https://github.com/docker/docker) | The world's leading software container platform | [casbin-authz-plugin](https://github.com/casbin/casbin-authz-plugin) ([recommended by Docker](https://docs.docker.com/engine/extend/legacy_plugins/#authorization-plugins)) | [.conf](https://github.com/casbin/casbin-authz-plugin/blob/master/examples/basic_model.conf) | [.csv](https://github.com/casbin/casbin-authz-plugin/blob/master/examples/basic_policy.csv) | +| [Gobis](https://github.com/orange-cloudfoundry/gobis) | [Orange](https://github.com/orange-cloudfoundry)'s lightweight API Gateway written in go | [casbin](https://github.com/orange-cloudfoundry/gobis-middlewares/tree/master/casbin) | [Code](https://github.com/orange-cloudfoundry/gobis-middlewares/blob/master/casbin/model.go#L52-L65) | [Request](https://github.com/orange-cloudfoundry/gobis-middlewares/blob/master/casbin/adapter.go#L46-L64) | diff --git a/website/translated_docs/uk-UA/Benchmark.md b/website/translated_docs/uk-UA/Benchmark.md new file mode 100644 index 00000000..565c4174 --- /dev/null +++ b/website/translated_docs/uk-UA/Benchmark.md @@ -0,0 +1,26 @@ +--- +id: benchmark +title: Benchmarks +--- + +The overhead of policy enforcement is benchmarked in [model_b_test.go](https://github.com/casbin/casbin/blob/master/model_b_test.go). The testbed is: + +``` +Intel(R) Core(TM) i7-6700HQ CPU @ 2.60GHz, 2601 Mhz, 4 Core(s), 8 Logical Processor(s) +``` + +The benchmarking result of `go test -bench=. -benchmem` is as follows (op = an `Enforce()` call, ms = millisecond, KB = kilo bytes): + +| Test case | Rule size | Time overhead (ms/op) | Memory overhead (KB) | +| ------------------------- | ---------------------------------------- | --------------------- | -------------------- | +| ACL | 2 rules (2 users) | 0.015493 | 5.649 | +| RBAC | 5 rules (2 users, 1 role) | 0.021738 | 7.522 | +| RBAC (small) | 1100 rules (1000 users, 100 roles) | 0.164309 | 80.620 | +| RBAC (medium) | 11000 rules (10000 users, 1000 roles) | 2.258262 | 765.152 | +| RBAC (large) | 110000 rules (100000 users, 10000 roles) | 23.916776 | 7,606 | +| RBAC with resource roles | 6 rules (2 users, 2 roles) | 0.021146 | 7.906 | +| RBAC with domains/tenants | 6 rules (2 users, 1 role, 2 domains) | 0.032696 | 10.755 | +| ABAC | 0 rule (0 user) | 0.007510 | 2.328 | +| RESTful | 5 rules (3 users) | 0.045398 | 91.774 | +| Deny-override | 6 rules (2 users, 1 role) | 0.023281 | 8.370 | +| Priority | 9 rules (2 users, 2 roles) | 0.016389 | 5.313 | diff --git a/website/translated_docs/uk-UA/Dispatchers.md b/website/translated_docs/uk-UA/Dispatchers.md new file mode 100644 index 00000000..27c9c5b0 --- /dev/null +++ b/website/translated_docs/uk-UA/Dispatchers.md @@ -0,0 +1,23 @@ +--- +id: dispatchers +title: Dispatchers +--- + +Dispatcher provide a way to synchronize incremental changes of policy. It should be based on consistency algorithms such as raft to ensure the consistency of all enforcer instances. Through dispatcher users can easily establish distributed clusters. + +The dispatcher's method is divided into two parts. The first is the method combined with casbin. These methods should be called inside casbin. Users can use the more complete api provided by casbin itself. + +The other part is the method defined by the dispatcher itself, including the dispatcher initialization method, and different functions provided by different algorithms, such as dynamic membership, config changes etc. + +:::note we hope dispatcher just ensure the consistency of Casbin enforcer at runtime. So if the policy is inconsistent when initialization, the dispatcher will not work properly. Users need to ensure that the state of all instances is consistent before using dispatcher. ::: + +A complete list of Casbin dispatchers is provided as below. Any 3rd-party contribution on a new dispatcher is welcomed, please inform us and we will put it in this list:) + + + +| Dispatcher | Type | Author | Description | +| ------------------------------------------------------------- | ---- | ------ | -------------------------------------------------------------------- | +| [Etcd Raft Dispatcher](https://github.com/casbin/casbin-raft) | raft | Casbin | Dispatcher based on [etcd/raft](https://github.com/coreos/etcd/raft) | + + + diff --git a/website/translated_docs/uk-UA/Function.md b/website/translated_docs/uk-UA/Function.md new file mode 100644 index 00000000..f28c7937 --- /dev/null +++ b/website/translated_docs/uk-UA/Function.md @@ -0,0 +1,73 @@ +--- +id: function +title: Function +--- + +## Functions in matchers + +You can even specify functions in a matcher to make it more powerful. You can use the built-in functions or specify your own function. All built-in functions take such a format(except `keyGet` and `keyGet2`): + +```C +bool function_name(string arg1, string arg2) +``` + +It returns whether `arg1` matches `arg2`. + +`keyGet` and `keyGet2` will return the string which matching the wildcard, and return `""` if nothing was matched. + +The supported built-in functions are: + +| Function | arg1 | arg2 | Example | +| ---------- | ------------------------------------------ | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| keyMatch | a URL path like `/alice_data/resource1` | a URL path or a `*` pattern like `/alice_data/*` | [keymatch_model.conf](https://github.com/casbin/casbin/blob/master/examples/keymatch_model.conf)/[keymatch_policy.csv](https://github.com/casbin/casbin/blob/master/examples/keymatch_policy.csv) | +| keyGet | a URL path like `/alice_data/resource1` | a URL path or a `*` pattern like `/alice_data/*` | [keyget_model.conf](https://github.com/casbin/casbin/blob/master/examples/keyget_model.conf)/[keymatch_policy.csv](https://github.com/casbin/casbin/blob/master/examples/keymatch_policy.csv) | +| keyMatch2 | a URL path like `/alice_data/resource1` | a URL path or a `:` pattern like `/alice_data/:resource` | [keymatch2_model.conf](https://github.com/casbin/casbin/blob/master/examples/keymatch2_model.conf)/[keymatch2_policy.csv](https://github.com/casbin/casbin/blob/master/examples/keymatch2_policy.csv) | +| keyGet2 | a URL path like `/alice_data/resource1` | a URL path or `:` pattern like `/alice_data/:resource` | [keyget2_model.conf](https://github.com/casbin/casbin/blob/master/examples/keyget2_model.conf)/[keymatch2_policy.csv](https://github.com/casbin/casbin/blob/master/examples/keymatch2_policy.csv) | +| keyMatch3 | a URL path like `/alice_data/resource1` | a URL path or a `{}` pattern like `/alice_data/{resource}` | | +| keyMatch4 | a URL path like `/alice_data/123/book/123` | a URL path or a `{}` pattern like `/alice_data/{id}/book/{id}` | | +| regexMatch | any string | a regular expression pattern | [keymatch_model.conf](https://github.com/casbin/casbin/blob/master/examples/keymatch_model.conf)/[keymatch_policy.csv](https://github.com/casbin/casbin/blob/master/examples/keymatch_policy.csv) | +| ipMatch | an IP address like `192.168.2.123` | an IP address or a CIDR like `192.168.2.0/24` | [ipmatch_model.conf](https://github.com/casbin/casbin/blob/master/examples/ipmatch_model.conf)/[ipmatch_policy.csv](https://github.com/casbin/casbin/blob/master/examples/ipmatch_policy.csv) | + +See details for above functions at: https://github.com/casbin/casbin/blob/master/util/builtin_operators_test.go + +## How to add a customized function + +First prepare your function. It takes several parameters and return a bool: + +```go +func KeyMatch(key1 string, key2 string) bool { + i := strings.Index(key2, "*") + if i == -1 { + return key1 == key2 + } + + if len(key1) > i { + return key1[:i] == key2[:i] + } + return key1 == key2[:i] +} +``` + +Then wrap it with `interface{}` types: + +```go +func KeyMatchFunc(args ...interface{}) (interface{}, error) { + name1 := args[0].(string) + name2 := args[1].(string) + + return (bool)(KeyMatch(name1, name2)), nil +} +``` + +At last, register the function to the Casbin enforcer: + +```go +e.AddFunction("my_func", KeyMatchFunc) +``` + +Now, you can use the function in your model CONF like this: + +```ini +[matchers] +m = r.sub == p.sub && my_func(r.obj, p.obj) && r.act == p.act +``` diff --git a/website/translated_docs/uk-UA/GetStarted.md b/website/translated_docs/uk-UA/GetStarted.md new file mode 100644 index 00000000..921c6334 --- /dev/null +++ b/website/translated_docs/uk-UA/GetStarted.md @@ -0,0 +1,365 @@ +--- +id: get-started +title: Get Started +--- + +## Installation + + + + +``` +go get github.com/casbin/casbin/v2 +``` + + +For Maven: + +``` + + org.casbin + jcasbin + 1.6.0 + +``` + + +``` +# NPM +npm install casbin --save + +# Yarn +yarn add casbin +``` + + +Require this package in the `composer.json` of your project. This will download the package: + +``` +composer require casbin/casbin +``` + + +``` +pip install casbin +``` + + +``` +dotnet add package Casbin.NET +``` + + +``` +cargo install cargo-edit +cargo add casbin + +// If you use async-std as async executor +cargo add async-std + +// If you use tokio as async executor +cargo add tokio // make sure you activate its `macros` feature +``` + + +Casbin4D comes in a package (currently for Delphi 10.3 Rio) and you can install it in the IDE. However, there are no visual components which means that you can use the units independently of packages. Just import the units in your project (assuming you do not mind the number of them). + + + +## New a Casbin enforcer + +The new a Casbin enforcer must provide a [Model](supported-models) and a [Adapter](adapters). + +Casbin has a [FileAdapter](adapters#file-adapter-built-in), see [Adapter](adapters) from more Adapter. + +- Use the Model file and default [FileAdapter](adapters#file-adapter-built-in): + + + + +```go +import "github.com/casbin/casbin/v2" + +e, err := casbin.NewEnforcer("path/to/model.conf", "path/to/policy.csv") +``` + + +```java +import org.casbin.jcasbin.main.Enforcer; + +Enforcer e = new Enforcer("path/to/model.conf", "path/to/policy.csv"); +``` + + +```js +import { newEnforcer } from 'casbin'; + +const e = await newEnforcer('path/to/model.conf', 'path/to/policy.csv'); +``` + + +```php +require_once './vendor/autoload.php'; + +use Casbin\Enforcer; + +$e = new Enforcer("path/to/model.conf", "path/to/policy.csv"); +``` + + +```python +import casbin + +e = casbin.Enforcer("path/to/model.conf", "path/to/policy.csv") +``` + + +```csharp +using NetCasbin; + +var e = new Enforcer("path/to/model.conf", "path/to/policy.csv"); +``` + + +```delphi +var + casbin: ICasbin; +begin + casbin := TCasbin.Create('path/to/model.conf', 'path/to/policy.csv'); + ... +end +``` + + +```rust +use casbin::prelude::*; + +// If you use async_td as async executor +#[cfg(feature = "runtime-async-std")] +#[async_std::main] +async fn main() -> Result<()> { + let mut e = Enforcer::new("path/to/model.conf", "path/to/policy.csv").await?; + Ok(()) +} + +// If you use tokio as async executor +#[cfg(feature = "runtime-tokio")] +#[tokio::main] +async fn main() -> Result<()> { + let mut e = Enforcer::new("path/to/model.conf", "path/to/policy.csv").await?; + Ok(()) +} +``` + + +- Use the Model text with other Adapter: + + + + +```go +import ( + "log" + + "github.com/casbin/casbin/v2" + "github.com/casbin/casbin/v2/model" + xormadapter "github.com/casbin/xorm-adapter/v2" + _ "github.com/go-sql-driver/mysql" +) + +// Initialize a Xorm adapter with MySQL database. +a, err := xormadapter.NewAdapter("mysql", "mysql_username:mysql_password@tcp(127.0.0.1:3306)/casbin") +if err != nil { + log.Fatalf("error: adapter: %s", err) +} + +m, err := model.NewModelFromString(` +[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 +`) +if err != nil { + log.Fatalf("error: model: %s", err) +} + +e, err := casbin.NewEnforcer(m, a) +if err != nil { + log.Fatalf("error: enforcer: %s", err) +} +``` + + +### Check permissions + +Add an enforcement hook into your code right before the access happens: + + + + +```go +sub := "alice" // the user that wants to access a resource. +obj := "data1" // the resource that is going to be accessed. +act := "read" // the operation that the user performs on the resource. + +ok, err := e.Enforce(sub, obj, act) + +if err != nil { + // handle err +} + +if ok == true { + // permit alice to read data1 +} else { + // deny the request, show an error +} + +// You could use BatchEnforce() to enforce some requests in batches. +// This method returns a bool slice, and this slice's index corresponds to the row index of the two-dimensional array. +// e.g. results[0] is the result of {"alice", "data1", "read"} +results, err := e.BatchEnforce([][]interface{}{{"alice", "data1", "read"}, {"bob", "data2", "write"}, {"jack", "data3", "read"}}) +``` + + +```java +String sub = "alice"; // the user that wants to access a resource. +String obj = "data1"; // the resource that is going to be accessed. +String act = "read"; // the operation that the user performs on the resource. + +if (e.enforce(sub, obj, act) == true) { + // permit alice to read data1 +} else { + // deny the request, show an error +} +``` + + +```js +const sub = 'alice'; // the user that wants to access a resource. +const obj = 'data1'; // the resource that is going to be accessed. +const act = 'read'; // the operation that the user performs on the resource. + +if ((await e.enforce(sub, obj, act)) === true) { + // permit alice to read data1 +} else { + // deny the request, show an error +} +``` + + +```php +$sub = "alice"; // the user that wants to access a resource. +$obj = "data1"; // the resource that is going to be accessed. +$act = "read"; // the operation that the user performs on the resource. + +if ($e->enforce($sub, $obj, $act) === true) { + // permit alice to read data1 +} else { + // deny the request, show an error +} +``` + + +```python +sub = "alice" # the user that wants to access a resource. +obj = "data1" # the resource that is going to be accessed. +act = "read" # the operation that the user performs on the resource. + +if e.enforce(sub, obj, act): + # permit alice to read data1 + pass +else: + # deny the request, show an error + pass +``` + + +```csharp +var sub = "alice"; # the user that wants to access a resource. +var obj = "data1"; # the resource that is going to be accessed. +var act = "read"; # the operation that the user performs on the resource. + +if (await e.EnforceAsync(sub, obj, act)) +{ + // permit alice to read data1 +} +else +{ + // deny the request, show an error +} +``` + + +```delphi +if casbin.enforce(['alice,data1,read']) then + // Alice is super happy as she can read data1 +else + // Alice is sad +``` + + +```rust + let sub = "alice"; // the user that wants to access a resource. + let obj = "data1"; // the resource that is going to be accessed. + let act = "read"; // the operation that the user performs on the resource. + + if e.enforce((sub, obj, act)).await? { + // permit alice to read data1 + } else { + // error occurs + } +``` + + + +Casbin also provides API for permission management at run-time. For example, You can get all the roles assigned to a user as below: + + + + +```go +roles := e.GetRolesForUser("alice") +``` + + +```java +Roles roles = e.getRolesForUser("alice"); +``` + + +```js +const roles = await e.getRolesForUser('alice'); +``` + + +```php +$roles = $e->getRolesForUser("alice"); +``` + + +```python +roles = e.get_roles_for_user("alice") +``` + + +```csharp +var roles = e.GetRolesForUser("alice"); +``` + + +```delphi +``` + + +```rust +let roles = e.get_roles_for_user("alice"); +```See [Management API](/docs/en/management-api) and [RBAC API](/docs/en/rbac-api) for more usage. + +Please refer to the test cases for more usage. diff --git a/website/translated_docs/uk-UA/HowItWorks.md b/website/translated_docs/uk-UA/HowItWorks.md new file mode 100644 index 00000000..a7eeadc7 --- /dev/null +++ b/website/translated_docs/uk-UA/HowItWorks.md @@ -0,0 +1,61 @@ +--- +id: how-it-works +title: How it Works +--- + +In Casbin, an access control model is abstracted into a CONF file based on the **PERM metamodel (Policy, Effect, Request, Matchers)**. So switching or upgrading the authorization mechanism for a project is just as simple as modifying a configuration. You can customize your own access control model by combining the available models. For example, you can get RBAC roles and ABAC attributes together inside one model and share one set of policy rules. + +The most basic and simplest model in Casbin is ACL. ACL's model CONF is: + +```ini +# Request definition +[request_definition] +r = sub, obj, act + +# Policy definition +[policy_definition] +p = sub, obj, act + +# Policy effect +[policy_effect] +e = some(where (p.eft == allow)) + +# Matchers +[matchers] +m = r.sub == p.sub && r.obj == p.obj && r.act == p.act + +``` + +An example policy for ACL model is like: + +``` +p, alice, data1, read +p, bob, data2, write +``` + +It means: + +- alice can read data1 +- bob can write data2 + +We also support multi-line mode by appending '\\' in the end: + +```ini +# Matchers +[matchers] +m = r.sub == p.sub && r.obj == p.obj \ + && r.act == p.act +``` + +Further more, if you are using ABAC, you can try operator `in` like following in Casbin **golang** edition (jCasbin and Node-Casbin are not supported yet): + +```ini +# Matchers +[matchers] +m = r.obj == p.obj && r.act == p.act || r.obj in ('data2', 'data3') +``` + +But you **SHOULD** make sure that the length of the array is **MORE** than **1**, otherwise there will cause it to panic. + +For more operators, you may take a look at [govaluate](https://github.com/Knetic/govaluate) + diff --git a/website/translated_docs/uk-UA/LogError.md b/website/translated_docs/uk-UA/LogError.md new file mode 100644 index 00000000..de720a67 --- /dev/null +++ b/website/translated_docs/uk-UA/LogError.md @@ -0,0 +1,188 @@ +--- +id: log-error +title: Log & Error Handling +--- + +## Logging + +Casbin uses the built-in `log` to print logs to console by default like: + +```log +2017/07/15 19:43:56 [Request: alice, data1, read ---> true] +``` + +The logging is not enabled by default. You can toggle it via `Enforcer.EnableLog()` or the last parameter of `NewEnforcer()`. + +:::note +We already support logging the model, enforce request, role, policy in Golang. You can define your own log for logging Casbin. If you are using Python, pycasbin leverages the default Python logging mechanism. The pycasbin package makes a call to logging.getLogger() to set the logger. No special logging configuration is needed other than initializing the logger in the parent application. If no logging is intitilized within the parent application you will not see any log messages from pycasbin. ::: + +### Use different logger for different enforcer + +Every enforcer could have its own logger to log info, and it could be changed at run-time. + +And you could use a proper logger via the last paramter of `NewEnforcer()`, if you using this way to initialize your enforcer, you needn't use the enabled parameter, cause the priority of the enabled field in logger is higher. + +```go +// Set a default logger as enforcer e1's logger. +// This operation could also be seen as changing the logger of e1 at run-time. +e1.SetLogger(&Log.DefaultLogger{}) + +// Set another logger as enforcer e2's logger. +e2.SetLogger(&YouOwnLogger) + +// Set your logger when initialize enforcer e3. +e3, _ := casbin.NewEnforcer("examples/rbac_model.conf", a, logger) +``` + +#### Supported loggers + +We provide some loggers to help you log information.| Logger | Author | Description | +| ------------------------------------------------------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------- | +| [Defatule logger (built-in)](https://github.com/casbin/casbin/blob/master/log/default_logger.go) | Casbin | The default logger using golang log. | +| [Zap logger](https://github.com/casbin/zap-logger) | Casbin | Using [zap](https://github.com/uber-go/zap), provide json encoded log and you could customize more with your own zap-logger. |#### How to write a logger + +Your logger should implement the [Logger](https://github.com/casbin/casbin/blob/master/log/logger.go#L20) interface. + +| Method | Type | Description | +| ------------ | --------- | ----------------------------------------- | +| EnableLog() | mandatory | Control whether print the message. | +| IsEnabled() | mandatory | Show the current logger's enabled status. | +| LogModel() | mandatory | Log info related to model. | +| LogEnforce() | mandatory | Log info related to enforce. | +| LogRole() | mandatory | Log info related to role. | +| LogPolicy() | mandatory | Log info related to policy. | + + +You can pass your custom `logger` to `Enforcer.SetLogger()`. + +Here is an example about how to customize a logger for Golang: + +```go +import ( + "fmt" + "log" + "strings" +) + +// DefaultLogger is the implementation for a Logger using golang log. +type DefaultLogger struct { + enabled bool +} + +func (l *DefaultLogger) EnableLog(enable bool) { + l.enabled = enable +} + +func (l *DefaultLogger) IsEnabled() bool { + return l.enabled +} + +func (l *DefaultLogger) LogModel(model [][]string) { + if !l.enabled { + return + } + var str strings.Builder + str.WriteString("Model: ") + for _, v := range model { + str.WriteString(fmt.Sprintf("%v\n", v)) + } + + log.Println(str.String()) +} + +func (l *DefaultLogger) LogEnforce(matcher string, request []interface{}, result bool, explains [][]string) { + if !l.enabled { + return + } + + var reqStr strings.Builder + reqStr.WriteString("Request: ") + for i, rval := range request { + if i != len(request)-1 { + reqStr.WriteString(fmt.Sprintf("%v, ", rval)) + } else { + reqStr.WriteString(fmt.Sprintf("%v", rval)) + } + } + reqStr.WriteString(fmt.Sprintf(" ---> %t\n", result)) + + reqStr.WriteString("Hit Policy: ") + for i, pval := range explains { + if i != len(explains)-1 { + reqStr.WriteString(fmt.Sprintf("%v, ", pval)) + } else { + reqStr.WriteString(fmt.Sprintf("%v \n", pval)) + } + } + + log.Println(reqStr.String()) +} + +func (l *DefaultLogger) LogPolicy(policy map[string][][]string) { + if !l.enabled { + return + } + + var str strings.Builder + str.WriteString("Policy: ") + for k, v := range policy { + str.WriteString(fmt.Sprintf("%s : %v\n", k, v)) + } + + log.Println(str.String()) +} + +func (l *DefaultLogger) LogRole(roles []string) { + if !l.enabled { + return + } + + log.Println("Roles: ", roles) +} + +``` + +## Error handling + +Error or panic may happen when you use Casbin for reasons like: + +1. Invalid syntax in model file (.conf). +2. Invalid syntax in policy file (.csv). +3. Custom error from storage adapters, e.g., MySQL fails to connect. +4. Casbin's bug. + +There are five main functions you may need to care about for error or panic: + +| Function | Behavior on error | +| ------------------------------------------------------------------------------ | ----------------- | +| [NewEnforcer()](https://godoc.org/github.com/casbin/casbin#NewEnforcer) | Return error | +| [LoadModel()](https://godoc.org/github.com/casbin/casbin#Enforcer.LoadModel) | Return error | +| [LoadPolicy()](https://godoc.org/github.com/casbin/casbin#Enforcer.LoadPolicy) | Return error | +| [SavePolicy()](https://godoc.org/github.com/casbin/casbin#Enforcer.SavePolicy) | Return error | +| [Enforce()](https://godoc.org/github.com/casbin/casbin#Enforcer.Enforce) | Return error | + +:::note `NewEnforcer()` calls `LoadModel()` and `LoadPolicy()` inside. So you don't have to call the latter two calls when using `NewEnforcer()`. ::: + +## Enable & disable + +The enforcer can be disabled via the `Enforcer.EnableEnforce()` function. When it's disabled, `Enforcer.Enforce()` will always return `true`. Other operations like adding or removing policy is not affected. Here's an example: + +```go +e := casbin.NewEnforcer("examples/basic_model.conf", "examples/basic_policy.csv") + +// Will return false. +// By default, the enforcer is enabled. +e.Enforce("non-authorized-user", "data1", "read") + +// Disable the enforcer at run-time. +e.EnableEnforce(false) + +// Will return true for any request. +e.Enforce("non-authorized-user", "data1", "read") + +// Enable the enforcer again. +e.EnableEnforce(true) + +// Will return false. +e.Enforce("non-authorized-user", "data1", "read") +``` diff --git a/website/translated_docs/uk-UA/ManagementAPI.md b/website/translated_docs/uk-UA/ManagementAPI.md new file mode 100644 index 00000000..fd5de5a0 --- /dev/null +++ b/website/translated_docs/uk-UA/ManagementAPI.md @@ -0,0 +1,1655 @@ +--- +id: management-api +title: Management API +--- + +The primitive API that provides full support for Casbin policy management. + +## Reference + +global variable `e` is Enforcer instance. + + + + +```go +e, err := NewEnforcer("examples/rbac_model.conf", "examples/rbac_policy.csv") +``` + + +```typescript +const e = await newEnforcer('examples/rbac_model.conf', 'examples/rbac_policy.csv') +``` + + +```php +$e = new Enforcer('examples/rbac_model.conf', 'examples/rbac_policy.csv'); +``` + + +```csharp +var e = new Enforcer("path/to/model.conf", "path/to/policy.csv"); +``` + + +```rust +let mut e = Enforce::new("examples/rbac_model.conf", "examples/rbac_policy.csv").await?; +``` + + + +### `GetAllSubjects()` + +GetAllSubjects gets the list of subjects that show up in the current policy. + +For example: + + + + +```go +allSubjects := e.GetAllSubjects() +``` + + +```typescript +const allSubjects = await e.getAllSubjects() +``` + + +```php +$allSubjects = $e->getAllSubjects(); +``` + + +```csharp +var allSubjects = e.GetAllSubjects(); +``` + + +```rust +let all_subjects = e.get_all_subjects(); +``` + + + +### `GetAllNamedSubjects()` + +GetAllNamedSubjects gets the list of subjects that show up in the current named policy. + +For example: + + + + +```go +allNamedSubjects := e.GetAllNamedSubjects("p") +``` + + +```typescript +const allNamedSubjects = await e.getAllNamedSubjects('p') +``` + + +```php +$allNamedSubjects = $e->getAllNamedSubjects("p"); +``` + + +```csharp +var allNamedSubjects = e.GetAllNamedSubjects("p"); +``` + + +```rust +let all_named_subjects = e.get_all_named_subjects("p"); +``` + + + +### `GetAllObjects()` + +GetAllObjects gets the list of objects that show up in the current policy. + +For example: + + + + +```go +allObjects := e.GetAllObjects() +``` + + +```typescript +const allObjects = await e.getAllObjects() +``` + + +```php +$allObjects = $e->getAllObjects(); +``` + + +```csharp +var allObjects = e.GetAllObjects(); +``` + + +```rust +let all_objects = e.get_all_objects(); +``` + + + +### `GetAllNamedObjects()` + +GetAllNamedObjects gets the list of objects that show up in the current named policy. + +For example: + + + + +```go +allNamedObjects := e.GetAllNamedObjects("p") +``` + + +```typescript +const allNamedObjects = await e.getAllNamedObjects('p') +``` + + +```php +$allNamedObjects = $e->getAllNamedObjects("p"); +``` + + +```csharp +var allNamedObjects = e.GetAllNamedObjects("p"); +``` + + +```rust +let all_named_objects = e.get_all_named_objects("p"); +``` + + + +### `GetAllActions()` + +GetAllActions gets the list of actions that show up in the current policy. + +For example: + + + + +```go +allActions := e.GetAllActions() +``` + + +```typescript +const allActions = await e.getAllActions() +``` + + +```php +$allActions = $e->getAllActions(); +``` + + +```csharp +var allActions = e.GetAllActions(); +``` + + +```rust +let all_actions = e.get_all_actions(); +``` + + + +### `GetAllNamedActions()` + +GetAllNamedActions gets the list of actions that show up in the current named policy. + +For example: + + + + +```go +allNamedActions := e.GetAllNamedActions("p") +``` + + +```typescript +const allNamedActions = await e.getAllNamedActions('p') +``` + + +```php +$allNamedActions = $e->getAllNamedActions("p"); +``` + + +```csharp +var allNamedActions = e.GetAllNamedActions("p"); +``` + + +```rust +let all_named_actions = e.get_all_named_actions("p"); +``` + + + +### `GetAllRoles()` + +GetAllRoles gets the list of roles that show up in the current policy. + +For example: + + + + +``` +allRoles = e.GetAllRoles() +``` + + +```typescript +const allRoles = await e.getAllRoles() +``` + + +```php +$allRoles = $e->getAllRoles(); +``` + + +```csharp +var allRoles = e.GetAllRoles(); +``` + + +```rust +let all_roles = e.get_all_roles(); +``` + + + +### `GetAllNamedRoles()` + +GetAllNamedRoles gets the list of roles that show up in the current named policy. + +For example: + + + + +```go +allNamedRoles := e.GetAllNamedRoles("g") +``` + + +```typescript +const allNamedRoles = await e.getAllNamedRoles('g') +``` + + +```php +$allNamedRoles = $e->getAllNamedRoles('g'); +``` + + +```csharp +var allNamedRoles = e.GetAllNamedRoles("g"); +``` + + +```rust +let all_named_roles = e.get_all_named_roles("g"); +``` + + + +### `GetPolicy()` + +GetPolicy gets all the authorization rules in the policy. + +For example: + + + + +```go +policy = e.GetPolicy() +``` + + +```typescript +const policy = await e.getPolicy() +``` + + +```php +$policy = $e->getPolicy(); +``` + + +```csharp +var policy = e.GetPolicy(); +``` + + +```rust +let policy = e.get_policy(); +``` + + + + +### `GetFilteredPolicy()` + +GetFilteredPolicy gets all the authorization rules in the policy, field filters can be specified. + +For example: + + + + +```go +filteredPolicy := e.GetFilteredPolicy(0, "alice") +``` + + +```typescript +const filteredPolicy = await e.getFilteredPolicy(0, 'alice') +``` + + +```php +$filteredPolicy = $e->getFilteredPolicy(0, "alice"); +``` + + +```csharp +var filteredPolicy = e.GetFilteredPolicy(0, "alice"); +``` + + +```rust +let filtered_policy = e.get_filtered_policy(0, vec!["alice".to_owned()]); +``` + + + +### `GetNamedPolicy()` + +GetNamedPolicy gets all the authorization rules in the named policy. + +For example: + + + + +```go +namedPolicy := e.GetNamedPolicy("p") +``` + + +```typescript +const namedPolicy = await e.getNamedPolicy('p') +``` + + +```php +$namedPolicy = $e->getNamedPolicy("p"); +``` + + +```csharp +var namedPolicy = e.GetNamedPolicy("p"); +``` + + +```rust +let named_policy = e.get_named_policy("p"); +``` + + + + +### `GetFilteredNamedPolicy()` + +GetFilteredNamedPolicy gets all the authorization rules in the named policy, field filters can be specified. + +For example: + + + + +```go +filteredNamedPolicy = e.GetFilteredNamedPolicy("p", 0, "bob") +``` + + +```typescript +const filteredNamedPolicy = await e.getFilteredNamedPolicy('p', 0, 'bob') +``` + + +```php +$filteredNamedPolicy = $e->getFilteredNamedPolicy("p", 0, "bob"); +``` + + +```csharp +var filteredNamedPolicy = e.GetFilteredNamedPolicy("p", 0, "alice"); +``` + + +```rust +let filtered_named_policy = e.get_filtered_named_policy("p", 0, vec!["bob".to_owned()]); +``` + + + +### `GetGroupingPolicy()` + +GetGroupingPolicy gets all the role inheritance rules in the policy. + +For example: + + + + +```go +groupingPolicy := e.GetGroupingPolicy() +``` + + +```typescript +const groupingPolicy = await e.getGroupingPolicy() +``` + + +```php +$groupingPolicy = $e->getGroupingPolicy(); +``` + + +```csharp +var groupingPolicy = e.GetGroupingPolicy(); +``` + + +```rust +let grouping_policy = e.get_grouping_policy(); +``` + + + +### `GetFilteredGroupingPolicy()` + +GetFilteredGroupingPolicy gets all the role inheritance rules in the policy, field filters can be specified. + +For example: + + + + +```go +filteredGroupingPolicy := e.GetFilteredGroupingPolicy(0, "alice") +``` + + +```typescript +const filteredGroupingPolicy = await e.getFilteredGroupingPolicy(0, 'alice') +``` + + +```php +$filteredGroupingPolicy = $e->getFilteredGroupingPolicy(0, "alice"); +``` + + +```csharp +var filteredGroupingPolicy = e.GetFilteredGroupingPolicy(0, "alice"); +``` + + +```rust +let filtered_grouping_policy = e.get_filtered_grouping_policy(0, vec!["alice".to_owned()]); +``` + + + +### `GetNamedGroupingPolicy()` + +GetNamedGroupingPolicy gets all the role inheritance rules in the policy. + +For example: + + + + +```go +namedGroupingPolicy := e.GetNamedGroupingPolicy("g") +``` + + +```typescript +const namedGroupingPolicy = await e.getNamedGroupingPolicy('g') +``` + + +```php +$namedGroupingPolicy = $e->getNamedGroupingPolicy("g"); +``` + + +```csharp +var namedGroupingPolicy = e.GetNamedGroupingPolicy("g"); +``` + + +```rust +let named_grouping_policy = e.get_named_grouping_policy("g"); +``` + + + + +### `GetFilteredNamedGroupingPolicy()` + +GetFilteredNamedGroupingPolicy gets all the role inheritance rules in the policy. + +For example: + + + + +```go +namedGroupingPolicy := e.GetFilteredNamedGroupingPolicy("g", 0, "alice") +``` + + +```typescript +const namedGroupingPolicy = await e.getFilteredNamedGroupingPolicy('g', 0, 'alice') +``` + + +```php +$namedGroupingPolicy = $e->getFilteredNamedGroupingPolicy("g", 0, "alice"); +``` + + +```csharp +var namedGroupingPolicy = e.GetFilteredNamedGroupingPolicy("g", 0, "alice"); +``` + + +```rust +let named_grouping_policy = e.get_filtered_named_groupingPolicy("g", 0, vec!["alice".to_owned()]); +``` + + + +### `HasPolicy()` + +HasPolicy determines whether an authorization rule exists. + +For example: + + + + +```go +hasPolicy := e.HasPolicy("data2_admin", "data2", "read") +``` + + +```typescript +const hasPolicy = await e.hasPolicy('data2_admin', 'data2', 'read') +``` + + +```php +$hasPolicy = $e->hasPolicy('data2_admin', 'data2', 'read'); +``` + + +```csharp +var hasPolicy = e.HasPolicy("data2_admin", "data2", "read"); +``` + + +```rust +let has_policy = e.has_policy(vec!["data2_admin".to_owned(), "data2".to_owned(), "read".to_owned()]); +``` + + + +### `HasNamedPolicy()` + +HasNamedPolicy determines whether a named authorization rule exists. + +For example: + + + + +```go +hasNamedPolicy := e.HasNamedPolicy("p", "data2_admin", "data2", "read") +``` + + +```typescript +const hasNamedPolicy = await e.hasNamedPolicy('p', 'data2_admin', 'data2', 'read') +``` + + +```php +$hasNamedPolicy = $e->hasNamedPolicy("p", "data2_admin", "data2", "read"); +``` + + +```csharp +var hasNamedPolicy = e.HasNamedPolicy("p", "data2_admin", "data2", "read"); +``` + + +```rust +let has_named_policy = e.has_named_policy("p", vec!["data2_admin".to_owned(), "data2".to_owned(), "read".to_owned()]); +``` + + + +### `AddPolicy()` + +AddPolicy adds an authorization rule to the current policy. If the rule already exists, the function returns false and the rule will not be added. Otherwise the function returns true by adding the new rule. + +For example: + + + + +```go +added := e.AddPolicy("eve", "data3", "read") +``` + + +```typescript +const p = ['eve', 'data3', 'read'] +const added = await e.addPolicy(...p) +``` + + +```php +$added = $e->addPolicy('eve', 'data3', 'read'); +``` + + +```csharp +var added = e.AddPolicy("eve", "data3", "read"); +or +var added = await e.AddPolicyAsync("eve", "data3", "read"); +``` + + +```rust +let added = e.add_policy(vec!["eve".to_owned(), "data3".to_owned(), "read".to_owned()]); +``` + + + +### `AddPolicies()` + +AddPolicies adds authorization rules to the current policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is added to the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is added to the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesAdded := e.AddPolicies(rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["katy".to_owned(), "data4".to_owned(), "write".to_owned()], + vec!["leyo".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["ham".to_owned(), "data4".to_owned(), "write".to_owned()], +]; + +let are_rules_added = e.add_policies(rules).await? +``` + + +```typescript +const rules = [ + ['jack', 'data4', 'read'], + ['katy', 'data4', 'write'], + ['leyo', 'data4', 'read'], + ['ham', 'data4', 'write'] +]; + +const areRulesAdded = await e.addPolicies(rules); +``` + + + +### `AddNamedPolicy()` + +AddNamedPolicy adds an authorization rule to the current named policy. If the rule already exists, the function returns false and the rule will not be added. Otherwise the function returns true by adding the new rule. + +For example: + + + + +```go +added := e.AddNamedPolicy("p", "eve", "data3", "read") +``` + + +```typescript +const p = ['eve', 'data3', 'read'] +const added = await e.addNamedPolicy('p', ...p) +``` + + +```php +$added = $e->addNamedPolicy("p", "eve", "data3", "read"); +``` + + +```csharp +var added = e.AddNamedPolicy("p", "eve", "data3", "read"); +or +var added = await e.AddNamedPolicyAsync("p", "eve", "data3", "read"); +``` + + +```rust +let added = e.add_named_policy("p", vec!["eve".to_owned(), "data3".to_owned(), "read".to_owned()]).await?; +``` + + + +### `AddNamedPolicies()` + +AddNamedPolicies adds authorization rules to the current named policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is added to the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is added to the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesAdded := e.AddNamedPolicies("p", rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["katy".to_owned(), "data4".to_owned(), "write".to_owned()], + vec!["leyo".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["ham".to_owned(), "data4".to_owned(), "write".to_owned()], +]; + +let are_rules_added := e.add_named_policies("p", rules).await?; +``` + + +```typescript +const rules = [ + ['jack', 'data4', 'read'], + ['katy', 'data4', 'write'], + ['leyo', 'data4', 'read'], + ['ham', 'data4', 'write'] +]; + +const areRulesAdded = await e.addNamedPolicies('p', rules); +``` + + + +### `RemovePolicy()` + +RemovePolicy removes an authorization rule from the current policy. + +For example: + + + + +```go +removed := e.RemovePolicy("alice", "data1", "read") +``` + + +```typescript +const p = ['alice', 'data1', 'read'] +const removed = await e.removePolicy(...p) +``` + + +```php +$removed = $e->removePolicy("alice", "data1", "read"); +``` + + +```csharp +var removed = e.RemovePolicyAsync("alice", "data1", "read"); +or +var removed = await e.RemovePolicyAsync("alice", "data1", "read"); +``` + + +```rust +let removed = e.remove_policy(vec!["alice".to_owned(), "data1".to_owned(), "read".to_owned()]).await?; +``` + + + +### `RemovePolicies()` + +RemovePolicies removes authorization rules from the current policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is removed from the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is removed from the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesRemoved := e.RemovePolicies(rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["katy".to_owned(), "data4".to_owned(), "write".to_owned()], + vec!["leyo".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["ham".to_owned(), "data4".to_owned(), "write".to_owned()], +]; + +let are_rules_removed = e.remove_policies(rules).await?; +``` + + +```typescript +const rules = [ + ['jack', 'data4', 'read'], + ['katy', 'data4', 'write'], + ['leyo', 'data4', 'read'], + ['ham', 'data4', 'write'] +]; + +const areRulesRemoved = await e.removePolicies(rules); +``` + + + + +### `RemoveFilteredPolicy()` + +RemoveFilteredPolicy removes an authorization rule from the current policy, field filters can be specified. RemovePolicy removes an authorization rule from the current policy. + +For example: + + + + +```go +removed := e.RemoveFilteredPolicy(0, "alice", "data1", "read") +``` + + +```typescript +const p = ['alice', 'data1', 'read'] +const removed = await e.removeFilteredPolicy(0, ...p) +``` + + +```php +$removed = $e->removeFilteredPolicy(0, "alice", "data1", "read"); +``` + + +```csharp +var removed = e.RemoveFilteredPolicy("alice", "data1", "read"); +or +var removed = await e.RemoveFilteredPolicyAsync("alice", "data1", "read"); +``` + + +```rust +let removed = e.remove_filtered_policy(0, vec!["alice".to_owned(), "data1".to_owned(), "read".to_owned()]).await?; +``` + + + +### `RemoveNamedPolicy()` + +RemoveNamedPolicy removes an authorization rule from the current named policy. + +For example: + + + + +```go +removed := e.RemoveNamedPolicy("p", "alice", "data1", "read") +``` + + +```typescript +const p = ['alice', 'data1', 'read'] +const removed = await e.removeNamedPolicy('p', ...p) +``` + + +```php +$removed = $e->removeNamedPolicy("p", "alice", "data1", "read"); +``` + + +```csharp +var removed = e.RemoveNamedPolicy("p", "alice", "data1", "read"); +or +var removed = await e.RemoveNamedPolicyAsync("p", "alice", "data1", "read"); +``` + + +```rust +let removed = e.remove_named_policy("p", vec!["alice".to_owned(), "data1".to_owned(), "read".to_owned()]).await?; +``` + + + +### `RemoveNamedPolicies()` + +RemoveNamedPolicies removes authorization rules from the current named policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is removed from the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is removed from the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesRemoved := e.RemoveNamedPolicies("p", rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["katy".to_owned(), "data4".to_owned(), "write".to_owned()], + vec!["leyo".to_owned(), "data4".to_owned(), "read".to_owned()], + vec!["ham".to_owned(), "data4".to_owned(), "write".to_owned()], +]; + +let areRulesRemoved = e.remove_named_policies("p", rules).await?; +``` + + +```typescript +const rules = [ + ['jack', 'data4', 'read'], + ['katy', 'data4', 'write'], + ['leyo', 'data4', 'read'], + ['ham', 'data4', 'write'] +]; + +const areRulesRemoved = await e.removeNamedPolicies('p', rules); +``` + + + +### `RemoveFilteredNamedPolicy()` + +RemoveFilteredNamedPolicy removes an authorization rule from the current named policy, field filters can be specified. + +For example: + + + + +```go +removed := e.RemoveFilteredNamedPolicy("p", 0, "alice", "data1", "read") +``` + + +```typescript +const p = ['alice', 'data1', 'read'] +const removed = await e.removeFilteredNamedPolicy('p', 0, ...p) +``` + + +```php +$removed = $e->removeFilteredNamedPolicy("p", 0, "alice", "data1", "read"); +``` + + +```csharp +var removed = e.RemoveFilteredNamedPolicy("p", 0, "alice", "data1", "read"); +or +var removed = e.RemoveFilteredNamedPolicyAync("p", 0, "alice", "data1", "read"); +``` + + +```rust +let removed = e.remove_filtered_named_policy("p", 0, vec!["alice".to_owned(), "data1".to_owned(), "read".to_owned()]).await?; +``` + + + +### `HasGroupingPolicy()` + +HasGroupingPolicy determines whether a role inheritance rule exists. + +For example: + + + + +```go +has := e.HasGroupingPolicy("alice", "data2_admin") +``` + + +```typescript +const has = await e.hasGroupingPolicy('alice', 'data2_admin') +``` + + +```php +$has = $e->hasGroupingPolicy("alice", "data2_admin"); +``` + + +```csharp +var has = e.HasGroupingPolicy("alice", "data2_admin"); +``` + + +```rust +let has = e.has_grouping_policy(vec!["alice".to_owned(), "data2_admin".to_owned()]); +``` + + + +### `HasNamedGroupingPolicy()` + +HasNamedGroupingPolicy determines whether a named role inheritance rule exists. + +For example: + + + + +```go +has := e.HasNamedGroupingPolicy("g", "alice", "data2_admin") +``` + + +```typescript +const has = await e.hasNamedGroupingPolicy('g', 'alice', 'data2_admin') +``` + + +```php +$has = $e->hasNamedGroupingPolicy("g", "alice", "data2_admin"); +``` + + +```csharp +var has = e.HasNamedGroupingPolicy("g", "alice", "data2_admin"); +``` + + +```rust +let has = e.has_named_grouping_policy("g", vec!["alice".to_owned(), "data2_admin".to_owned()]); +``` + + + + +### `AddGroupingPolicy()` + +AddGroupingPolicy adds a role inheritance rule to the current policy. If the rule already exists, the function returns false and the rule will not be added. Otherwise the function returns true by adding the new rule. + +For example: + + + + +```go +added := e.AddGroupingPolicy("group1", "data2_admin") +``` + + +```typescript +const added = await e.addGroupingPolicy('group1', 'data2_admin') +``` + + +```php +$added = $e->addGroupingPolicy("group1", "data2_admin"); +``` + + +```csharp +var added = e.AddGroupingPolicy("group1", "data2_admin"); +or +var added = await e.AddGroupingPolicyAsync("group1", "data2_admin"); +``` + + +```rust +let added = e.add_grouping_policy(vec!["group1".to_owned(), "data2_admin".to_owned()]).await?; +``` + + + +### `AddGroupingPolicies()` + +AddGroupingPolicies adds role inheritance rules to the current policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is added to the current policy. If all authorization the rules are consistent with the policy rules, the function returns true and each policy rule is added to the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesAdded := e.AddGroupingPolicies(rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["katy".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["leyo".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["ham".to_owned(), "group1".to_owned(), "domain1".to_owned()], +]; + +let areRulesAdded = e.add_grouping_policies(rules).await?; +``` + +```typescript +const groupingRules = [ + ['ham', 'data4_admin'], + ['jack', 'data5_admin'] + ]; + +const areRulesAdded = await e.addGroupingPolicies(groupingRules); +``` + + + +### `AddNamedGroupingPolicy()` + +AddNamedGroupingPolicy adds a named role inheritance rule to the current policy. If the rule already exists, the function returns false and the rule will not be added. Otherwise the function returns true by adding the new rule. + +For example: + + + + +```go +added := e.AddNamedGroupingPolicy("g", "group1", "data2_admin") +``` + + +```typescript +const added = await e.addNamedGroupingPolicy('g', 'group1', 'data2_admin') +``` + + +```php +$added = $e->addNamedGroupingPolicy("g", "group1", "data2_admin"); +``` + + +```csharp +var added = e.AddNamedGroupingPolicy("g", "group1", "data2_admin"); +or +var added = await e.AddNamedGroupingPolicyAsync("g", "group1", "data2_admin"); +``` + + +```rust +let added = e.add_named_grouping_policy("g", vec!["group1".to_owned(), "data2_admin".to_owned()]).await?; +``` + + + + +### `AddNamedGroupingPolicies()` + +AddNamedGroupingPolicies adds named role inheritance rules to the current policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is added to the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is added to the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesAdded := e.AddNamedGroupingPolicies("g", rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["katy".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["leyo".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["ham".to_owned(), "group1".to_owned(), "domain1".to_owned()], +]; + +let are_rules_added = e.add_named_grouping_policies("g", rules).await?; +``` + + +```typescript +const groupingRules = [ + ['ham', 'data4_admin'], + ['jack', 'data5_admin'] + ]; + +const areRulesAdded = await e.addNamedGroupingPolicies('g', groupingRules); +``` + + + +### `RemoveGroupingPolicy()` + +RemoveGroupingPolicy removes a role inheritance rule from the current policy. + +For example: + + + + +```go +removed := e.RemoveGroupingPolicy("alice", "data2_admin") +``` + + +```typescript +const removed = await e.removeGroupingPolicy('alice', 'data2_admin') +``` + + +```php +$removed = $e->removeGroupingPolicy("alice", "data2_admin"); +``` + + +```csharp +var removed = e.RemoveGroupingPolicy("alice", "data2_admin"); +or +var removed = await e.RemoveGroupingPolicyAsync("alice", "data2_admin"); +``` + + +```rust +let removed = e.remove_grouping_policy(vec!["alice".to_owned(), "data2_admin".to_owned()]).await?; +``` + + + +### `RemoveGroupingPolicies()` + +RemoveGroupingPolicies removes role inheritance rules from the current policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is removed from the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is removed from the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesRemoved := e.RemoveGroupingPolicies(rules) +``` + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["katy".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["leyo".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["ham".to_owned(), "group1".to_owned(), "domain1".to_owned()], +]; + +let are_rules_removed = e.remove_grouping_policies(rules).await?; +``` + + +```typescript +const groupingRules = [ + ['ham', 'data4_admin'], + ['jack', 'data5_admin'] + ]; + +const areRulesRemoved = await e.removeGroupingPolicies(groupingRules); +``` + + + +### `RemoveFilteredGroupingPolicy()` + +RemoveFilteredGroupingPolicy removes a role inheritance rule from the current policy, field filters can be specified. + +For example: + + + + +```go +removed := e.RemoveFilteredGroupingPolicy(0, "alice") +``` + + +```typescript +const removed = await e.removeFilteredGroupingPolicy(0, 'alice') +``` + + +```php +$removed = $e->removeFilteredGroupingPolicy(0, "alice"); +``` + + +```csharp +var removed = e.RemoveFilteredGroupingPolicy(0, "alice"); +or +var removed = await e.RemoveFilteredGroupingPolicyAsync(0, "alice"); +``` + + +```rust +let removed = e.remove_filtered_grouping_policy(0, vec!["alice".to_owned()]).await?; +``` + + + +### `RemoveNamedGroupingPolicy()` + +RemoveNamedGroupingPolicy removes a role inheritance rule from the current named policy. + +For example: + + + + +```go +removed := e.RemoveNamedGroupingPolicy("g", "alice") +``` + + +```typescript +const removed = await e.removeNamedGroupingPolicy('g', 'alice') +``` + + +```php +$removed = $e->removeNamedGroupingPolicy("g", "alice"); +``` + + +```csharp +var removed = e.RemoveNamedGroupingPolicy("g", "alice"); +or +var removed = await e.RemoveNamedGroupingPolicyAsync("g", "alice"); +``` + + +```rust +let removed = e.remove_named_grouping_policy("g", vec!["alice".to_owned()]).await?; +``` + + + +### `RemoveNamedGroupingPolicies()` + +RemoveNamedGroupingPolicies removes named role inheritance rules from the current policy. The operation is atomic in nature. Hence, if authorization rules consists of rules which are not consistent with the current policy, the function returns false and no policy rule is removed from the current policy. If all the authorization rules are consistent with the policy rules, the function returns true and each policy rule is removed from the current policy. + +For example: + + + + +```go +rules := [][] string { + []string {"jack", "data4", "read"}, + []string {"katy", "data4", "write"}, + []string {"leyo", "data4", "read"}, + []string {"ham", "data4", "write"}, + } + +areRulesRemoved := e.RemoveNamedGroupingPolicies("g", rules) +``` + + + +```rust +let rules = vec![ + vec!["jack".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["katy".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["leyo".to_owned(), "group1".to_owned(), "domain1".to_owned()], + vec!["ham".to_owned(), "group1".to_owned(), "domain1".to_owned()], +]; + +let are_rules_removed = e.remove_named_grouping_policies("g", rules).await?; +``` + + +```typescript +const groupingRules = [ + ['ham', 'data4_admin'], + ['jack', 'data5_admin'] + ]; + +const areRulesRemoved = await e.removeNamedGroupingPolicies('g', groupingRules); +``` + + + +### `RemoveFilteredNamedGroupingPolicy()` + +RemoveFilteredNamedGroupingPolicy removes a role inheritance rule from the current named policy, field filters can be specified. + +For example: + + + + +```go +removed := e.RemoveFilteredNamedGroupingPolicy("g", 0, "alice") +``` + + +```typescript +const removed = await e.removeFilteredNamedGroupingPolicy('g', 0, 'alice') +``` + + +```php +$removed = $e->removeFilteredNamedGroupingPolicy("g", 0, "alice"); +``` + + +```csharp +var removed = e.RemoveFilteredNamedGroupingPolicy("g", 0, "alice"); +or +var removed = await e.RemoveFilteredNamedGroupingPolicyAsync("g", 0, "alice"); +``` + + +```rust +let removed = e.remove_filtered_named_groupingPolicy("g", 0, vec!["alice".to_owned()]).await?; +``` + + + +### `UpdatePolicy()` + +UpdatePolicy update a old policy to new policy. + +For example: + + + + +```go +updated, err := e.UpdatePolicy([]string{"eve", "data3", "read"}, []string{"eve", "data3", "write"}) +``` + + + +### `UpdatePolicies()` + +UpdatePolicies updates all old policies to new policies. + +For example: + + + + +```go +updated, err := e.UpdatePolicies([][]string{{"eve", "data3", "read"}, {"jack", "data3", "read"}}, [][]string{{"eve", "data3", "write"}, {"jack", "data3", "write"}}) +``` + + + +### `AddFunction()` + +AddFunction adds a customized function. + +For example: + + + + +```go +func CustomFunction(key1 string, key2 string) bool { + if key1 == "/alice_data2/myid/using/res_id" && key2 == "/alice_data/:resource" { + return true + } else if key1 == "/alice_data2/myid/using/res_id" && key2 == "/alice_data2/:id/using/:resId" { + return true + } else { + return false + } +} + +func CustomFunctionWrapper(args ...interface{}) (interface{}, error) { + key1 := args[0].(string) + key2 := args[1].(string) + + return bool(CustomFunction(key1, key2)), nil +} + +e.AddFunction("keyMatchCustom", CustomFunctionWrapper) +``` + + +```text +Method is not implemented +``` + + +```php +func customFunction($key1, $key2) { + if ($key1 == "/alice_data2/myid/using/res_id" && $key2 == "/alice_data/:resource") { + return true; + } elseif ($key1 == "/alice_data2/myid/using/res_id" && $key2 == "/alice_data2/:id/using/:resId") { + return true; + } else { + return false; + } +} + +func customFunctionWrapper(...$args){ + $key1 := $args[0]; + $key2 := $args[1]; + + return customFunction($key1, $key2); +} + +$e->addFunction("keyMatchCustom", customFunctionWrapper); +``` + + + +```rust +fn custom_function(key1: STring, key2: String) { + key1 == "/alice_data2/myid/using/res_id" && key2 == "/alice_data/:resource" || key1 == "/alice_data2/myid/using/res_id" && key2 == "/alice_data2/:id/using/:resId" +} + + +e.add_function("keyMatchCustom", custom_function); +``` + + diff --git a/website/translated_docs/uk-UA/Middlewares.md b/website/translated_docs/uk-UA/Middlewares.md new file mode 100644 index 00000000..c316a69d --- /dev/null +++ b/website/translated_docs/uk-UA/Middlewares.md @@ -0,0 +1,83 @@ +--- +id: middlewares +title: Middlewares +--- + +### Web frameworks + + + + +| Name | Description | +| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Gin](https://github.com/gin-gonic/gin) | A HTTP web framework featuring a Martini-like API with much better performance, via plugin: [authz](https://github.com/gin-contrib/authz) or [gin-casbin](https://github.com/maxwellhertz/gin-casbin) (thanks to [@maxwellhertz](https://github.com/maxwellhertz)) | +| [Beego](https://github.com/astaxie/beego) | An open-source, high-performance web framework for Go, via built-in plugin: [plugins/authz](https://github.com/astaxie/beego/blob/master/plugins/authz) | +| [Caddy](https://github.com/mholt/caddy) | Fast, cross-platform HTTP/2 web server with automatic HTTPS, via plugin: [caddy-authz](https://github.com/casbin/caddy-authz) | +| [Go kit](https://github.com/go-kit/kit) | A toolkit for microservices, via built-in plugin: [plugins/authz](https://github.com/go-kit/kit/tree/master/auth/casbin) | +| [Fiber](https://github.com/gofiber/fiber) | An Express inspired web framework written in Go, via middleware: [fiber-casbin](https://github.com/arsmn/fiber-casbin) or [fiber-casbinrest](https://github.com/prongbang/fiber-casbinrest) | +| [Revel](https://github.com/revel/revel) | A high productivity, full-stack web framework for the Go language, via plugin: [auth/casbin](https://github.com/revel/modules/tree/master/auth/casbin) | +| [Echo](https://github.com/labstack/echo) | High performance, minimalist Go web framework, via plugin: [echo-authz](https://github.com/labstack/echo-contrib/tree/master/casbin) (thanks to [@xqbumu](https://github.com/xqbumu)) or [casbinrest](https://github.com/prongbang/casbinrest) (thanks to [@prongbang](https://github.com/prongbang)) | +| [Iris](https://github.com/kataras/iris) | The fastest web framework for Go in (THIS) Earth. HTTP/2 Ready-To-GO, via plugin: [casbin](https://github.com/iris-contrib/middleware/tree/master/casbin) (thanks to [@hiveminded](https://github.com/hiveminded)) or [iris-middleware-casbin](https://github.com/kokobing/iris-middleware-casbin) | +| [Negroni](https://github.com/urfave/negroni) | Idiomatic HTTP Middleware for Golang, via plugin: [negroni-authz](https://github.com/casbin/negroni-authz) | +| [Chi](https://github.com/pressly/chi) | A lightweight, idiomatic and composable router for building HTTP services, via plugin: [chi-authz](https://github.com/casbin/chi-authz) | +| [Buffalo](https://github.com/gobuffalo/buffalo) | A Go web development eco-system, designed to make your life easier, via plugin: [buffalo-mw-rbac](https://github.com/kgosse/buffalo-mw-rbac) (thanks to [@kgosse](https://github.com/kgosse)) | +| [gqlgen](https://gqlgen.com/) | Go library for building GraphQL servers without any fuss, via plugin: [gqlgen_casbin_RBAC_example](https://github.com/WenyXu/gqlgen_casbin_RBAC_example) | +| [Macaron](https://github.com/go-macaron/macaron) | A high productive and modular web framework in Go, via plugin: [authz](https://github.com/go-macaron/authz) | +| [DotWeb](https://github.com/devfeel/dotweb) | Simple and easy go web micro framework, via plugin: [authz](https://github.com/devfeel/middleware/tree/master/authz) | +| [Tango](https://github.com/lunny/tango) | Micro & pluggable web framework for Go, via plugin: [authz](https://gitea.com/tango/authz) | +| [Baa](https://github.com/go-baa/baa) | An express Go web framework with routing, middleware, dependency injection and http context, via plugin: [authz](https://github.com/baa-middleware/authz) | + + +| Name | Description | +| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Spring Boot](https://projects.spring.io/spring-boot/) | Makes it easy to create Spring-powered applications and services, via plugin: [casbin-spring-boot-starter](https://github.com/jcasbin/casbin-spring-boot-starter) or [jcasbin-springboot-plugin](https://github.com/jcasbin/jcasbin-springboot-plugin) or [Simple SpringBoot security demo with jCasbin](https://github.com/jveverka/spring-examples/tree/master/spring-jcasbin) | +| [Apache Shiro](https://shiro.apache.org/) | A powerful and easy-to-use Java security framework that performs authentication, authorization, cryptography, and session management, via plugin: [shiro-casbin](https://github.com/jcasbin/shiro-casbin) or [shiro-jcasbin-spring-boot-starter](https://github.com/mapleafgo/shiro-jcasbin-spring-boot-starter) | +| [Vert.x](https://vertx.io/) | A tool-kit for building reactive applications on the JVM, via plugin: [vertx-auth-jcasbin](https://github.com/vert-x3/vertx-auth/pull/215) | +| [JFinal](http://www.jfinal.com/) | A simple, light, rapid, independent and extensible Java WEB + ORM framework, via plugin: [jfinal-authz](https://github.com/jcasbin/jfinal-authz) | +| [Nutz](https://nutzam.com/) | Web framework (MVC/IOC/AOP/DAO/JSON) for all Java developers, via plugin: [nutz-authz](https://github.com/jcasbin/nutz-authz) | +| [mangoo I/O](https://github.com/svenkubiak/mangooio) | An intuitive, lightweight, high performance full stack Java web framework, via built-in plugin: [AuthorizationService.java](https://github.com/svenkubiak/mangooio/blob/e8c647a3f7c427bce27377025bec074f6d767f50/mangooio-core/src/main/java/io/mangoo/services/AuthorizationService.java) | + + +| Name | Description | +| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Express](https://github.com/expressjs/express) | Fast, unopinionated, minimalist web framework for node, via plugin: [express-authz](https://github.com/node-casbin/express-authz) | +| [Koa](https://github.com/koajs/koa) | Expressive middleware for node.js using ES2017 async functions, via plugin: [koa-authz](https://github.com/node-casbin/koa-authz) or [koajs-starter](https://github.com/djordjep/koajs-starter) or [koa-casbin](https://github.com/zcong1993/koa-casbin) | +| [LoopBack 4](https://github.com/koajs/koa) | A highly extensible Node.js and TypeScript framework for building APIs and microservices, via plugin: [loopback4-authorization](https://github.com/sourcefuse/loopback4-authorization) | +| [Nest](https://nestjs.com/) | Progressive Node.js framework for building efficient and scalable server-side applications on top of TypeScript & JavaScript. via plugin: [nest-authz](https://github.com/dreamdevil00/nest-authz) or [nest-casbin](https://github.com/pardjs/nest-casbin) or [NestJS Casbin Module](https://github.com/switchit-conseil/nestjs-casbin-module) or [nestjs-casbin](https://github.com/juicycleff/nestjs-casbin) | +| [Fastify](https://github.com/fastify/fastify) | Fast and low overhead web framework, for Node.js. via plugin: [fastify-casbin](https://github.com/nearform/fastify-casbin) or [fastify-casbin-rest](https://github.com/nearform/fastify-casbin-rest) | +| [Egg](https://github.com/eggjs/egg) | Born to build better enterprise frameworks and apps with Node.js & Koa, via plugin: [egg-authz](https://github.com/node-casbin/egg-authz) or [egg-zrole](https://github.com/klren0312/egg-zrole) | +| [hapi](https://hapi.dev/) | The Simple, Secure Framework Developers Trust. via plugin: [hapi-authz](https://github.com/node-casbin/hapi-authz) | +| [Casbin JWT Express](https://github.com/tiagostutz/casbin-jwt-express) | Authorization middleware that uses stateless JWT token to validate ACL rules using Casbin | + + +| Name | Description | +| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Laravel](https://laravel.com/) | The PHP framework for web artisans, via plugin: [laravel-authz](https://github.com/php-casbin/laravel-authz) | +| [Yii PHP Framework](https://www.yiiframework.com/) | A fast, secure, and efficient PHP framework, via plugin: [yii-permission](https://github.com/php-casbin/yii-permission) | +| [CakePHP](https://cakephp.org/) | Build fast, grow solid PHP Framework, via plugin: [cake-casbin](https://github.com/php-casbin/cake-casbin) | +| [CodeIgniter4](https://codeigniter.com/) | Associate users with roles and permissions in CodeIgniter4 Web Framework, via plugin: [CodeIgniter Permission](https://github.com/php-casbin/codeigniter-permission) | +| [ThinkPHP 5.1](http://www.thinkphp.cn/) | The ThinkPHP 5.1 framework, via plugin: [think-casbin](https://github.com/php-casbin/think-casbin) | +| [ThinkPHP 6.0](http://www.thinkphp.cn/) | The ThinkPHP 6.0 framework, via plugin: [think-authz](https://github.com/php-casbin/think-authz) | +| [Symfony](https://symfony.com/) | The Symfony PHP framework, via plugin: [symfony-casbin](https://github.com/videni/symfony-casbin) | +| [Hyperf](https://github.com/hyperf/hyperf) | A coroutine framework that focuses on hyperspeed and flexibility, via plugin: [hyperf-casbin](https://github.com/donjan-deng/hyperf-casbin) | + + +| Name | Description | +| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Django](https://www.djangoproject.com/) | A high-level Python Web framework, via plugin: [django-casbin](https://github.com/pycasbin/django-casbin) | +| [Flask](http://flask.pocoo.org/) | A microframework for Python based on Werkzeug, Jinja 2 and good intentions, via plugin: [flask-authz](https://github.com/pycasbin/flask-authz) or [Flask-Casbin (3rd-party, but maybe more friendly)](https://github.com/daymien/Flask-Casbin) | + + +| Name | Description | +| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core) | An open-source and cross-platform framework for building modern cloud based internet connected applications, such as web apps, IoT apps and mobile backends, via plugin: [Casbin.AspNetCore](https://github.com/casbin-net/Casbin.AspNetCore) | +| [ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core) | A simple demo of using Casbin at ASP.NET Core framework, via plugin: [CasbinACL-aspNetCore](https://github.com/MustafaMustafayev/CasbinACL-aspNetCore) | + + +| Name | Description | +| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Actix](https://github.com/actix/actix) | A Rust actors framework, via plugin: [actix-casbin](https://github.com/casbin-rs/actix-casbin) | +| [Actix web](https://github.com/actix/actix-web) | A small, pragmatic, and extremely fast rust web framework, via plugin: [actix-casbin-auth](https://github.com/casbin-rs/actix-casbin-auth) | +| [Rocket](https://github.com/SergioBenitez/Rocket) | a web framework for Rust that makes it simple to write fast, secure web applications without sacrificing flexibility, usability, or type safety, template: [rocket-casbin-demo](https://github.com/simoin/Rocket_Casbin_Demo) | + + diff --git a/website/translated_docs/uk-UA/ModelStorage.md b/website/translated_docs/uk-UA/ModelStorage.md new file mode 100644 index 00000000..5c9a9c9d --- /dev/null +++ b/website/translated_docs/uk-UA/ModelStorage.md @@ -0,0 +1,91 @@ +--- +id: model-storage +title: Model Storage +--- + +Unlike the policy, the model can be loaded only, it cannot be saved. Because we think the model is not a dynamic component and should not be modified at run-time, so we don't implement an API to save the model into a storage. + +However, the good news is, we provide three equivalent ways to load a model either statically or dynamically: + +## Load model from .CONF file + +This is the most common way to use Casbin. It's easy to understand for beginners and convenient for sharing when you ask Casbin team for help. + +The content of the `.CONF` file [examples/rbac_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_model.conf): + +```ini +[request_definition] +r = sub, obj, act + +[policy_definition] +p = sub, obj, act + +[role_definition] +g = _, _ + +[policy_effect] +e = some(where (p.eft == allow)) + +[matchers] +m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act +``` + +Then you can load the model file as: + +```go +e := casbin.NewEnforcer("examples/rbac_model.conf", "examples/rbac_policy.csv") +``` + +## Load model from code + +The model can be initialized dynamically from code instead of using `.CONF` file. Here's an example for the RBAC model: + +```go +// Initialize the model from Go code. +m := model.NewModel() +m.AddDef("r", "r", "sub, obj, act") +m.AddDef("p", "p", "sub, obj, act") +m.AddDef("g", "g", "_, _") +m.AddDef("e", "e", "some(where (p.eft == allow))") +m.AddDef("m", "m", "g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act") + +// Load the policy rules from the .CSV file adapter. +// Replace it with your adapter to avoid files. +a := persist.NewFileAdapter("examples/rbac_policy.csv") + +// Create the enforcer. +e := casbin.NewEnforcer(m, a) +``` + +## Load model from string + +Or you can just load the entire model text from a multi-line string. The good point for this way is that you do not need to maintain a model file. + +```go +// Initialize the model from a string. +text := +` +[request_definition] +r = sub, obj, act + +[policy_definition] +p = sub, obj, act + +[role_definition] +g = _, _ + +[policy_effect] +e = some(where (p.eft == allow)) + +[matchers] +m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act +` +m, _ := NewModelFromString(text) + +// Load the policy rules from the .CSV file adapter. +// Replace it with your adapter to avoid files. +a := persist.NewFileAdapter("examples/rbac_policy.csv") + +// Create the enforcer. +e := casbin.NewEnforcer(m, a) +``` diff --git a/website/translated_docs/uk-UA/MultiThreading.md b/website/translated_docs/uk-UA/MultiThreading.md new file mode 100644 index 00000000..e6206442 --- /dev/null +++ b/website/translated_docs/uk-UA/MultiThreading.md @@ -0,0 +1,8 @@ +--- +id: multi-threading +title: Multi-threading +--- + +If you use Casbin in a multi-threading manner, you can use the synchronized wrapper of the Casbin enforcer: https://github.com/casbin/casbin/blob/master/enforcer_synced.go. + +It also supports the `AutoLoad` feature, which means the Casbin enforcer will automatically load the latest policy rules from DB if it has changed. Call `StartAutoLoadPolicy()` to start automatically loading policy periodically and call `StopAutoLoadPolicy()` to stop it. diff --git a/website/translated_docs/uk-UA/OnlineEditor.md b/website/translated_docs/uk-UA/OnlineEditor.md new file mode 100644 index 00000000..25469b99 --- /dev/null +++ b/website/translated_docs/uk-UA/OnlineEditor.md @@ -0,0 +1,6 @@ +--- +id: online-editor +title: Online Editor +--- + +You can also use the online editor (https://casbin.org/en/editor/) to write your Casbin model and policy in your web browser. It provides functionality such as `syntax highlighting` and `code completion`, just like an IDE for a programming language. diff --git a/website/translated_docs/uk-UA/Overview.md b/website/translated_docs/uk-UA/Overview.md new file mode 100644 index 00000000..cb6dbcf4 --- /dev/null +++ b/website/translated_docs/uk-UA/Overview.md @@ -0,0 +1,52 @@ +--- +id: overview +title: Overview +--- + +Casbin is a powerful and efficient open-source access control library. It provides support for enforcing authorization based on various access control models. + +## All the languages supported by Casbin: + +| [![golang](https://casbin.org/img/langs/golang.png)](https://github.com/casbin/casbin) | [![java](https://casbin.org/img/langs/java.png)](https://github.com/casbin/jcasbin) | [![nodejs](https://casbin.org/img/langs/nodejs.png)](https://github.com/casbin/node-casbin) | [![php](https://casbin.org/img/langs/php.png)](https://github.com/php-casbin/php-casbin) | +| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| [Casbin](https://github.com/casbin/casbin) | [jCasbin](https://github.com/casbin/jcasbin) | [node-Casbin](https://github.com/casbin/node-casbin) | [PHP-Casbin](https://github.com/php-casbin/php-casbin) | +| production-ready | production-ready | production-ready | production-ready | + +| [![python](https://casbin.org/img/langs/python.png)](https://github.com/casbin/pycasbin) | [![dotnet](https://casbin.org/img/langs/dotnet.png)](https://github.com/casbin/Casbin.NET) | [![c++](https://casbin.org/img/langs/cpp.png)](https://github.com/casbin/casbin-cpp) | [![rust](https://casbin.org/img/langs/rust.png)](https://github.com/casbin/casbin-rs) | +| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | +| [PyCasbin](https://github.com/casbin/pycasbin) | [Casbin.NET](https://github.com/casbin/Casbin.NET) | [Casbin-CPP](https://github.com/casbin/casbin-cpp) | [Casbin-RS](https://github.com/casbin/casbin-rs) | +| production-ready | production-ready | production-ready | production-ready | + +## Feature set for different languages + +| Feature | Go | Java | Node.js | PHP | Python | C# | Delphi | Rust | C++ | +| ----------------------- | -- | ---- | ------- | --- | ------ | -- | ------ | ---- | --- | +| Enforcement | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| RBAC | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| ABAC | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Scaling ABAC (`eval()`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | +| Adapter | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Management API | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| RBAC API | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Batch API | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | +| Filtered Adapter | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | +| Watcher | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Role Manager | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | +| Multi-Threading | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | + +We are always working our best to make Casbin have the same set of features for all languages. But the reality is not that beautiful. The current progress is as the above table. ✅ for Watcher or Role Manager only means having the interface in the core library. Whether there is an available watcher or role manager implementation is another question. + +## What is Casbin? + +What Casbin does: + +1. enforce the policy in the classic `{subject, object, action}` form or a customized form as you defined, both allow and deny authorizations are supported. +2. handle the storage of the access control model and its policy. +3. manage the role-user mappings and role-role mappings (aka role hierarchy in RBAC). +4. support built-in superuser like `root` or `administrator`. A superuser can do anything without explicit permissions. +5. multiple built-in operators to support the rule matching. For example, `keyMatch` can map a resource key `/foo/bar` to the pattern `/foo*`. + +What Casbin does NOT do: + +1. authentication (aka verify `username` and `password` when a user logs in) +2. manage the list of users or roles. I believe it's more convenient for the project itself to manage these entities. Users usually have their passwords, and Casbin is not designed as a password container. However, Casbin stores the user-role mapping for the RBAC scenario. diff --git a/website/translated_docs/uk-UA/Performance.md b/website/translated_docs/uk-UA/Performance.md new file mode 100644 index 00000000..b2959335 --- /dev/null +++ b/website/translated_docs/uk-UA/Performance.md @@ -0,0 +1,28 @@ +--- +id: performance +title: Performance Optimization +--- + +When applied in a production environment with millions of users or permissions, you may encounter performance downgrade in Casbin enforcement, there are usually two causes: + +#### High Volume Traffic + +The number of coming requests per second is too large, e.g., 10,000 request/s for a single Casbin instance. In such case, a single Casbin instance is usually not enough to handle all the requests. There are 2 possible solutions: + +1. Use multi-threading to enable multiple Casbin instances, so you can fully utilize all the cores in the machine. See details at: [Multi-threading](/docs/en/multi-threading). + +2. Deploy Casbin instances to a cluster (multiple machines). Use Watcher to guarantee all Casbin instances are consistent. See details at: [Watchers](/docs/en/watchers). + +:::note You can use the above methods both at the same time, e.g., deploy Casbin to a 10-machine cluster. Each machine has 5 threads simultaneously to serve Casbin enforcement requests. ::: + +#### High Number of Policy Rules + +Millions of policy rules may be required in a cloud or multi-tenant environment. Each enforcement call or even loading the policy rules at the initial time is very slow. Such cases can usually be mitigated in several ways: + +1. Your Casbin model or policy is not well-designed. A well-written model and policy will abstract out the duplicated logic for each user/tenant and reduce the number of rules to a very small level (< 100): e.g., you can share some default rules across all tenants and let users customize their rules later. Customized rules can override the default rules. If you still have question, please send GitHub issue to the Casbin repos. + +2. Do sharding to let a Casbin enforcer only load a small set of policy rules, e.g., enforcer_0 only serves for tenant_0 to tenant_99, enforcer_1 only serves for tenant_100 to tenant_199. To load only a subset of all policy rules, see details at: [Policy Subset Loading](/docs/en/policy-subset-loading). + +3. Grant permissions to RBAC roles instead of users directly. Casbin's RBAC is implemented by a role inheritance tree (as a cache). So given a user like Alice, Casbin only uses O(1) time to query the RBAC tree for role-user relationship and do enforcement. If your g rules don't change often, then the RBAC tree won't need to update. See details at this dicussion: https://github.com/casbin/casbin/issues/681#issuecomment-763801583 + +:::note You can try the above methods all at the same time. ::: diff --git a/website/translated_docs/uk-UA/PolicyStorage.md b/website/translated_docs/uk-UA/PolicyStorage.md new file mode 100644 index 00000000..c27a8b01 --- /dev/null +++ b/website/translated_docs/uk-UA/PolicyStorage.md @@ -0,0 +1,6 @@ +--- +id: policy-storage +title: Policy Storage +--- + +In Casbin, the policy storage is implemented as an adapter. Please go to: [/docs/en/adapters](/docs/en/adapters) diff --git a/website/translated_docs/uk-UA/PolicySubsetLoading.md b/website/translated_docs/uk-UA/PolicySubsetLoading.md new file mode 100644 index 00000000..5ac7a67a --- /dev/null +++ b/website/translated_docs/uk-UA/PolicySubsetLoading.md @@ -0,0 +1,27 @@ +--- +id: policy-subset-loading +title: Policy Subset Loading +--- + +Some adapters support filtered policy management. This means that the policy loaded by Casbin is a subset of the policy in storage based on a given filter. This allows for efficient policy enforcement in large, multi-tenant environments when parsing the entire policy becomes a performance bottleneck. + +To use filtered policies with a supported adapter, simply call the `LoadFilteredPolicy` method. The valid format for the filter parameter depends on the adapter used. To prevent accidental data loss, the `SavePolicy` method is disabled when a filtered policy is loaded. + +For example, the following code snippet uses the built-in filtered file adapter and the RBAC model with domains. In this case, the filter limits the policy to a single domain. Any policy lines for domains other than `"domain1"` are omitted from the loaded policy: + +```go +import "github.com/casbin/casbin" + +enforcer := casbin.NewEnforcer() + +adapter := fileadapter.NewFilteredAdapter("examples/rbac_with_domains_policy.csv") +enforcer.InitWithAdapter("examples/rbac_with_domains_model.conf", adapter) + +filter := &fileadapter.Filter{ + P: []string{"", "domain1"}, + G: []string{"", "", "domain1"}, +} +enforcer.LoadFilteredPolicy(filter) + +// The loaded policy now only contains the entries pertaining to "domain1". +``` diff --git a/website/translated_docs/uk-UA/PrivacyPolicy.md b/website/translated_docs/uk-UA/PrivacyPolicy.md new file mode 100644 index 00000000..8ebfcbf0 --- /dev/null +++ b/website/translated_docs/uk-UA/PrivacyPolicy.md @@ -0,0 +1,20 @@ +--- +id: privacy-policy +title: Privacy Policy +--- + +Your privacy is important to us. It is Casbin's policy to respect your privacy regarding any information we may collect from you across our website, https://casbin.org, and other sites we own and operate. + +We only ask for personal information when we truly need it to provide a service to you. We collect it by fair and lawful means, with your knowledge and consent. We also let you know why we’re collecting it and how it will be used. + +We only retain collected information for as long as necessary to provide you with your requested service. What data we store, we’ll protect within commercially acceptable means to prevent loss and theft, as well as unauthorized access, disclosure, copying, use or modification. + +We don’t share any personally identifying information publicly or with third-parties, except when required to by law. + +Our website may link to external sites that are not operated by us. Please be aware that we have no control over the content and practices of these sites, and cannot accept responsibility or liability for their respective privacy policies. + +You are free to refuse our request for your personal information, with the understanding that we may be unable to provide you with some of your desired services. + +Your continued use of our website will be regarded as acceptance of our practices around privacy and personal information. If you have any questions about how we handle user data and personal information, feel free to contact us. + +This policy is effective as of 29 June 2020. diff --git a/website/translated_docs/uk-UA/RBAC.md b/website/translated_docs/uk-UA/RBAC.md new file mode 100644 index 00000000..c172cfbc --- /dev/null +++ b/website/translated_docs/uk-UA/RBAC.md @@ -0,0 +1,121 @@ +--- +id: rbac +title: RBAC +--- + +## Role definition + +`[role_definition]` is the definition for the RBAC role inheritance relations. Casbin supports multiple instances of RBAC systems, e.g., users can have roles and their inheritance relations, and resources can have roles and their inheritance relations too. These two RBAC systems won't interfere. + +This section is optional. If you don't use RBAC roles in the model, then omit this section. + +```ini +[role_definition] +g = _, _ +g2 = _, _ +``` + +The above role definition shows that `g` is a RBAC system, and `g2` is another RBAC system. `_, _` means there are two parties inside an inheritance relation. As a common case, you usually use `g` alone if you only need roles on users. You can also use `g` and `g2` when you need roles (or groups) on both users and resources. Please see the [rbac_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_model.conf) and [rbac_model_with_resource_roles.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_with_resource_roles_model.conf) for examples. + +Casbin stores the actual user-role mapping (or resource-role mapping if you are using roles on resources) in the policy, for example: + +``` +p, data2_admin, data2, read +g, alice, data2_admin +``` + +It means `alice` inherits/is a member of role `data2_admin`. `alice` here can be a user, a resource or a role. Casbin only recognizes it as a string. + +Then in a matcher, you should check the role as below: + +```ini +[matchers] +m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act +``` + +It means `sub` in the request should have the role `sub` in the policy. + +:::note +1. Casbin only stores the user-role mapping. +2. Casbin doesn't verify whether a user is a valid user, or role is a valid role. That should be taken care of by authentication. +3. Do not use the same name for a user and a role inside a RBAC system, because Casbin recognizes users and roles as strings, and there's no way for Casbin to know whether you are specifying user `alice` or role `alice`. You can simply solve it by using `role_alice`. +4. If `A` has role `B`, `B` has role `C`, then `A` has role `C`. This transitivity is infinite for now. ::: + +## Role hierarchy + +Casbin's RBAC supports RBAC1's role hierarchy feature, meaning if `alice` has `role1`, `role1` has `role2`, then `alice` will also have `role2` and inherit its permissions. + +Here is a concept called hierarchy level. So the hierarchy level for this example is 2. For the built-in role manager in Casbin, you can specify the max hierarchy level. The default value is 10. It means an end user like `alice` can only inherit 10 levels of roles. + +```go +// NewRoleManager is the constructor for creating an instance of the +// default RoleManager implementation. +func NewRoleManager(maxHierarchyLevel int) rbac.RoleManager { + rm := RoleManager{} + rm.allRoles = &sync.Map{} + rm.maxHierarchyLevel = maxHierarchyLevel + rm.hasPattern = false + + return &rm +} +``` + +## How to distinguish role from user? + +Casbin doesn't distinguish role from user in its RBAC. They are all treated as strings. If you only use single-level RBAC (a role will never be a member of another role). You can use `e.GetAllSubjects()` to get all users and `e.GetAllRoles()` to get all roles. They just list all `u` and all `r` respectively in all `g, u, r` rules. + +But if you are using multi-level RBAC (with role hierarchy), and your application doesn't record whether a name (string) is a user or a role, or you have user and role with same name. You can add a prefix to role like `role::admin` before passing it to Casbin. So you will know if it's a role by checking this prefix. + +## How to query implicit roles or permissions? + +When a user inherits a role or permission via RBAC hierarchy instead of directly assigning them in a policy rule, we call such type of assignment as `implicit`. To query such implicit relations, you need to use these 2 APIs: `GetImplicitRolesForUser()` and `GetImplicitPermissionsForUser` instead of `GetRolesForUser()` and `GetPermissionsForUser`. For more details, please see [this GitHub issue](https://github.com/casbin/casbin/issues/137). + +## Use pattern matching in RBAC + +Sometimes, you want some subjects, object or domains/tenants with the specific pattern to be automatically granted to a role. Pattern matching functions in RBAC can help you do that. A pattern matching function shares the same parameters and return value as the previous [matcher function](https://casbin.org/docs/en/syntax-for-models#functions-in-matchers). + +The pattern matching function supports each parameter of g. + +We know that normally RBAC is expressed as `g(r.sub, p.sub)` in matcher. Then we will use policy like: + +``` +p, alice, book_group, read +g, /book/1, book_group +g, /book/2, book_group +``` + +So `alice` can read all books including `book 1` and `book 2`. But there can be thousands of books and it's very tedious to add each book to the book role (or group) with one `g` policy rule. + +But with pattern matching functions, you can write the policy with only one line: + +``` +g, /book/:id, book_group +``` + +Casbin will automatically match `/book/1` and `/book/2` into pattern `/book/:id` for you. You only need to register the function with the enforcer like: + +```go +r := e.GetRoleManager() +r.(*defaultrolemanager.RoleManager).AddMatchingFunc("KeyMatch2",util.KeyMatch2) +``` + +When Using a pattern matching function in domains/tenants, You need to register the function to enforcer and model. + +register `keyMatch2` to enforcer: + +```go +r := e.GetRoleManager() +r.(*defaultrolemanager.RoleManager).AddDomainMatchingFunc("KeyMatch2",util.KeyMatch2) +``` + +register `keyMatch2` to model: + +``` +m = g(r.sub, p.sub, r.dom) && keyMatch2(r.dom, p.dom) && r.obj == p.obj && r.act == p.act +``` + +You can see the full example [here](https://github.com/casbin/casbin/blob/dbdb6cbe2e7a80863e4951f9ff36da07fef01b75/model_test.go#L278-L307). + +## Role manager + +See [Role Managers](/docs/en/role-managers) section for details. diff --git a/website/translated_docs/uk-UA/RBACAPI.md b/website/translated_docs/uk-UA/RBACAPI.md new file mode 100644 index 00000000..1a68ed88 --- /dev/null +++ b/website/translated_docs/uk-UA/RBACAPI.md @@ -0,0 +1,672 @@ +--- +id: rbac-api +title: RBAC API +--- + +A more friendly API for RBAC. This API is a subset of Management API. The RBAC users could use this API to simplify the code. + +## Reference + +global variable `e` is Enforcer instance. + + + + +```go +e, err := NewEnforcer("examples/rbac_model.conf", "examples/rbac_policy.csv") +``` + + +```typescript +const e = await newEnforcer('examples/rbac_model.conf', 'examples/rbac_policy.csv') +``` + + +```php +$e = new Enforcer('examples/rbac_model.conf', 'examples/rbac_policy.csv'); +``` + + +```csharp +var e = new Enforcer("path/to/model.conf", "path/to/policy.csv"); +``` + + +```rust +let mut e = Enforcer::new("examples/rbac_model.conf", "examples/rbac_policy.csv").await?; +``` + + + + +### `GetRolesForUser()` + +GetRolesForUser gets the roles that a user has. + +For example: + + + + +```go +res := e.GetRolesForUser("alice") +``` + + +```typescript +const res = await e.getRolesForUser('alice') +``` + + +```php +$res = $e->getRolesForUser("alice"); +``` + + +```csharp +var res = e.GetRolesForUser("alice"); +``` + + +```rust +let roles = e.get_roles_for_user("alice", None); // No domain +``` + + + +### `GetUsersForRole()` + +GetUsersForRole gets the users that has a role. + +For example: + + + + +```go +res := e.GetUsersForRole("data1_admin") +``` + + +```typescript +const res = await e.getUsersForRole('data1_admin') +``` + + +```php +$res = $e->getUsersForRole("data1_admin"); +``` + + +```csharp +var res = e.GetUsersForRole("data1_admin"); +``` + + +```rust +let users = e.get_users_for_role("data1_admin", None); // No domain +``` + + + +### `HasRoleForUser()` + +HasRoleForUser determines whether a user has a role. + +For example: + + + + +```go +res := e.HasRoleForUser("alice", "data1_admin") +``` + + +```typescript +const res = await e.hasRoleForUser('alice', 'data1_admin') +``` + + +```php +$res = $e->hasRoleForUser("alice", "data1_admin"); +``` + + +```csharp +var res = e.HasRoleForUser("alice", "data1_admin"); +``` + + +```rust +let has = e.has_role_for_user("alice", "data1_admin", None); // No domain +``` + + + +### `AddRoleForUser()` + +AddRoleForUser adds a role for a user. Returns false if the user already has the role (aka not affected). + +For example: + + + + +```go +e.AddRoleForUser("alice", "data2_admin") +``` + + +```typescript +await e.addRoleForUser('alice', 'data2_admin') +``` + + +```PHP +$e->addRoleForUser("alice", "data2_admin"); +``` + + +```csharp +var added = e.AddRoleForUser("alice", "data2_admin"); +or +var added = await e.AddRoleForUserAsync("alice", "data2_admin"); +``` + + +```rust +let added = e.add_role_for_user("alice", "data2_admin", None).await?; // No domain +``` + + + + +### `AddRolesForUser()` + +AddRolesForUser adds multiple roles for a user. Returns false if the user already has one of these roles (aka not affected). + +For example: + + + + +```rust +let roles = vec!["data1_admin".to_owned(), "data2_admin".to_owned()]; +let all_added = e.add_roles_for_user("alice", roles, None).await?; // No domain +``` + + + + +### `DeleteRoleForUser()` + +DeleteRoleForUser deletes a role for a user. Returns false if the user does not have the role (aka not affected). + +For example: + + + + +```go +e.DeleteRoleForUser("alice", "data1_admin") +``` + + +```typescript +await e.deleteRoleForUser('alice', 'data1_admin') +``` + + +```php +$e->deleteRoleForUser("alice", "data1_admin"); +``` + + +```csharp +var deleted = e.DeleteRoleForUser("alice", "data1_admin"); +or +var deleted = await e.DeleteRoleForUser("alice", "data1_admin"); +``` + + +```rust +let deleted = e.delete_role_for_user("alice", "data1_admin", None).await?; // No domain +``` + + + + +### `DeleteRolesForUser()` + +DeleteRolesForUser deletes all roles for a user. Returns false if the user does not have any roles (aka not affected). + +For example: + + + + +```go +e.DeleteRolesForUser("alice") +``` + + +```typescript +await e.deleteRolesForUser('alice') +``` + + +```php +$e->deleteRolesForUser("alice"); +``` + + +```csharp +var deletedAtLeastOne = e.DeleteRolesForUser("alice"); +or +var deletedAtLeastOne = await e.DeleteRolesForUserAsync("alice"); +``` + + +```rust +let deleted_at_least_one = e.delete_roles_for_user("alice", None).await?; // No domain +``` + + + +### `DeleteUser()` + +DeleteUser deletes a user. Returns false if the user does not exist (aka not affected). + +For example: + + + + +``` +e.DeleteUser("alice") +``` + + +```typescript +await e.deleteUser('alice') +``` + + +```php +$e->deleteUser("alice"); +``` + + +```csharp +var deleted = e.DeleteUser("alice"); +or +var deleted = await e.DeleteUserAsync("alice"); +``` + + +```rust +let deleted = e.delete_user("alice").await?; +``` + + + +### `DeleteRole()` + +DeleteRole deletes a role. + +For example: + + + + +```go +e.DeleteRole("data2_admin") +``` + + +```typescript +await e.deleteRole("data2_admin") +``` + + +```php +$e->deleteRole("data2_admin"); +``` + + +```csharp +var deleted = e.DeleteRole("data2_admin"); +or +var deleted = await e.DeleteRoleAsync("data2_admin"); +``` + + +```rust +let deleted = e.delete_role("data2_admin").await?; +``` + + + +### `DeletePermission()` + +DeletePermission deletes a permission. Returns false if the permission does not exist (aka not affected). + +For example: + + + + +```go +e.DeletePermission("read") +``` + + +```typescript +await e.deletePermission('read') +``` + + +```php +$e->deletePermission("read"); +``` + + +```csharp +var deleted = e.DeletePermission("read"); +or +var deleted = await e.DeletePermissionAsync("read"); +``` + + +```rust +let deleted = e.delete_permission(vec!["read".to_owned()]).await?; +``` + + + + +### `AddPermissionForUser()` + +AddPermissionForUser adds a permission for a user or role. Returns false if the user or role already has the permission (aka not affected). + +For example: + + + + +```go +e.AddPermissionForUser("bob", "read") +``` + + +```typescript +await e.addPermissionForUser('bob', 'read') +``` + + +```php +$e->addPermissionForUser("bob", "read"); +``` + + +```csharp +var added = e.AddPermissionForUser("bob", "read"); +or +var added = await e.AddPermissionForUserAsync("bob", "read"); +``` + + +```rust +let added = e.add_permission_for_user("bob", vec!["read".to_owned()]).await?; +``` + + + +### `AddPermissionsForUser()` + +AddPermissionsForUser adds multiple permissions for a user or role. Returns false if the user or role already has one of the permissions (aka not affected). + +For example: + + + + +```rust +let permissions = vec![ + vec!["data1".to_owned(), "read".to_owned()], + vec!["data2".to_owned(), "write".to_owned()], +]; + +let all_added = e.add_permissions_for_user("bob", permissions).await?; +``` + + + + +### `DeletePermissionForUser()` + +DeletePermissionForUser deletes a permission for a user or role. Returns false if the user or role does not have the permission (aka not affected). + +For example: + + + + +```go +e.DeletePermissionForUser("bob", "read") +``` + + +```typescript +await e.deletePermissionForUser("bob", "read") +``` + + +```php +$e->deletePermissionForUser("bob", "read"); +``` + + +```csharp +var deleted = e.DeletePermissionForUser("bob", "read"); +or +var deleted = await e.DeletePermissionForUserAsync("bob", "read"); +``` + + +```rust +let deleted = e.delete_permission_for_user("bob", vec!["read".to_owned()]).await?; +``` + + + + +### `DeletePermissionsForUser()` + +DeletePermissionsForUser deletes permissions for a user or role. Returns false if the user or role does not have any permissions (aka not affected). + +For example: + + + + +```go +e.DeletePermissionsForUser("bob") +``` + + +```typescript +await e.deletePermissionsForUser('bob') +``` + + +```php +$e->deletePermissionsForUser("bob"); +``` + + +```csharp +var deletedAtLeastOne = e.DeletePermissionsForUser("bob"); +or +var deletedAtLeastOne = await e.DeletePermissionsForUserAsync("bob"); +``` + + +```rust +let deleted_at_least_one = e.delete_permissions_for_user("bob").await?; +``` + + + +### `GetPermissionsForUser()` + +GetPermissionsForUser gets permissions for a user or role. + +For example: + + + + +```go +e.GetPermissionsForUser("bob") +``` + + +```typescript +await e.getPermissionsForUser('bob') +``` + + +```php +$e->getPermissionsForUser("bob"); +``` + + +```csharp +var permissions = e.GetPermissionsForUser("bob"); +``` + + + +### `HasPermissionForUser()` + +HasPermissionForUser determines whether a user has a permission. + +For example: + + + + +```go +e.HasPermissionForUser("alice", []string{"read"}) +``` + + +```typescript +await e.hasPermissionForUser('alice', 'read') +``` + + +```php +$e->hasPermissionForUser("alice", []string{"read"}); +``` + + +```csharp +var has = e.HasPermissionForUser("bob", "read"); +``` + + +```rust +let has = e.has_permission_for_user("alice", vec!["data1".to_owned(), "read".to_owned()]); +``` + + + +### `GetImplicitRolesForUser()` + +GetImplicitRolesForUser gets implicit roles that a user has. Compared to GetRolesForUser(), this function retrieves indirect roles besides direct roles. + +For example: +g, alice, role:admin +g, role:admin, role:user + +GetRolesForUser("alice") can only get: ["role:admin"]. +But GetImplicitRolesForUser("alice") will get: ["role:admin", "role:user"]. + + +For example: + + + + +```go +e.GetImplicitRolesForUser("alice") +``` + + +```typescript +await e.getImplicitRolesForUser("alice") +``` + + +```php +$e->getImplicitRolesForUser("alice"); +``` + + +```csharp +var implicitRoles = e.GetImplicitRolesForUser("alice"); +``` + + +```rust +e.get_implicit_roles_for_user("alice", None); // No domain +``` + + + +### `GetImplicitPermissionsForUser()` + +GetImplicitPermissionsForUser gets implicit permissions for a user or role. +Compared to GetPermissionsForUser(), this function retrieves permissions for inherited roles. + +For example: +p, admin, data1, read +p, alice, data2, read +g, alice, admin + +GetPermissionsForUser("alice") can only get: [["alice", "data2", "read"]]. +But GetImplicitPermissionsForUser("alice") will get: [["admin", "data1", "read"], ["alice", "data2", "read"]]. + +For example: + + + + +```go +e.GetImplicitPermissionsForUser("alice") +``` + + +```text +await e.getImplicitPermissionsForUser("alice") +``` + + +```php +$e->getImplicitPermissionsForUser("alice"); +``` + + +```csharp +var implicitPermissions = e.GetImplicitPermissionsForUser("alice"); +``` + + +```rust +e.get_implicit_permissions_for_user("alice", None); // No domain +``` + + diff --git a/website/translated_docs/uk-UA/RBACWithDomains.md b/website/translated_docs/uk-UA/RBACWithDomains.md new file mode 100644 index 00000000..089a68cc --- /dev/null +++ b/website/translated_docs/uk-UA/RBACWithDomains.md @@ -0,0 +1,36 @@ +--- +id: rbac-with-domains +title: RBAC with Domains +--- + +## Role definition with domains tenants + +The RBAC roles in Casbin can be global or domain-specific. Domain-specify roles mean that the roles for a user can be different when the user is at different domains/tenants. This is very useful for large systems like a cloud, as the users are usually in different tenants. + +The role definition with domains/tenants should be something like: + +```ini +[role_definition] +g = _, _, _ +``` + +The 3rd `_` means the name of domain/tenant, this part should not be changed. Then the policy can be: + +``` +p, admin, tenant1, data1, read +p, admin, tenant2, data2, read + +g, alice, admin, tenant1 +g, alice, user, tenant2 +``` + +It means `admin` role in `tenant1` can read `data1`. And `alice` has `admin` role in `tenant1`, and has `user` role in `tenant2`. So she can read `data1`. However, since `alice` is not an `admin` in `tenant2`, she cannot read `data2`. + +Then in a matcher, you should check the role as below: + +```ini +[matchers] +m = g(r.sub, p.sub, r.dom) && r.dom == p.dom && r.obj == p.obj && r.act == p.act +``` + +Please see the [rbac_with_domains_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_with_domains_model.conf) for examples. diff --git a/website/translated_docs/uk-UA/RoleManagers.md b/website/translated_docs/uk-UA/RoleManagers.md new file mode 100644 index 00000000..ced3c279 --- /dev/null +++ b/website/translated_docs/uk-UA/RoleManagers.md @@ -0,0 +1,49 @@ +--- +id: role-managers +title: Role Managers +--- + +The role manager is used to manage the RBAC role hierarchy (user-role mapping) in Casbin. A role manager can retrieve the role data from Casbin policy rules or external sources such as LDAP, Okta, Auth0, Azure AD, etc. We support different implementations of a role manager. To keep light-weight, we don't put role manager code in the main library (except the default role manager). A complete list of Casbin role managers is provided as below. Any 3rd-party contribution on a new role manager is welcomed, please inform us and I will put it in this list:) + + + + +| Role manager | Author | Description | +| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Default Role Manager (built-in)](https://github.com/casbin/casbin/blob/master/rbac/default-role-manager/role_manager.go) | Casbin | Supports role hierarchy stored in Casbin policy | +| [Session Role Manager](https://github.com/casbin/session-role-manager) | [EDOMO Systems](https://github.com/edomosystems) | Supports role hierarchy stored in Casbin policy, with time-range-based sessions | +| [Okta Role Manager](https://github.com/casbin/okta-role-manager) | Casbin | Supports role hierarchy stored in [Okta](https://www.okta.com/) | +| [Auth0 Role Manager](https://github.com/casbin/auth0-role-manager) | Casbin | Supports role hierarchy stored in [Auth0](https://auth0.com/)'s [Authorization Extension](https://auth0.com/docs/extensions/authorization-extension/v2) | + +For developers: all role managers must implement the [RoleManager](https://github.com/casbin/casbin/blob/master/rbac/role_manager.go) interface. [Session Role Manager](https://github.com/casbin/session-role-manager) can be used as a reference implementation. + + +| Role manager | Author | Description | +| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------- | +| [Default Role Manager (built-in)](https://github.com/casbin/jcasbin/blob/master/src/main/java/org/casbin/jcasbin/rbac/DefaultRoleManager.java) | Casbin | Supports role hierarchy stored in Casbin policy | + +For developers: all role managers must implement the [RoleManager](https://github.com/casbin/jcasbin/blob/master/src/main/java/org/casbin/jcasbin/rbac/RoleManager.java) interface. [Default Role Manager](https://github.com/casbin/jcasbin/blob/master/src/main/java/org/casbin/jcasbin/rbac/DefaultRoleManager.java) can be used as a reference implementation. + + +| Role manager | Author | Description | +| ------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------- | +| [Default Role Manager (built-in)](https://github.com/casbin/node-casbin/blob/master/src/rbac/defaultRoleManager.ts) | Casbin | Supports role hierarchy stored in Casbin policy | +| [Session Role Manager](https://github.com/node-casbin/session-role-manager) | Casbin | Supports role hierarchy stored in Casbin policy, with time-range-based sessions | + +For developers: all role managers must implement the [RoleManager](https://github.com/casbin/node-casbin/blob/master/src/rbac/roleManager.ts) interface. [Default Role Manager](https://github.com/casbin/node-casbin/blob/master/src/rbac/defaultRoleManager.ts) can be used as a reference implementation. + + +| Role manager | Author | Description | +| ----------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------- | +| [Default Role Manager (built-in)](https://github.com/php-casbin/php-casbin/blob/master/src/Rbac/DefaultRoleManager/RoleManager.php) | Casbin | Supports role hierarchy stored in Casbin policy | + +For developers: all role managers must implement the [RoleManager](https://github.com/php-casbin/php-casbin/blob/master/src/Rbac/RoleManager.php) interface. [Default Role Manager](https://github.com/php-casbin/php-casbin/blob/master/src/Rbac/DefaultRoleManager/RoleManager.php) can be used as a reference implementation. + + +| Role manager | Author | Description | +| ---------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------- | +| [Default Role Manager (built-in)](https://github.com/casbin/pycasbin/blob/master/casbin/rbac/default_role_manager/role_manager.py) | Casbin | Supports role hierarchy stored in Casbin policy | + +For developers: all role managers must implement the [RoleManager](https://github.com/casbin/pycasbin/blob/master/casbin/rbac/role_manager.py) interface. [Default Role Manager](https://github.com/casbin/pycasbin/blob/master/casbin/rbac/default_role_manager/role_manager.py) can be used as a reference implementation. + + diff --git a/website/translated_docs/uk-UA/Service.md b/website/translated_docs/uk-UA/Service.md new file mode 100644 index 00000000..7dba6f9e --- /dev/null +++ b/website/translated_docs/uk-UA/Service.md @@ -0,0 +1,13 @@ +--- +id: service +title: Casbin Service +--- + +## How to use Casbin as a service? + +| Name | Description | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Casbin Server](https://github.com/casbin/casbin-server) | The official `Casbin as a Service` solution based on [gRPC](https://grpc.io/), both Management API and RBAC API are provided. | +| [PaySuper Casbin Server](https://github.com/paysuper/casbin-server) | PaySuper's fork of the above official `Casbin-Server` but more actively maintained. It provides [go-micro](https://micro.mu/) interface for Casbin authorization. | +| [Go-Simple-API-Gateway (Archived)](https://github.com/Soontao/go-simple-api-gateway) | A simple API gateway written by golang, supports for authentication and authorization. | +| [middleware-acl](https://github.com/luk4z7/middleware-acl) | RESTful access control middleware based on Casbin. | diff --git a/website/translated_docs/uk-UA/SupportedModels.md b/website/translated_docs/uk-UA/SupportedModels.md new file mode 100644 index 00000000..6bbcffdc --- /dev/null +++ b/website/translated_docs/uk-UA/SupportedModels.md @@ -0,0 +1,33 @@ +--- +id: supported-models +title: Supported Models +--- + +1. [**ACL (Access Control List)**](https://en.wikipedia.org/wiki/Access_control_list) +2. **ACL with [superuser](https://en.wikipedia.org/wiki/Superuser)** +3. **ACL without users**: especially useful for systems that don't have authentication or user log-ins. +3. **ACL without resources**: some scenarios may target for a type of resources instead of an individual resource by using permissions like `write-article`, `read-log`. It doesn't control the access to a specific article or log. +4. **[RBAC (Role-Based Access Control)](https://en.wikipedia.org/wiki/Role-based_access_control)** +5. **RBAC with resource roles**: both users and resources can have roles (or groups) at the same time. +6. **RBAC with domains/tenants**: users can have different role sets for different domains/tenants. +7. **[ABAC (Attribute-Based Access Control)](https://en.wikipedia.org/wiki/Attribute-Based_Access_Control)**: syntax sugar like `resource.Owner` can be used to get the attribute for a resource. +8. **[RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer)**: supports paths like `/res/*`, `/res/:id` and HTTP methods like `GET`, `POST`, `PUT`, `DELETE`. +9. **Deny-override**: both allow and deny authorizations are supported, deny overrides the allow. +10. **Priority**: the policy rules can be prioritized like firewall rules. + +## Examples + +| Model | Model file | Policy file | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | +| ACL | [basic_model.conf](https://github.com/casbin/casbin/blob/master/examples/basic_model.conf) | [basic_policy.csv](https://github.com/casbin/casbin/blob/master/examples/basic_policy.csv) | +| ACL with superuser | [basic_with_root_model.conf](https://github.com/casbin/casbin/blob/master/examples/basic_with_root_model.conf) | [basic_policy.csv](https://github.com/casbin/casbin/blob/master/examples/basic_policy.csv) | +| ACL without users | [basic_without_users_model.conf](https://github.com/casbin/casbin/blob/master/examples/basic_without_users_model.conf) | [basic_without_users_policy.csv](https://github.com/casbin/casbin/blob/master/examples/basic_without_users_policy.csv) | +| ACL without resources | [basic_without_resources_model.conf](https://github.com/casbin/casbin/blob/master/examples/basic_without_resources_model.conf) | [basic_without_resources_policy.csv](https://github.com/casbin/casbin/blob/master/examples/basic_without_resources_policy.csv) | +| RBAC | [rbac_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_model.conf) | [rbac_policy.csv](https://github.com/casbin/casbin/blob/master/examples/rbac_policy.csv) | +| RBAC with resource roles | [rbac_with_resource_roles_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_with_resource_roles_model.conf) | [rbac_with_resource_roles_policy.csv](https://github.com/casbin/casbin/blob/master/examples/rbac_with_resource_roles_policy.csv) | +| RBAC with domains/tenants | [rbac_with_domains_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_with_domains_model.conf) | [rbac_with_domains_policy.csv](https://github.com/casbin/casbin/blob/master/examples/rbac_with_domains_policy.csv) | +| ABAC | [abac_model.conf](https://github.com/casbin/casbin/blob/master/examples/abac_model.conf) | N/A | +| RESTful | [keymatch_model.conf](https://github.com/casbin/casbin/blob/master/examples/keymatch_model.conf) | [keymatch_policy.csv](https://github.com/casbin/casbin/blob/master/examples/keymatch_policy.csv) | +| Deny-override | [rbac_with_not_deny_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_with_not_deny_model.conf) | [rbac_with_deny_policy.csv](https://github.com/casbin/casbin/blob/master/examples/rbac_with_deny_policy.csv) | +| Allow-and-deny | [rbac_with_deny_model.conf](https://github.com/casbin/casbin/blob/master/examples/rbac_with_deny_model.conf) | [rbac_with_deny_policy.csv](https://github.com/casbin/casbin/blob/master/examples/rbac_with_deny_policy.csv) | +| Priority | [priority_model.conf](https://github.com/casbin/casbin/blob/master/examples/priority_model.conf) | [priority_policy.csv](https://github.com/casbin/casbin/blob/master/examples/priority_policy.csv) | diff --git a/website/translated_docs/uk-UA/SyntaxForModels.md b/website/translated_docs/uk-UA/SyntaxForModels.md new file mode 100644 index 00000000..055b8f0a --- /dev/null +++ b/website/translated_docs/uk-UA/SyntaxForModels.md @@ -0,0 +1,121 @@ +--- +id: syntax-for-models +title: Syntax for Models +--- + +- A model CONF should have at least four sections: `[request_definition], [policy_definition], [policy_effect], [matchers]`. + +- If a model uses RBAC, it should also add the `[role_definition]` section. + +- A model CONF can contain comments. The comments start with `#`, and `#` will comment the rest of the line. + +## Request definition + +`[request_definition]` is the definition for the access request. It defines the arguments in `e.Enforce(...)` function. + +```ini +[request_definition] +r = sub, obj, act +``` + +`sub, obj, act` represents the classic triple: accessing entity (Subject), accessed resource (Object) and the access method (Action). However, you can customize your own request form, like `sub, act` if you don't need to specify an particular resource, or `sub, sub2, obj, act` if you somehow have two accessing entities. + +## Policy definition + +`[policy_definition]` is the definition for the policy. It defines the meaning of the policy. For example, we have the following model: + +```ini +[policy_definition] +p = sub, obj, act +p2 = sub, act +``` + +And we have the following policy (if in a policy file) + +``` +p, alice, data1, read +p2, bob, write-all-objects +``` + +Each line in a policy is called a policy rule. Each policy rule starts with a `policy type`, e.g., `p`, `p2`. It is used to match the policy definition if there are multiple definitions. The above policy shows the following binding. The binding can be used in the matcher. + +``` +(alice, data1, read) -> (p.sub, p.obj, p.act) +(bob, write-all-objects) -> (p2.sub, p2.act) +``` + +:::note Currently only single policy definition `p` is supported. `p2` is yet not supported. Because for common cases, our user doesn't have the need to use multiple policy definitions. If your requirement has to use additional policy definitions, please send an issue about it. ::: + +:::tip The elements in a policy rule are always regarded as`string`. If you have any question about this, please see the discussion at: https://github.com/casbin/casbin/issues/113 ::: + +## Policy effect + +`[policy_effect]` is the definition for the policy effect. It defines whether the access request should be approved if multiple policy rules match the request. For example, one rule permits and the other denies. + +```ini +[policy_effect] +e = some(where (p.eft == allow)) +``` + +The above policy effect means if there's any matched policy rule of `allow`, the final effect is `allow` (aka allow-override). `p.eft` is the effect for a policy, it can be `allow` or `deny`. It's optional and the default value is `allow`. So as we didn't specify it above, it uses the default value. + +Another example for policy effect is: + +```ini +[policy_effect] +e = !some(where (p.eft == deny)) +``` + +It means if there's no matched policy rules of`deny`, the final effect is `allow` (aka deny-override). `some` means: if there exists one matched policy rule. `any` means: all matched policy rules (not used here). The policy effect can even be connected with logic expressions: + +```ini +[policy_effect] +e = some(where (p.eft == allow)) && !some(where (p.eft == deny)) +``` + +It means at least one matched policy rule of`allow`, and there is no matched policy rule of`deny`. So in this way, both the allow and deny authorizations are supported, and the deny overrides. + +:::note Although we designed the syntax of policy effect as above, the current implementations only use hard-coded policy effect, as we found there's no much need for that sort of flexibility. So for now, you must use one of the built-in policy effects instead of customizing your own one. ::: + +The supported built-in policy effects are: + +| Policy effect | Meaning | Example | +| ------------------------------------------------------------ | -------------- | ----------------------------------------------------- | +| some(where (p.eft == allow)) | allow-override | [ACL, RBAC, etc.](/docs/en/supported-models#examples) | +| !some(where (p.eft == deny)) | deny-override | [Deny-override](/docs/en/supported-models#examples) | +| some(where (p.eft == allow)) && !some(where (p.eft == deny)) | allow-and-deny | [Allow-and-deny](/docs/en/supported-models#examples) | +| priority(p.eft) || deny | priority | [Priority](/docs/en/supported-models#examples) | + +## Matchers + +`[matchers]` is the definition for policy matchers. The matchers are expressions. It defines how the policy rules are evaluated against the request. + +```ini +[matchers] +m = r.sub == p.sub && r.obj == p.obj && r.act == p.act +``` + +The above matcher is the simplest, it means that the subject, object and action in a request should match the ones in a policy rule. + +You can use arithmetic like `+, -, *, /` and logical operators like `&&, ||, !` in matchers. + +:::note Although it seems like there will be multiple matchers such as `m1`, `m2` like other primitives, currently, we only support one matcher `m`. You can always use the above logical operators to implement complicated logic judgment in one matcher. So we believe there is no need to support multiple matchers for now. Let me know if you have other opinions. ::: + +### Expression evaluator + +The matcher evaluation in Casbin is implemented by expression evaluators in each language. Casbin integrates their powers to provide the unified PERM language. Besides all the model syntax provided here, those expression evaluators may provide extra functionality, which may be not supported by another language or implementation. Use it at your own risk. + +The expression evaluators used by each Casbin implementation are: + +| Implementation | Language | Expression evaluator | +| -------------- | -------- | -------------------------------------------------------------------------------------------------- | +| Casbin | Golang | https://github.com/Knetic/govaluate | +| jCasbin | Java | https://github.com/killme2008/aviator | +| Node-Casbin | Node.js | https://github.com/donmccurdy/expression-eval | +| PHP-Casbin | PHP | https://github.com/symfony/expression-language | +| PyCasbin | Python | https://github.com/danthedeckie/simpleeval | +| Casbin.NET | C# | https://github.com/davideicardi/DynamicExpresso | +| Casbin4D | Delphi | https://github.com/casbin4d/Casbin4D/tree/master/SourceCode/Common/Third%20Party/TExpressionParser | +| casbin-rs | Rust | https://github.com/jonathandturner/rhai | + +:::note If you encounter performance issue about Casbin, it's probably caused by the low efficiency of the expression evaluator. You can both send issue to Casbin or the expression evaluator directly for advice to speed up. See [Benchmarks](/docs/en/benchmark) section for details. ::: diff --git a/website/translated_docs/uk-UA/TermsOfService.md b/website/translated_docs/uk-UA/TermsOfService.md new file mode 100644 index 00000000..9200d7ec --- /dev/null +++ b/website/translated_docs/uk-UA/TermsOfService.md @@ -0,0 +1,46 @@ +--- +id: terms-of-service +title: Terms of Service +--- + +1. Terms + +By accessing the website at https://casbin.org, you are agreeing to be bound by these terms of service, all applicable laws and regulations, and agree that you are responsible for compliance with any applicable local laws. If you do not agree with any of these terms, you are prohibited from using or accessing this site. The materials contained in this website are protected by applicable copyright and trademark law. + +2. Use License + +a. Permission is granted to temporarily download one copy of the materials (information or software) on Casbin's website for personal, non-commercial transitory viewing only. This is the grant of a license, not a transfer of title, and under this license you may not: + +- i. modify or copy the materials; +- ii. use the materials for any commercial purpose, or for any public display (commercial or non-commercial); +- iii. attempt to decompile or reverse engineer any software contained on Casbin's website; +- iv. remove any copyright or other proprietary notations from the materials; or +- v. transfer the materials to another person or "mirror" the materials on any other server. + +b. This license shall automatically terminate if you violate any of these restrictions and may be terminated by Casbin at any time. Upon terminating your viewing of these materials or upon the termination of this license, you must destroy any downloaded materials in your possession whether in electronic or printed format. + +3. Disclaimer + +a. The materials on Casbin's website are provided on an 'as is' basis. Casbin makes no warranties, expressed or implied, and hereby disclaims and negates all other warranties including, without limitation, implied warranties or conditions of merchantability, fitness for a particular purpose, or non-infringement of intellectual property or other violation of rights. + +b. Further, Casbin does not warrant or make any representations concerning the accuracy, likely results, or reliability of the use of the materials on its website or otherwise relating to such materials or on any sites linked to this site. + +4. Limitations + +In no event shall Casbin or its suppliers be liable for any damages (including, without limitation, damages for loss of data or profit, or due to business interruption) arising out of the use or inability to use the materials on Casbin's website, even if Casbin or a Casbin authorized representative has been notified orally or in writing of the possibility of such damage. Because some jurisdictions do not allow limitations on implied warranties, or limitations of liability for consequential or incidental damages, these limitations may not apply to you. + +5. Accuracy of materials + +The materials appearing on Casbin's website could include technical, typographical, or photographic errors. Casbin does not warrant that any of the materials on its website are accurate, complete or current. Casbin may make changes to the materials contained on its website at any time without notice. However Casbin does not make any commitment to update the materials. + +6. Links + +Casbin has not reviewed all of the sites linked to its website and is not responsible for the contents of any such linked site. The inclusion of any link does not imply endorsement by Casbin of the site. Use of any such linked website is at the user's own risk. + +7. Modifications + +Casbin may revise these terms of service for its website at any time without notice. By using this website you are agreeing to be bound by the then current version of these terms of service. + +8. Governing Law + +These terms and conditions are governed by and construed in accordance with the laws of San Francisco, CA and you irrevocably submit to the exclusive jurisdiction of the courts in that State or location. diff --git a/website/translated_docs/uk-UA/Tutorial.md b/website/translated_docs/uk-UA/Tutorial.md new file mode 100644 index 00000000..a02dc184 --- /dev/null +++ b/website/translated_docs/uk-UA/Tutorial.md @@ -0,0 +1,143 @@ +--- +id: tutorials +title: Tutorials +--- + +Some tutorials are for the Casbin's model and work for all Casbin implementations in different languages. Some other tutorials are language-specific. + +### Our Papers + +- [PML: An Interpreter-Based Access Control Policy Language for Web Services](https://arxiv.org/abs/1903.09756) + +This paper digs deeply into the design details about Casbin. Please cite the following BibTex if you use Casbin/PML as a reference in your paper: + +```bibtex +@article{luo2019pml, + title={PML: An Interpreter-Based Access Control Policy Language for Web Services}, + author={Luo, Yang and Shen, Qingni and Wu, Zhonghai}, + journal={arXiv preprint arXiv:1903.09756}, + year={2019} +} +``` + +- [Access Control Policy Specification Language Based on Metamodel (in Chinese)](http://www.jos.org.cn/1000-9825/5624.htm) + +This is another longer-version paper published in Journal of Software. The citation for different formats (Refworks, EndNote, etc.) can be found at: https://kns.cnki.net/kcms/detail/Detail.aspx?dbname=CJFDLAST2020&filename=RJXB202002012&v= + +### Videos + +- [A Secure Vault - implementing authorization middleware with Casbin - JuniorDevSG](https://www.youtube.com/watch?v=OTT84oplR9o) +- [Sharing user permissions in a micro-service architecture based on Casbin (in Russian)](https://www.youtube.com/watch?v=Z5dUxH4PqYM) +- [Nest.js - Casbin RESTful RBAC authorization midleware](https://www.youtube.com/watch?v=mWlPNrCgVdE) +- [Gin Tutorial Chapter 10: Learn Casbin basic models in 30 minutes](https://www.bilibili.com/video/BV1qz4y167XP) +- [Gin Tutorial Chapter 11: Coding, API and custom function in Casbin](https://www.bilibili.com/video/BV13r4y1M7AC) +- [Gin + Casbin: Learning Permissions in Action (in Chinese)](https://www.jtthink.com/course/132) +- [jCasbin Basics: A simple RBAC example (in Chinese)](https://www.jtthink.com/course/play/2706) +- [Golang's RBAC based on Casbin (in Chinese)](https://www.bilibili.com/video/BV1Kf4y1U7iJ) +- [Learning Gin + Casbin (1): Opening & Overview (in Chinese)](https://www.bilibili.com/video/BV1bp4y1a7je) +- [ThinkPHP 5.1 + Casbin: Introduction (in Chinese)](https://www.bilibili.com/video/BV1kz4y1Z7vd) +- [ThinkPHP 5.1 + Casbin: RBAC authorization (in Chinese)](https://www.bilibili.com/video/BV1A541187M4) +- [ThinkPHP 5.1 + Casbin: RESTful & Middleware (in Chinese)](https://www.bilibili.com/video/BV1uk4y117up) +- [Quick Start for PHP-Casbin (in Chinese)](https://www.bilibili.com/video/BV1dK4y1L7xy) + +### PERM Meta-Model (Policy, Effect, Request, Matchers) + +- [Modeling Authorization with PERM in Casbin](https://vicarie.in/posts/generalized-authz.html) +- [Designing a Flexible Permissions System with Casbin](https://medium.com/silo-blog/designing-a-flexible-permissions-system-with-casbin-f5d97fef17b8) +- [Access control with PERM and Casbin (in Persian)](https://vrgl.ir/npwoy) +- [RBAC? ABAC? .. PERM! New Way of Authorization for Cloud-Based Web Services and Apps (in Russian)](https://habr.com/ru/post/539778/) +- [Practice & Examples of Flexible Authorization Using Casbin & PERM (in Russian)](https://habr.com/ru/post/540454/) +- [Permission management with Casbin (in Chinese)](http://www.cnblogs.com/wang_yb/archive/2018/11/20/9987397.html) +- [Analysis of Casbin (in Chinese)](https://www.cnblogs.com/xiaohunshi/p/10372881.html) +- [Design of System Permissions (in Chinese)](https://github.com/xizhibei/blog/issues/101) +- [Casbin: A Permission Engine (in Chinese)](https://github.com/xizhibei/blog/issues/102) +- [Implementing ABAC with Casbin (in Chinese)](https://www.cnblogs.com/studyzy/p/11380736.html) +- [Source code analysis of Casbin (in Chinese)](https://www.cnblogs.com/yjf512/p/12200206.html) +- [Permission evaluation with Casbin (in Chinese)](https://cloud.tencent.com/developer/article/1534674) +- [Casbin: Library of the day for Go (in Chinese)](https://juejin.im/post/5ee6c93ce51d45787d3484a1) + + + + + +### HTTP & RESTful + +- [Basic Role-Based HTTP Authorization in Go with Casbin](https://zupzup.org/casbin-http-role-auth) (or [Chinese translation](https://studygolang.com/articles/12323)) + +### Beego + +- [Using Casbin with Beego: 1. Get started and test (in Chinese)](https://blog.csdn.net/hotqin888/article/details/78460385) +- [Using Casbin with Beego: 2. Policy storage (in Chinese)](https://blog.csdn.net/hotqin888/article/details/78571240) +- [Using Casbin with Beego: 3. Policy query (in Chinese)](https://blog.csdn.net/hotqin888/article/details/78992250) +- [Using Casbin with Beego: 4. Policy update (in Chinese)](https://blog.csdn.net/hotqin888/article/details/80032538) +- [Using Casbin with Beego: 5. Policy update (continued) (in Chinese)](https://blog.csdn.net/hotqin888/article/details/80092285) + +### Gin + +- [Tutorial: Integrate Gin with Cabsin](https://dev.to/maxwellhertz/tutorial-integrate-gin-with-cabsin-56m0) +- [Policy enforcements on K8s with Pipeline](https://banzaicloud.com/blog/policy-enforcement-k8s/) +- [Authentication and authorization in Gin application with JWT and Casbin](https://medium.com/@tienbm90/authentication-and-authorization-in-gin-application-with-jwt-and-casbin-a56bbbdec90b) +- [Backend API with Go: 1. Authentication based on JWT (in Chinese)](https://studygolang.com/topics/6998) +- [Backend API with Go: 2. Authorization based on Casbin (in Chinese)](https://studygolang.com/topics/6999) +- [Using Go's authorization library Casbin with Gin and GORM (in Japanese)](https://www.zaneli.com/blog/20181203) + +### Echo + +- [Web authorization with Casbin](http://klotzandrew.com/blog/authorization-with-casbin) + +### Iris + +- [Iris + Casbin: Practice for permission management (in Chinese)](https://zxc0328.github.io/2018/05/14/casbin-iris/) +- [Role-based access control for HTTP based on Casbin (in Chinese)](https://studyiris.com/example/exper/casbin.html) +- [Learning iris + Casbin from scratch](https://learnku.com/articles/41416) + +### VMware Harbor + +- [Casbin: Golang access control framework (in Chinese)](http://www.growingdev.com/articles/2020/01/12/1578838858526.html) +- [Access control in Harbor (in Chinese)](http://www.growingdev.com/articles/2020/01/10/1578670203670.html) + +### Argo CD + +- [Organizational RBAC in Argo CD with Casbin](https://argoproj.github.io/argo-cd/operator-manual/rbac/) + +### GShark + +- [GShark: Scan for sensitive information in Github easily and effectively (in Chinese)](https://mp.weixin.qq.com/s?__biz=MzI3MjA3MTY3Mw==&mid=2247483770&idx=1&sn=9f02c2803e1c946e8c23b16ff3eba757&chksm=eb396fecdc4ee6fa2f378e846f354f45acf6e6f540cfd54190e9353df47c7707e3a2aadf714f&token=115330850&lang=zh_CN#rd) + + + +### SprintBoot + +- [jCasbin: a more light-weight permission management solution (in Chinese)](https://blog.csdn.net/waynelee0809/article/details/85702551) +- [Integrating jCasbin with JFinal (in Chinese)](http://www.jfinal.com/share/842) + + + +### Express + +- [How to Add Role-Based-Access-Control to Your Serverless HTTP API on AWS](https://dev.to/matttyler/how-to-add-role-based-access-control-to-your-serverless-http-api-on-aws-17bk) + +### Nest + +- [How to Create Role based Authorization Middleware with Casbin and Nest.js](https://dev.to/dwipr/how-to-create-role-based-authorization-middleware-with-casbin-and-nest-js-52gm) +- [nest.js: Casbin RESTful RBAC authorization middleware (Video)](https://www.youtube.com/watch?v=mWlPNrCgVdE) +- [A Demo App of Attribute-based Access Control in Node.js Based on Casbin](https://github.com/Jarvie8176/casbin-example) +- [Multi tenant SaaS starter kit with cqrs graphql microservice architecture](https://github.com/juicycleff/ultimate-backend) + +### Fastify + +- [Access Control in Node.js with Fastify and Casbin](https://www.nearform.com/blog/access-control-node-js-fastify-and-casbin/) + + + +- [Casbin, Powerful and Efficient ACL for Your Projects](http://phpmagazine.net/2018/11/casbin-powerful-and-efficient-acl-for-your-projects.html) + +### Laravel + +- [Laravel authorization: authorization library supporting ACL, RBAC, ABAC and other models](https://developpaper.com/laravel-authorization-authorization-library-supporting-acl-rbac-abac-and-other-models/) + + + +- [Basic Role-Based HTTP Authorization in Rust with Casbin](https://www.zupzup.org/rust-casbin-example/) + + diff --git a/website/translated_docs/uk-UA/Watchers.md b/website/translated_docs/uk-UA/Watchers.md new file mode 100644 index 00000000..c3ad271e --- /dev/null +++ b/website/translated_docs/uk-UA/Watchers.md @@ -0,0 +1,49 @@ +--- +id: watchers +title: Watchers +--- + +We support to use distributed messaging systems like [etcd](https://github.com/coreos/etcd) to keep consistence between multiple Casbin enforcer instances. So our users can concurrently use multiple Casbin enforcers to handle large number of permission checking requests. + +Similar to policy storage adapters, we don't put watcher code in the main library. Any support for a new messaging system should be implemented as a watcher. A complete list of Casbin watchers is provided as below. Any 3rd-party contribution on a new watcher is welcomed, please inform us and I will put it in this list:) + + + + +| Watcher | Type | Author | Description | +| ------------------------------------------------------------------------------------------------------------------ | ---------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| [Etcd Watcher](https://github.com/casbin/etcd-watcher) | KV store | Casbin | Watcher for [etcd](https://github.com/coreos/etcd) | +| [NATS Watcher](https://github.com/Soluto/casbin-nats-watcher) | Messaging system | [Soluto](https://github.com/Soluto) | Watcher for [NATS](https://nats.io/) | +| [ZooKeeper Watcher](https://github.com/grepsr/casbin-zk-watcher) | KV store | [Grepsr](https://github.com/grepsr) | Watcher for [Apache ZooKeeper](https://zookeeper.apache.org/) | +| [Redis Watcher](https://github.com/billcobbler/casbin-redis-watcher) | KV store | [@billcobbler](https://github.com/billcobbler) | Watcher for [Redis](http://redis.io/) | +| [NATS, RabbitMQ, GCP Pub/Sub, AWS SNS & SQS, Kafka, InMemory](https://github.com/rusenask/casbin-go-cloud-watcher) | Messaging System | [rusenask](https://github.com/rusenask/) | Watcher based on [Go Cloud Dev Kit](https://gocloud.dev/) that works with leading cloud providers and self-hosted infrastructure | + + +| Watcher | Type | Author | Description | +| ---------------------------------------------------------- | -------- | ------------------------------------------ | -------------------------------------------------- | +| [Etcd Adapter](https://github.com/mapleafgo/jcasbin-extra) | KV store | [@mapleafgo](https://github.com/mapleafgo) | Watcher for [etcd](https://github.com/coreos/etcd) | + + +| Watcher | Type | Author | Description | +| ----------------------------------------------------------------- | ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------ | +| [Etcd Watcher](https://github.com/node-casbin/etcd-watcher) | KV store | Casbin | Watcher for [etcd](https://github.com/coreos/etcd) | +| [Redis Watcher](https://github.com/node-casbin/redis-watcher) | KV store | Casbin | Watcher for [Redis](http://redis.io/) | +| [Pub/Sub Watcher](https://github.com/node-casbin/pubsub-watcher) | Messaging system | Casbin | Watcher for [Google Cloud Pub/Sub](https://cloud.google.com/pubsub/docs) | +| [Postgres Watcher](https://github.com/mcollina/casbin-pg-watcher) | Database | [Matteo Collina](https://github.com/mcollina/) | Watcher for [PostgreSQL](https://www.postgresql.org/) | + + +| Watcher | Type | Author | Description | +| --------------------------------------------------------------------------- | -------- | ----------------------------------------------- | ----------------------------------------------------- | +| [Redis Watcher](https://github.com/ScienceLogic/flask-casbin-redis-watcher) | KV store | [ScienceLogic](https://github.com/ScienceLogic) | Watcher for [Redis](http://redis.io/) | +| [PostgreSQL Watcher](https://github.com/pycasbin/postgresql-watcher) | Database | Casbin | Watcher for [PostgreSQL](https://www.postgresql.org/) | + + +| Watcher | Type | Author | Description | +| ----------------------------------------------------------------- | -------- | -------------------------------- | ------------------------------------- | +| [Redis Watcher](https://github.com/Sbou/Casbin.NET-Redis-Watcher) | KV store | [@Sbou](https://github.com/Sbou) | Watcher for [Redis](http://redis.io/) | + + + +## WatcherEx + +In order to support incremental synchronization between multiple instances, we provide the `WatcherEx` interface. We hope it can notify other instances when the policy changes, but there is currently no implementation of `WatcherEx`. We recommend that you use dispatcher to achieve this. diff --git a/website/translated_docs/uk-UA/WebpageController.md b/website/translated_docs/uk-UA/WebpageController.md new file mode 100644 index 00000000..1bc184c3 --- /dev/null +++ b/website/translated_docs/uk-UA/WebpageController.md @@ -0,0 +1,133 @@ +--- +id: frontend +title: Frontend Usage +--- + +[Casbin.js](https://github.com/casbin/casbin.js) is a Casbin addon that facilites your access-control management in the frontend application. + + +## Installation + +``` +npm install casbin.js +``` +or +``` +yarn add casbin.js +``` + +## Quick Start +You can use `manual` mode in your frontend application, and set the permission whenever you wish: +```Javascript +const casbinjs = require("casbin.js"); + +// Set the user's permission: +// He/She can read `data1` and `data2` objects and can write `data1` object +const permission = { + "read": ["data1", "data2"], + "write": ["data1"] +} + +// Run casbin.js in manual mode, which requires you to set the permission manually. +const authorizer = new casbinjs.Authorizer("manual"); + +authorizer.setPermission(permission); +console.log(authorizer.can("read", "data1")); // True +console.log(authorizer.cannot("write", "data2")); // True +``` + +You can refer to our [React example](https://github.com/casbin-js/examples) to see a practical usage of Casbin.js + + + + + + + +## Advanced Usage + +Casbin.js provides a perfect solution to integrating your frontend access-control management with your backend Casbin service. + + +Use `auto` mode and specify your endpoint when initializing the Casbin.js `Authorizer`, it will automatically sync the permission and manipulate the frontend status. + +```Javascript +const casbinjs = require('casbin.js'); + +// Set your backend casbin service url +const authorizer = new casbinjs.Authorizer( + 'auto', // mode + {endpoint: 'http://your_endpoint/api/casbin'} +); + +// Set your visitor. +// Casbin.js will automatically sync the permission with your backend Casbin service. +authorizer.setUser("Tom"); + +// Evaluate the permission +if authorizer.can("read", "data1") { + // Some frontend procedure ... +} +``` + +Correspondingly, you need to expose an interface (e.g. a RestAPI) to generate the permission object and pass it to the frontend. In your API controller, call `CasbinJsGetUserPermission` to construct the permission object. Here is an example in Beego: + +```Go +// Router +beego.Router("api/casbin", &controllers.APIController{}, "GET:GetFrontendPermission") + +// Controller +func (c *APIController) GetFrontendPermission() { + // Get the visitor from the GET parameters. (The key is "casbin_subject") + visitor := c.Input().Get("casbin_subject") + // `e` is an initialized instance of Casbin Enforcer + c.Data["perm"] = casbin.CasbinJsGetPermissionForUser(e, visitor) + // Pass the data to the fronend. + c.ServeJSON() +} +``` + +:::note Currently, `CasbinJsGetPermissionForUser` api is only supported in Go Casbin and Node-Casbin. If you want this api to be supported in other languages, please [raise an issue](https://github.com/casbin/casbin.js/issues) or leave a comment below. ::: + + +## API List + +#### `setPermission(permission: string)` +Set the permission object. Always used in `manual` mode. + +#### `setUser(user: string)` +Set the visitor identity and update the permission. Always used in `auto` mode. + +#### `can(action: string, object: string)` +Check if the user can perform `action` on `object`. + +#### `cannot(action: string, object: string)` +Check if the user **cannot** perform `action` on `object`. + +#### `canAll(action: string, objects: Array)` +Check if the user can perform `action` on **all** object in `objects`. + +#### `canAny(action: string, objects: Array)` +Check if the user can perform `action` on **any one** of the `objects`. + + +## Why Casbin.js + +People may wonder the difference between Node-Casbin and Casbin.js. In a word, Node-Casbin is the core of Casbin implemented in NodeJS environment, and it's normally used as an access-controlling management toolkit at the server ends. Casbin.js is an frontend library that help you use Casbin to authorize your webpage user at the client side. + +Normally, it is not proper to directly build up a Casbin service and do the authorization/enforcement tasks at a web frontend application due to the following problems: +1. When someone turn on the client, the enforcer will be initialized, and it will pull all the policies from the backend persistent layers. A high concurrency could bring tough pressure on the databases and cost a lot of network throughput.  +2. Loading all policies to the client sides could bring secure risks. +3. Difficult for the seperation between client and server as well as the agile development. + +We wish a tool that eases the process of using Casbin at the frontend. Actually, the core of Casbin.js is the manipulation of current user's permission at the client side. As you mentioned, Casbin.js does a fetch from a specified endpoint. This procedure will sync the permission of the user with the backend Casbin service. After having the permission data, developers can use Casbin.js interfaces to manage the behaviors of the user at the frontend side. + +Casbin.js avoid the two problems that mentioned above: Casbin service will no longer be pulled up repeatedly, and the size of passing messages between the client and the server are reduced. We also avoid to store all the policies at the frontend. User can only accessible to his own permission, but have no idea about anything about things like the access-control model and other users' permissions. Besides, Casbin.js can also efficiently decouple the client and the server in authorization management.