Panda-api接口权限Auth配置说明

一个系统,通常会涉及不同的权限和用户角色,每一种角色对接口的的权限是不一样的,或者对同一个接口地址的请求方法GETPOSTPUTDELETE的权限也会有不同,Panda Api在设计的时候很好的兼容了这些情况。下面我们用例子来进行说明:

首先,在我们的项目接口文档目录的根目录下创建_auth.json5文件,该文件和_settings.json5在同一级目录。

注意: 只有接口文档中auth:true的情况下,Panda Api才会对接口进行权限验证,如果auth:false,那么会跳过auth验证。你可以在接口文档中设置,也可以在_settings.json5中进行全局开启,然后在不需要权限验证的接口的地方再单独关闭。例如:

// _settings.json5
{
  project_name: "Panda Api",
  project_desc: "Panda api is a simple api manage tool",
  global: {
    apis: {
      auth: true
    }
  }
}

我们先写一个最简单的权限配置,超级管理员,拥有所有接口的权限配置。编辑_auth.json5文件:

// _auth.json5
{
    name: "用户认证接口文档",
    desc: "相关auth认证说明,token生成规则及相关说明",
    auth_type:"Bearer", // Authentication type, default is Bearer
    auth_place:"headers", // Add authorization data to headers, body, query. default is heaeders
    no_perm_response: {
        code: -1,
        msg: "没有权限非法操作"
    },
    // 没有权限的或者没有token的就返回 no_perem_response中的内容
    groups:[ // 表示拥有不同权限的用户组列表
    {
        name: "超级管理员",
        desc: "拥有全部的权限",
        users:[ // 拥有权限的用户列表
        {
            id:1,
            username:"root",
            password:"123321",
            token:"9)N2Ck*~nB1tMj3le7dstcX3ymfM3LqB6y!Kk!NZlg91(st&EY~etZN1()vU",
        }
        ],
        no_perms:[["/admin/user/", "DELETE"]], // 表示没有权限的列表,没有权限列表优先
        has_perms:["*"], // *星号表示拥有所有接口的全部权限
        no_perm_response: {
            code: -1,
            msg: "没有用户删除的权限"
        }
    }
    ]
}

这个文档表示:用户root,token是9)N2Ck*~nB1tMj3le7dstcX3ymfM3LqB6y!Kk!NZlg91(st&EY~etZN1()vU,他拥有全部的接口访问权限,除了/admin/user/这个接口的DELETE请求方法。

auth_type

表示Authentication类型,默认是Bearer

auth_place

表示token放的位置,可以放到headers,body或者query,默认是headers

no_perm_response

表示没有权限时返回的错误内容,可以在根节点,全局设置一个,然后所有groups列表中的权限都会继承,groups中的权限也可以重写自己的no_perm_response,如果都没有设置,系统在遇到没有权限的时候,会返回:

{
    "code":-1,
    "error":"no perm to visit"
}

groups

表示拥有各种不同权限的用户组列表

groups的元素中,name表示用户组的名称,desc表示对这个用户组及拥有权限的说明,

users这个用户组拥有哪些用户,用户里面的字段是可以根据需要任意设置的(比如登录需要用户名和密码;手机号;OpenID等),但是一定要有token字段,表示这个用户的auth token

no_perms

表示这个用户组的用户对哪些接口没有权限,这个权限是优先于has_perms,也就是这只在这里的权限,就算has_perms里面设置了有权限也无效。

has_perms

表示这个用户组的用户对哪些接口有权限,

权限的写法

no_perms和has_perms的权限写法是一样的,他们有这些写法:

当你直接写一个字符串的url地址的时候,默认表示拥有了所有请求方法权限。比如例子中:/admin/settings/的完整写法其实是:has_perms:[["/admin/settings/", "*"]]

当你用数组表示的时候,第一个元素表示请求地址,后面的所有元素表示这个地址包含的请求方法。

你还可以使用第三种写法:

has_perms:[
    {
        url: "/admin/user/",
        methods:["DELETE", "GET", "POST"]
    },
    {
        url: "/admin/post/",
        methods:["POST"]
    },
    {
        url: "/admin/news/",
        methods:["*"]
    }
]

以接口文档作为权限加载

因为如果要一个接口一个接口的写,可能会导致工作量很大,而且有的接口文档的接口地址还在不停的修改,所以又设计了直接以接口文档为加载。例如:

has_perms:["$article.json5", ["$auth.json5", "GET", "POST"], {$ref:"manage.json5", methods:["GET", "POST", "DELETE"], $exclude:["/user/list/", ["/user/", "DELETE"]]}],
no_perms:[["/admin/user/", "DELETE"]],

has_perms表示:

no_perms 表示出了/admin/user/DELETE权限没有

$英文的美元符号后面,跟的是接口文件的相对地址。

创建token

当你用很多用户组权限,也有很多用户,你可能无法自己编出很多的符合前后端约定的token,Panda api的命令提供了token生成的简单方法。

这里以mac下安装好Panda api举例,在shell中执行命令panda token,默认创建10个长度为64的token

Prw$nMQT5~du8DF$#grOtosaFIQ!WeOTK@2(tZlep9ZX1lNK%PHINam8jsAz
~L2L59xX@gy*!vAVeOH*%0ImNdF9^1(5QL4~BgcRFPsSvfe$4iCTEq8GWABa
H~p~!wWLHjUFPLj0Uu4W3wZ#H!4%4)*zjZd*y$Dq4Yg*sdtI7jEgfG&o2gG$
63ugo3y6g^NAgM(nrZlhwXmabW#w6l&O&3#r^9uTz1Ep&Ox7DyxVx&AH10An
!7A7HE!0~yTbgK3qvzZksUgsRAfPeezBqGP0L$$bC!@WtQt)MFJuQv937m~!
rvD5VbW($bvh8M3ci5Nq!^C1Aotu4gCn(j$)(*wQisLXIAigUM9zNQk5S^I0
FlI$SvZEdfsb2whh6r0F%gbYPZ3EyP!xzpTWvVfc#h4FYStYse4BNjC%8b)^
cKT8Nd76z!%6Iq0hN(Ac^83UCru%#vVT~zK&aldWJ1*1Phi#hdj2LG8K1m~a
PxtKs9YgbaZbiWtolsK8xIizeJKaYfg$pJL7Jz1p54RTHi!R4&9NVjn6uyjo
xUtBNQIlp(Jd04p$%COM0g*q0yiP$l*~ah^WkKwlqTONQ0#Z9u#FWF!QmueS

意思是生成长度为60的10个token,每一行是一个。60可以改为你想要的token长度。默认每次生成10个,如果想要更多个:

panda token -n 20 -l 128

生成20个 长度是 128 的token。n num 的默认长度是10, l length的默认长度是64,祥见panda token –help

未来这里会和jwt生成算法进行结合。

请求有权限认证的接口

当我们配置好了权限接口,请求的时候,就必须使用users中某一个用户的token去访问接口,并且token必须放到约定的地方,比如请求头中,接口才会成功,否则就会返回no_perm_response中的错误信息。

2020-02-16 11:07

留言