跳到主内容

Casdoor 公共 API

Casdoor 前端网页用户界面是一个用 React 开发的SPA（单页应用程序）。 React前端使用了Go后端代码暴露的Casdoor RESTful API。 这个RESTful API被称为Casdoor Public API。 换句话说，通过HTTP调用，你可以像Casdoor网页界面本身一样做任何事情。 没有其他限制。 以下人员可以利用该API：

  • Casdoor的前端
  • Casdoor 客户端 SDK（例如，casdoor-go-sdk）
  • 来自应用程序一侧的任何其他自定义代码

Casdoor Public API的完整参考可以在Swagger上找到：https://door.casdoor.com/swagger。 这些Swagger文档是使用Beego的Bee工具自动生成的。 如果你想要自己生成Swagger文档，请参见：如何生成swagger文件

如何使用Casdoor Public API进行身份验证​

1. 通过Access token​

我们可以使用为经过身份验证的用户授予的访问令牌，以用户自身的身份调用Casdoor Public API。

如何获取访问令牌？​

应用程序可以在OAuth登录过程结束时（也就是通过代码和状态获取令牌）获取Casdoor用户的访问令牌。 API调用的权限将与用户的权限相同。

以下示例展示了如何通过casdoor-go-sdk在Go中调用GetOAuthToken()函数。

func (c *ApiController) Signin() {
    code := c.Input().Get("code")
    state := c.Input().Get("state")

    token, err := casdoorsdk.GetOAuthToken(code, state)
    if err != nil {
        c.ResponseError(err.Error())
        return
    }

    claims, err := casdoorsdk.ParseJwtToken(token.AccessToken)
    if err != nil {
        c.ResponseError(err.Error())
        return
    }

    if !claims.IsAdmin {
        claims.Type = "chat-user"
    }

    err = c.addInitialChat(&claims.User)
    if err != nil {
        c.ResponseError(err.Error())
        return
    }

    claims.AccessToken = token.AccessToken
    c.SetSessionClaims(claims)

    c.ResponseOk(claims)
}

所有授予的访问令牌也可以通过管理员用户在Tokens页面上的web UI进行访问。 例如，访问：https://door.casdoor.com/tokens 以查看演示站点。

如何进行身份验证？​

  1. HTTP GET 参数，其URL格式为：

    /page?access_token=<访问令牌>

    演示站点示例：https://door.casdoor.com/api/get-global-providers?access_token=eyJhbGciOiJSUzI1NiIs

  2. HTTP Bearer令牌，HTTP头格式是：

    Authorization: Bearer <访问令牌>

2. 通过Client ID和Client secret​

如何获取客户端ID和密钥？​

应用程序编辑页面（例如，https://door.casdoor.com/applications/casbin/app-vue-python-example）将显示应用程序的客户端ID和密钥。 当你想要以"机器"、"应用程序"或"服务"的身份而不是用户的身份调用API时，这种认证是有用的。 API 调用的权限将与应用程序（也就是组织的管理员）的权限相同。

以下示例展示了如何通过casdoor-go-sdk在Go中调用GetOAuthToken()函数。

如何进行身份验证？​

  1. HTTP GET 参数，其URL格式为：

    /page?clientId=<客户端ID>&clientSecret=<客户端密钥>

    演示站点示例：https://door.casdoor.com/api/get-global-providers?clientId=294b09fbc17f95daf2fe&clientSecret=dd8982f7046ccba1bbd7851d5c1ece4e52bf039d

  2. HTTP 基本认证，其HTTP头格式为：

    Authorization: Basic <客户端ID和客户端密钥以单个冒号":"连接的Base64编码>

如果你不熟悉Base64编码，你可以使用一个库来完成这个任务，因为HTTP Basic Authentication是一个被许多地方支持的流行标准。

3. 通过Access key和Access secret​

我们可以使用Casdoor用户的访问密钥和访问秘密来调用Casdoor Public API作为用户本身。 访问密钥和访问秘密可以由管理员或用户本人在用户设置页面中配置。 update-user API也可以被调用来更新这些字段。 API 调用的权限将与用户的权限相同。

如何进行身份验证？​

  1. Create a pair of accessKey and accessSecret in account setting page.

  2. HTTP GET 参数，其URL格式为：

    /page?accessKey=<The user's access key>&accessSecret=<the user's access secret>"

演示站点示例：https://door.casdoor.com/api/get-global-providers?accessKey=b86db9dc-6bd7-4997-935c-af480dd2c796/admin&accessSecret=79911517-fc36-4093-b115-65a9741f6b14

User Api Key

curl --location 'http://door.casdoor.com/api/user?accessKey=b86db9dc-6bd7-4997-935c-af480dd2c796&accessSecret=79911517-fc36-4093-b115-65a9741f6b14'

4. 通过username和password​

注意事项

这种认证方法并不安全，仅为了兼容性或演示目的而保留在此。 我们建议使用前三种身份验证方法。

会发生什么？​

用户凭证将会以GET参数的形式在请求URL中暴露出来。 此外，如果你使用的是HTTP而不是HTTPS，用户的凭证将会被网络以明文形式嗅探。

我们可以使用Casdoor用户的用户名和密码来以用户自身的身份调用Casdoor Public API。 用户名采用的格式为<用户的组织名称>/<用户名>。 API调用的权限将与用户相同。

如何进行身份验证？​

  1. HTTP GET参数，URL格式为：

    /page?username=<用户的组织名称>/<用户名>&password=<用户的密码>"

演示站点示例：https://door.casdoor.com/api/get-global-providers?username=built-in/admin&password=123