Skip to content

casbin/casbin-server

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Casbin Server

GitHub Actions Docker Docker Image Version (latest by date) Coverage Status Godoc

Casbin Server is the Access Control as a Service (ACaaS) solution based on Casbin. It provides gRPC interface for Casbin authorization.

What is Casbin Server?

Casbin-Server is just a container of Casbin enforcers and adapters. Casbin-Server performs the policy enforcement check, which may take a fair amount of processing depending on the model and number of policies, interfacing to external data stores such as databases for policy data. Just like how native Casbin library works, each Casbin enforcer in Casbin-Server can use its own adapter, which is linked with external database for policy storage.

Of course, you can setup Casbin-Server together with your policy database in the same machine. But they can be separated. If you want to achieve high availability, you can use a Redis cluster as policy storage, then link Casbin-Server's adapter with it. In this sense, Casbin enforcer can be viewed as stateless component. It just retrieves the policy rules it is interested in (via sharding), does some computation and then returns allow or deny.

Architecture

Casbin-Server uses the client-server architecture. Casbin-Server itself is the server (in Golang only for now). The clients for Casbin-Server are listed here:

Language Author Client
Golang Casbin https://github.com/casbin/casbin-go-client
Java Accept008 https://github.com/Accept008/grpc-client
PHP Casbin https://github.com/php-casbin/casbin-client
Python @prathik-kaliyambath https://github.com/prathik-kaliyambath/casbin-python-client

Contributions for clients in other languages are welcome :)

Prerequisites

Protobuf (if not installed):

As Casbin-Server uses gRPC, you need to install Protocol Buffers first to generate the .proto file. The command is:

protoc -I proto --go_out=plugins=grpc:proto proto/casbin.proto

Alternatively, you can also run it from an IDE.

Installation

go get github.com/casbin/casbin-server

Database Support

Similar to Casbin, Casbin-Server also uses adapters to provide policy storage. However, because Casbin-Server is a service instead of a library, the adapters have to be implemented inside Casbin-Server. As Golang is a static language, each adapter requires to import 3rd-party library for that database. We cannot import all those 3rd-party libraries inside Casbin-Server's code, as it causes dependency overhead.

For now, only Gorm Adapter is built-in with mssql, mysql, postgres imports all commented. If you want to use Gorm Adapter with one of those databases, you should uncomment that import line, or add your own import, or even use another adapter by modifying Casbin-Server's source code.

To allow Casbin-Server to be production-ready, the adapter configuration supports environment variables. For example, assume we created a postgres database for our RBAC model and want Casbin-Server to use it. Assuming that the environment in which the Casbin-Server runs contains the necessary variables, we can simply use the $ENV_VAR notation to provide these to the adapter.

{
  "driver": "postgres",
  "connection": "host=$DB_HOST port=$DB_PORT user=$DB_USERNAME dbname=$DB_NAME password=$DB_PASSWORD",
  "enforcer": "examples/rbac_policy.csv",
  "dbSpecified" : true
}

The connection config file path can also be set using the environment variable CONNECTION_CONFIG_PATH. If this variable is not set, connection config is read from the path "config/connection_config.json".

Docker Way

docker run -id -p 50051:50051 --name my-casbin-server casbin/casbin-server

If you want to define your own connection file

docker run -id -p 50051:50051 \
-e CONNECTION_CONFIG_PATH=/data/connection_config.json \
-v ${your local file path}:/data \
--name my-casbin-server \
-d casbin/casbin-server

If you want to build your own image

docker build -f ./Dockerfile -t my-casbin-server-image .

Limitation of ABAC

Casbin-Server also supports the ABAC model as the Casbin library does. You may wonder how Casbin-Server passes the Go structs to the server-side via network? Good question. In fact, Casbin-Server's client dumps Go struct into JSON and transmits the JSON string prefixed by ABAC:: to Casbin-Server. Casbin-Server will recognize the prefix and load the JSON string into a pre-defined Go struct with 11 string members, then pass it to Casbin. So there will be several limitations for Casbin-Server's ABAC compared to Casbin's ABAC:

  1. The Go struct should be flat, all members should be primitive types, e.g., string, int, boolean. No nested struct, no slice or map.

  2. All members should be public (first letter capitalized).

  3. The Go struct is limited to 11 members at most. If you want to have more members, you should modify Casbin-Server's source code by adding more members and rebuild it.

Getting Help

License

This project is under Apache 2.0 License. See the LICENSE file for the full license text.