casbin_auth

casbin_auth

A base auth go web project combined with casbin open-source authorization library.

项目说明

项目代码中支持两种用户状态鉴权机制,分别是beego内置的session机制和目前比较流行的token机制.配置文件中如果设置sessionon为开启,则系统默认会使用cookie-session机制, 否则使用token模式, token模式一方面可以避免用户禁用token的情景, 另一方面也可以避免集群环境下session失效的情况. 项目中不论是session还是token模式均采取了reids 作为存储引擎, 因此在session模式下,即使重启了服务器只要cookie中携带的sessionID还未失效,则session信息依然可以获取到,无需重新登录.

运行项目步骤

• 修改conf/app.conf中数据库连接信息
• 配置conf/app.conf中是否开启session
• 安装并启动redis,如果redis为远程服务,则需要根据实际情况修改连接redis配置
• 在项目根目录下新建logs文件夹,里面存放一些日志文件,github上忽略上传需要自己来建

casbin_auth Api接口文档使用说明

1.1 版本历史

1.2 文档介绍

  本文档的接口遵循RESTful设计风格

1.3 全局响应状态码说明

1.4 Auth模块

1.4.1 登录

  基于session或者token的机制来实现用户登录

注意事项：如果用户在app.conf中开启了sessionOn = true，则使用session机制，否则使用token。

1.4.1.1 请求URL

http://localhost:8080/v1/api/auth/user/login

1.4.1.2 请求方式

POST

1.4.1.3 请求Headers参数

说明：如果是token模式的话，请求Headers中必须包含token参数键值对，否则需要开启cookie。

1.4.1.4 请求Body参数

请求示例：

{
    "username": "admin",
    "password": "123456"
}

1.4.1.5 响应Response参数

响应示例：

{
    "err_code": 0,
    "err_message": "OK",
    "payload": {
        "user_id": 1,
        "token": "gx7KDTNEA26lFcLGHaP0o645aLhe49gP"
    }
}

1.4.1.6 响应状态码说明

1.4.2 注册

  根据请求参数注册一个新用户，用户名不能重复

1.4.2.1 请求URL

http://localhost:8080/v1/api/auth/user/register

1.4.2.2 请求方式

POST

1.4.2.3 请求Headers参数

说明：如果是token模式的话，请求Headers中必须包含token参数键值对，否则需要开启cookie。

1.4.2.4 请求Body参数

请求示例：

{
    "username": "qiangjiyi",
    "password": "123456",
    "real_name": "真实姓名",
    "mobile": "18611876729",
    "email": "qiangjiyi@163.com"
}

1.4.2.5 响应Response参数

响应示例：

{
    "err_code": 0,
    "err_message": "OK",
    "payload": {
        "user_id": 1,
        "username": "qiangjiyi",
        "create_time": "2019-01-31 16:43:23"
    }
}

1.4.2.6 响应状态码说明

1.4.3 退出

  移除当前登录用户会话信息

1.4.3.1 请求URL

http://localhost:8080/v1/api/auth/user/logout

1.4.3.2 请求方式

GET

1.4.3.3 请求Headers参数

说明：如果是token模式的话，请求Headers中必须包含token参数键值对，否则需要开启cookie。

1.4.3.4 响应Response参数

响应示例：

{
    "err_code": 0,
    "err_message": "OK"
}

1.4.3.5 响应状态码说明

1.4.4 更新用户

  根据请求参数更新用户资料

1.4.4.1 请求URL

http://localhost:8080/v1/api/auth/user/update

1.4.4.2 请求方式

POST

1.4.4.3 请求Headers参数

说明：如果是token模式的话，请求Headers中必须包含token参数键值对，否则需要开启cookie。

1.4.4.4 请求Body参数

请求示例：

{
    "id": 1,
    "username": "qiangjiyi1",
    "password": "123456789",
    "real_name": "真实姓名xxx",
    "mobile": "18611876729",
    "email": "1473430734@qq.com"
}

1.4.4.5 响应Response参数

响应示例：

{
    "err_code": 0,
    "err_message": "OK",
    "payload": {
        "user_id": 1,
        "username": "qiangjiyi1",
        "update_time": "2019-01-31 17:00:37"
    }
}

1.4.4.6 响应状态码说明

1.4.5 删除用户

  根据请求参数删除对应的用户

1.4.5.1 请求URL

http://localhost:8080/v1/api/auth/user/delete/1

1.4.5.2 请求方式

GET

1.4.5.3 请求Headers参数

说明：如果是token模式的话，请求Headers中必须包含token参数键值对，否则需要开启cookie。

1.4.5.4 响应Response参数

响应示例：

{
    "err_code": 0,
    "err_message": "OK"
}

1.4.5.5 响应状态码说明

1.4.6 创建角色

  根据请求参数新建一个角色

1.4.6.1 请求URL

http://localhost:8080/v1/api/auth/role/create

1.4.6.2 请求方式

POST

1.4.6.3 请求Headers参数

说明：如果是token模式的话，请求Headers中必须包含token参数键值对，否则需要开启cookie。

1.4.6.4 请求Body参数

请求示例：

{
    "role_name": "admin",
    "description": "管理员"
}

1.4.6.5 响应Response参数

响应示例：

{
    "err_code": 0,
    "err_message": "OK",
    "payload": {
        "id": 15,
        "role_name": "admin",
        "description": "管理员",
        "create_time": "2019-01-31 17:12:29"
    }
}

1.4.6.6 响应状态码说明

1.4.7 更新角色

  根据请求参数更新指定的角色信息

1.4.7.1 请求URL

http://localhost:8080/v1/api/auth/role/update

1.4.7.2 请求方式

POST

1.4.7.3 请求Headers参数

说明：如果是token模式的话，请求Headers中必须包含token参数键值对，否则需要开启cookie。

1.4.7.4 请求Body参数

请求示例：

{
    "id": 1,
    "role_name": "system_admin",
    "description": "系统管理员"
}

1.4.7.5 响应Response参数

响应示例：

{
    "err_code": 0,
    "err_message": "OK",
    "payload": {
        "id": 1,
        "role_name": "system_admin",
        "description": "系统管理员",
        "update_time": "2019-01-31 17:18:01"
    }
}

1.4.7.6 响应状态码说明

1.4.8 删除角色

  根据请求参数删除指定的角色信息

1.4.8.1 请求URL

http://localhost:8080/v1/api/auth/role/delete/1

1.4.8.2 请求方式

GET

1.4.8.3 请求Headers参数

说明：如果是token模式的话，请求Headers中必须包含token参数键值对，否则需要开启cookie。

1.4.8.4 响应Response参数

响应示例：

{
    "err_code": 0,
    "err_message": "OK"
}

1.4.8.5 响应状态码说明

1.4.9 添加权限

  根据请求参数添加权限信息

1.4.9.1 请求URL

http://localhost:8080/v1/api/auth/permission/add

1.4.9.2 请求方式

POST

1.4.9.3 请求Headers参数

说明：如果是token模式的话，请求Headers中必须包含token参数键值对，否则需要开启cookie。

1.4.9.4 请求Body参数

说明：如果type为g，则说明添加的是权限组，那么sub_type如果为u，则sub为用户名，否则sub_type为r，则sub为角色ID，而obj此时必须为角色ID；如果type为p，则说明添加的是普通的权限，sub_type和sub的值跟type为g时要求类似，只是obj此时就是我们要访问的restful api地址，action为我们要访问该api地址的请求方式。

请求示例：

{
    "type": "g",
    "sub": "qiangjiyi",
    "sub_type": "u",
    "obj": "1",
    "action": "GET"
}

1.4.9.5 响应Response参数

响应示例：

{
    "err_code": 0,
    "err_message": "OK",
    "payload": {
        "policy": "g, 2, role_1"
    }
}

1.4.9.6 响应状态码说明

1.4.10 查询用户的角色和权限

  根据请求参数查询指定用户的所有角色和权限信息

1.4.10.1 请求URL

http://localhost:8080/v1/api/auth/permission/query/1

1.4.10.2 请求方式

GET

1.4.10.3 请求Headers参数

说明：如果是token模式的话，请求Headers中必须包含token参数键值对，否则需要开启cookie。

1.4.10.4 响应Response参数

响应示例：

{
    "err_code": 0,
    "err_message": "OK",
    "payload": {
        "user_id": 2,
        "username": "qiangjiyi",
        "real_name": "强吉义",
        "mobile": "18611876729",
        "email": "qiangjiyi@163.com",
        "role_list": [
            {
                "id": 5,
                "role_name": "组织管理员",
                "description": "作为一个组织内部的管理员",
                "update_time": "2019-01-21 20:18:55"
            },
            {
                "id": 2,
                "role_name": "角色name",
                "description": "角色description",
                "update_time": "2019-01-23 16:24:48"
            },
            {
                "id": 3,
                "role_name": "新角色name",
                "description": "新角色description",
                "update_time": "2019-01-29 11:11:48"
            }
        ],
        "permission_list": [
            "2,/v1/api/auth/permission/add,POST",
            "2,/v1/api/auth/role/delete/*,GET",
            "2,/v1/api/auth/role/delete/:roleId,GET",
            "role_3,/v2/api/auth/permission/query,GET"
        ]
    }
}

1.4.10.5 响应状态码说明

写在最后

通过以上的接口文档,相信有过go web开发经验的朋友们应该可以将该项目run起来,该部分代码是我之前做的一个比较通用的用户角色权限模块,最近才决定抽取并开源出来,不足之处也希望大家能够指正. 如果在使用过程中遇到问题,可以单独与我交流.