跳到主内容

开放的 Casbin API

介绍​

假设你的应用程序的前端已经获取了已登录用户的access_token，现在想要对用户进行一些访问的认证。 你不能简单地将access_token放入HTTP请求头来使用这些API，因为Casdoor使用Authorization字段来检查访问权限。 像Casdoor提供的其他API一样，Authorization字段由应用客户端id和密钥组成，使用基本的HTTP认证方案。 它看起来像Authorization: Basic <Your_Application_ClientId> <Your_Application_ClientSecret>。 因此，Casbin API 应当被应用的后端服务器调用。 以下是如何操作的步骤。

以演示站点中的app-vue-python-example应用为例，授权头应该是：Authorization: Basic 294b09fbc17f95daf2fe dd8982f7046ccba1bbd7851d5c1ece4e52bf039d。

  1. 前端通过HTTP请求头将access_token传递给后端服务器。
  2. 后端服务器从access_token中检索用户id。

提前说明，这些接口也是为(sub, obj, act)模型设计的（目前）。 正文是由Casbin模型定义的权限请求格式，通常分别代表sub、obj和act。

除了请求强制执行权限控制的 API 接口以外，Casdoor 也提供了其它一些有助于外部应用获取权限策略信息的接口，也一并列在此处。

Enforce​

The Enforce API supports multiple query parameters to specify which permission(s) to enforce against. Only one parameter should be provided at a time:

  • permissionId: The identity of a specific permission policy (format: organization name/permission name)
  • modelId: The identity of a permission model (format: organization name/model name) - enforces against all permissions using this model
  • resourceId: The identity of a resource - enforces against all permissions for this resource
  • enforcerId: The identity of a specific enforcer
  • owner: The organization name - enforces against all permissions in this organization

Request using permissionId:

curl --location --request POST 'http://localhost:8000/api/enforce?permissionId=example-org/example-permission' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Your_Application_ClientId> <Your_Application_ClientSecret>' \
--data-raw '["example-org/example-user", "example-resource", "example-action"]'

Request using modelId:

curl --location --request POST 'http://localhost:8000/api/enforce?modelId=example-org/example-model' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Your_Application_ClientId> <Your_Application_ClientSecret>' \
--data-raw '["example-org/example-user", "example-resource", "example-action"]'

Request using resourceId:

curl --location --request POST 'http://localhost:8000/api/enforce?resourceId=example-org/example-resource' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Your_Application_ClientId> <Your_Application_ClientSecret>' \
--data-raw '["example-org/example-user", "example-resource", "example-action"]'

Response:

{
    "status": "ok",
    "msg": "",
    "sub": "",
    "name": "",
    "data": [
        true
    ],
    "data2": [
        "example-org/example-model/example-adapter"
    ]
}

Note: When using modelId, resourceId, enforcerId, or owner parameters, the response data array may contain multiple boolean values (one for each permission that was checked), and data2 contains the corresponding model and adapter identifiers.

BatchEnforce​

The BatchEnforce API supports multiple query parameters to specify which permission(s) to enforce against. Only one parameter should be provided at a time:

  • permissionId: The identity of a specific permission policy (format: organization name/permission name)
  • modelId: The identity of a permission model (format: organization name/model name) - enforces against all permissions using this model
  • enforcerId: The identity of a specific enforcer
  • owner: The organization name - enforces against all permissions in this organization

Request using permissionId:

curl --location --request POST 'http://localhost:8000/api/batch-enforce?permissionId=example-org/example-permission' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Your_Application_ClientId> <Your_Application_ClientSecret>' \
--data-raw '[["example-org/example-user", "example-resource", "example-action"], ["example-org/example-user2", "example-resource", "example-action"], ["example-org/example-user3", "example-resource", "example-action"]]

Request using modelId:

curl --location --request POST 'http://localhost:8000/api/batch-enforce?modelId=example-org/example-model' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Your_Application_ClientId> <Your_Application_ClientSecret>' \
--data-raw '[["example-org/example-user", "example-resource", "example-action"], ["example-org/example-user2", "example-resource", "example-action"]]'

响应：

{
    "status": "ok",
    "msg": "",
    "sub": "",
    "name": "",
    "data": [
        [
            true,
            true,
            false
        ]
    ],
    "data2": [
        "example-org/example-model/example-adapter"
    ]
}

Note: When using modelId, enforcerId, or owner parameters, the response data array may contain multiple arrays of boolean values (one array for each permission that was checked), and data2 contains the corresponding model and adapter identifiers.

GetAllObjects​

This API retrieves all objects (resources) that a user has access to. It accepts an optional userId parameter. If not provided, it uses the logged-in user's session.

Request with userId parameter:

curl --location --request GET 'http://localhost:8000/api/get-all-objects?userId=example-org/example-user' \
--header 'Authorization: Basic <Your_Application_ClientId> <Your_Application_ClientSecret>'

Request using session (userId determined from session):

curl --location --request GET 'http://localhost:8000/api/get-all-objects' \
--header 'Authorization: Basic <Your_Application_ClientId> <Your_Application_ClientSecret>'

响应：

{
    "status": "ok",
    "msg": "",
    "data": [
        "app-built-in",
        "example-resource"
    ]
}

GetAllActions​

This API retrieves all actions that a user can perform. It accepts an optional userId parameter. If not provided, it uses the logged-in user's session.

Request with userId parameter:

curl --location --request GET 'http://localhost:8000/api/get-all-actions?userId=example-org/example-user' \
--header 'Authorization: Basic <Your_Application_ClientId> <Your_Application_ClientSecret>'

Request using session (userId determined from session):

curl --location --request GET 'http://localhost:8000/api/get-all-actions' \
--header 'Authorization: Basic <Your_Application_ClientId> <Your_Application_ClientSecret>'

响应：

{
    "status": "ok",
    "msg": "",
    "data": [
        "read",
        "write",
        "admin"
    ]
}

GetAllRoles​

This API retrieves all roles assigned to a user. It accepts an optional userId parameter. If not provided, it uses the logged-in user's session.

Request with userId parameter:

curl --location --request GET 'http://localhost:8000/api/get-all-roles?userId=example-org/example-user' \
--header 'Authorization: Basic <Your_Application_ClientId> <Your_Application_ClientSecret>'

Request using session (userId determined from session):

curl --location --request GET 'http://localhost:8000/api/get-all-roles' \
--header 'Authorization: Basic <Your_Application_ClientId> <Your_Application_ClientSecret>'

响应：

{
    "status": "ok",
    "msg": "",
    "data": [
        "role_kcx66l"
    ]
}

RunCasbinCommand​

This API executes Casbin CLI commands and returns their output. It's designed for running language-specific Casbin command-line tools through Casdoor's backend, supporting languages like Java, Go, Node.js, Python, and others.

The API includes an in-memory cache that stores command results for 5 minutes. When the same command is executed with identical parameters, the cached result is returned immediately without re-executing the command, improving response times and reducing server load.

Request:

curl --location --request GET 'http://localhost:8000/api/run-casbin-command?language=go&args=["-v"]' \
--header 'Authorization: Basic <Your_Application_ClientId> <Your_Application_ClientSecret>'

Parameters:

  • language: The programming language for the Casbin CLI (e.g., go, java, node, python)
  • args: A JSON-encoded array of command-line arguments (e.g., ["-v"] for version, ["new"] for creating new files). Note: URL-encode the JSON array when using it as a query parameter

Response:

{
    "status": "ok",
    "msg": "",
    "data": "casbin version 2.x.x"
}

The cache key is generated from the language and arguments, so different commands are cached independently. Expired entries are automatically cleaned up to prevent memory growth.