XSwitch认证鉴权接口
XSwitch支持通过API方式访问。根据安装部署方式的不同,可以使用不同的鉴权方式。
- 不鉴权:访问任何接口无需鉴权,适用于开发环境,以及可信的内部环境
- HTTP Basic:可以使用HTTP Basic方式鉴权
- HTTP Digest:未实现
- Session/Token方式
本文讨论基于Session/Token的认证方式。
通过认证API拿到Token后,即可携带Token访问有权限认证的接口。
约定
本文档中,使用$var
格式表示需要用户输入的值,如在如下URL中:
GET /api/users/$user_id
在实例使时使用真正的用户
GET /api/users/1
Session/Token认证
HTTP是无状态的,系统后台使用Sesison保存会话数据(如登录用户的ID、过期时间等),前后台使用Token或Cookie标志一个Session。
Session在后台有多种存储方式:
file
:文件存储,可以将文件删除强制Session过期。hash
:内在哈希表存储,在系统重启后过期。也可以在运行时手工删除对应的Key强制过期。redis
:Redis存储,可以支持Session自动过期。
Cookie/Token过期机制及过期时间设置:
有效期设置:缺省过期时间为24小时,可通过修改配置文件
xtra.config.lua
的config.session_expires
参数进行修改,如config.session_expires = 3600 * 12
,单位为秒。过期机制:
普通Token:
- 用户通过HTTP POST api/sessions接口申请到Token后,Token的有效使用时长就是由上述参数指定,即Token的有效期 = Token申请时间 + config.session_expires。在Token有效期内,用户可以通过HTTP RESET API接口来访问系统资源,Token过了有效期后,HTTP请求将返回
403
,这个时候需要用户调用接口重新申请Token。
- 用户通过HTTP POST api/sessions接口申请到Token后,Token的有效使用时长就是由上述参数指定,即Token的有效期 = Token申请时间 + config.session_expires。在Token有效期内,用户可以通过HTTP RESET API接口来访问系统资源,Token过了有效期后,HTTP请求将返回
用户开发key:
- 普通的Token有过期机制,因此在开发调试阶段对用户来说不太方便,因此我们提供了用户开发Key,用户可以在XUI Web上申请属于某个用户的Key,这个Key可以作为HTTP资源请求的Token使用,而且是永久有效的,等调试完毕,不用此Key的时候,直接在页面删除即可,详见后续开发Key。
XUI Web Cookie:Cookie的有效期设置和Http接口是同一参数配置,但两者的有效期机制却大不同。Cookie的有效期计算的是XUI Web两次请求的最大间隔时间,也就是只要在
config.session_expires
指定的时间范围内收到Web请求,那Cookie永远不会过期,否则将返回403。
登录
使用用户名密码获取Token。默认Token是一个UUID字符串,可以通过jwt=true
参数请求一个JWT格式的Token。后台也可以通过配置强制产生JWT格式的Token。
如果开启了图形验证码,在最开始调用api/session
时,无须图形验证码,当密码输入错误2次,则需要先获取验证码,然后根据账号、密码、验证码再次获取token,当输入错误5次后则锁定获取接口,2小时之内不可获取token。
如果Token使用了JWT Token,则Token过期时,无需再使用户名和密码申请新的Token,而是使用refresh_token来申请新的Token,每次申请新的Token时,接口都会返回refresh_token,用于下次申请Token的令牌验证。当然如果refresh_token过期了,那只能通过用户名和密码申请Token,refresh_token的有效期长与Token的有效期。
请求URL
POST /api/sessions
请求Header
参数 | 必选 | 类型 | 备注 |
---|---|---|---|
Content-Type | 是 | string | application/json 或 application/x-www-form-urlencoded |
请求Body
参数 | 必选 | 类型 | 备注 |
---|---|---|---|
login | 是 | string | 用户名 |
password | 是 | string | 密码 |
jwt | 否 | string | 是否返回JWT Token |
jwt
:true|false
,字符串类型,在JSON格式中也可以使用布尔型
返回值
正常返回一个JSON Object。
code
:结果代码token
:string,可用作Token (X-XTRA-AUTH-ID)expires
:int,UNIX时间戳,过期时间user_id
:用户IDextn
:默认分机号
如果出错,返回HTTP状态码如403
(用户名/密码错)500
(内部错误)等。
示例
产生一个Token:
curl -XPOST -d 'login=1007&password=$VeryGoodPassw0rd' localhost:8081/api/sessions
{
"user_id": 9,
"expires": 1666999916,
"code": 200,
"currentAuthority": "user",
"token": "1ad58209-6fa7-4758-90da-cdff8bb79a62",
"extn": "1007",
"system_roles": {
"senior_roles_str": "()",
"roles_str": "()"
}
}
产生一个JWT Token:
curl -XPOST -d 'login=1007&password=1234&jwt=true' localhost:8081/api/sessions
{
"token": "ewoJImFsZyI6CSJIUzI1NiIsCgkidHlwIjoJIkpXVCIKfQ.ewoJInVzZXJfaWQiOgk5LAoJImV4cGlyZXMiOgkxNjY1NjM4NjA2Cn0.qCYBAE5p9AW3mDHTjm817F9LnBRLX9QoH3dYktukkg4",
"user_id": 9,
"expires": 1665637770,
"code": 200,
"currentAuthority": "user",
"extn": "1007"
}
图形验证码
生成验证码
调用如下接口生成验证码
GET /api/captchas
根据验证码id获取图片
GET /api/captchas/1
修改Body值
请求Body
参数 | 必选 | 类型 | 备注 |
---|---|---|---|
login | 是 | string | 用户名 |
password | 是 | string | 密码 |
captcha_str | 是 | string | 图形验证码 |
POST /api/sessions
其它说明
首先,用用户名和密码获取一个Token,参数的提交方式有两种,一种是基于URL字符串(www-form-urlencoded
),如:
curl -XPOST -d 'login=1007&password=$VeryGoodPassw0rd' 192.168.1.100:8081/api/sessions
也可以提交一个JSON请求,如:
curl -XPOST -d '{"login": "1007", "password": "$VeryGoodPassw0rd"}' \
-H "Content-Type: application/json" 192.168.1.100:8081/api/sessions
返回:
- 成功:
{"code": 200, "token": "319a18e6-98e0-4b7e-b2f1-10d85d4a1d3d"}
- 失败:
{code = 403, text = "Wrong username or password"}
后续所有的请求(包括注销)都需要使用该Token。如:
curl -H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" 192.168.1.100:8081/api/users
也可以使用更为通用的 Authorization: Bearer $Token
的方式传递 Token。如:
curl -H "Authorization: Bearer 62dd0173-4916-4b1c-b958-546e4d7c91fe" 192.168.1.100:8081/api/users
也可以将该Key加入到Cookie中,如:
freeswitch_xtra_session_id=62dd0173-4916-4b1c-b958-546e4d7c91fe
如上所见,Token与Cookie是通用的,所以,在Web界面上获取到的Cookie,也可以直接在API中使用,直到Cookie失效。
注销
请求URL
DELETE /api/sessions
返回值
正常返回一个Object。
返回字段 | 必选 | 类型 | 备注 |
---|---|---|---|
code | 是 | int | 结果码 |
text | 是 | string | 描述字符串 |
示例
curl -XDELETE -H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" 192.168.1.100:8081/api/sessions
返回:
- 成功:状态码:
200
,Body:{"code":200, "text":"OK"}
- 失败:状态码:
500
,Body:空
开发Key
通过/api/sessions
获取到的Token是临时的,在系统重启后会失效。有时候,对于一些后台任务或需要长期Token的场景,可以使用开发Key进行身份验证。
使用Web方式获取开发Key
用户登录后可以在用户详情界面上生成开发key,申请后永久有效。当然申请后还可以查询和删除。
通过API创建开发key
用于API客户端创建申请某一服务器的开发key,申请完永久有效。得到的Key可以直接做为上一节中的Token使用。
默认情况下URL中的user_id
部分需要填入自己的ID,admin
可以填入其它用户的ID以便为其它用户生成开发Key。
请求URL
POST http://host:port/api/users/$user_id/dev_keys
请求Header
参数 | 必选 | 类型 | 备注 |
---|---|---|---|
Content-Type | 是 | string | application/json |
X-XTRA-AUTH-ID | 是 | string | 合法的Token |
请求Body
参数 | 必选 | 类型 | 备注 |
---|---|---|---|
description | 否 | string | 开发Key的用途描述信息 |
返回值
返回字段 | 必选 | 类型 | 备注 |
---|---|---|---|
code | 是 | int | 状态码 |
message | 是 | string | 状态描述 |
data | 是 | object | 开发Key数据 |
data对象:
k
:string,开发Key。enabled
:数字字符串,是否启用。
状态码定义
状态码 | 描述 |
---|---|
200 | 成功 |
403 | 用户名或密码错 |
406 | 缺少参数 |
500 | 服务端错误 |
示例
- curl例子:
curl -0 -H "X-XTRA-AUTH-ID: 1234" --data \
'{"description": "我的第一个测试用的开发Key"}' \
-XPOST 192.168.1.100:8081/api/users/dev_keys
- 返回:
{
"data": {
"description": "我的第一个测试用的开发Key",
"updated_at": "2019-08-07 20:27:07",
"k": "5bdd2cdd-fc64-47b1-b40e-f578d48b6d82",
"deleted_at": "",
"id": "20",
"user_id": "35",
"enabled": "1",
"created_at": "2019-08-07 20:27:07"
},
"code": 200,
"message": "success"
}
删除开发key
用户API客户端删除自己的开发key。
请求URL
DELETE http://host:port/api/users/$user_id/dev_keys
请求HEADER
参数 | 必选 | 类型 | 备注 |
---|---|---|---|
Content-Type | 是 | string | application/json |
X-XTRA-AUTH-ID | 是 | string | 合法的Token值 |
返回值
返回字段 | 必选 | 类型 | 备注 |
---|---|---|---|
code | 是 | int | 状态码 |
text | 是 | string | 状态描述 |
状态码定义
状态码 | 描述 |
---|---|
200 | success |
403 | Wrong Auth Id |
406 | Missing Args |
500 | service error |
示例
- curl例子:
curl -0 -H "Content-Type: application/json" \
-H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" \
-XDELETE 192.168.1.100:8081/api/users/100/dev_keys
- 返回:
{
"code": 0,
"text": "sucess"
}
查询开发key
用于API客户端查询自己的开发key列表。
请求URL
POST http://host:port/api/users/1/dev_keys
请求HEADER
参数 | 必选 | 类型 | 备注 |
---|---|---|---|
Content-Type | 是 | string | application/json |
X-XTRA-AUTH-ID | 是 | string | key值 |
返回值说明
返回字段 | 必选 | 类型 | 备注 |
---|---|---|---|
code | 是 | int | 状态码 |
message | 是 | string | 状态描述 |
data | 是 | object | Key数据 |
状态码定义
状态码 | 描述 |
---|---|
200 | success |
403 | Wrong Auth Id |
406 | Missing Args |
500 | service error |
示例
- curl例子:
curl -0 -H "Content-Type: application/json" -GET \
-H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" \
192.168.1.100:8081/api/users/1/dev_keys
- 返回:
{
"message": "success",
"data": [{
"created_at": "2019-08-06 20:13:06",
"key": "62dd0173-4916-4b1c-b958-546e4d7c91fe",
"id": "2",
"description": "我的第一个测试用的开发Key",
"user_id": 35,
"enabled": 1,
"deleted_at": "",
"updated_at": "2019-08-06 20:13:06"
}, {
"created_at": "2019-08-06 21:03:15",
"key": "a09a4f9f-afc5-4eb9-bc32-db5fc4c75c7f",
"id": "9",
"description": "我的第二个Key",
"user_id": 35,
"enabled": 0,
"deleted_at": "",
"updated_at": "2019-08-06 21:03:15"
}],
"code": 200
}
分机Token
在分机需要使用Token登录的情况下,如在使用WebRTC发起呼叫等,可以产生分机Token。
URL
POST /api/users/extn_token
请求HEADER
参数 | 必选 | 类型 | 备注 |
---|---|---|---|
Content-Type | 是 | string | application/json 或 application/x-www-form-urlencoded |
X-XTRA-AUTH-ID | 是 | string | 用户Token |
请求内容
extn
:string,分机号domain
:string,域
返回值说明
extn_id
:string,分机IDtoken
:string,Tokendomain
:分机所属的域
示例:
curl -H "X-XTRA-AUTH-ID: 4835b4c6-d4a1-4532-8d7a-d5e68de5261f" \
-d extn=admin localhost:8081/api/sessions/extn_token
{
"extn_id": "1",
"token": "e0e36c89-5326-4cb5-a63e-de5f291b77fa",
"domain": "seven.local"
}
也可以使用用户的JWT Token来请求分机的Token 示例:
curl -H "X-XTRA-AUTH-ID: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX3V1aWQiOiIyNjU4ZjljYy1hOTg1LTQ4NTktYTUwZC0xODdkYmEwMDkzNGMiLCJleHBpcmVzIjoxNjcxODIyMjI0LCJ1c2VybmFtZSI6IjEwMDciLCJ1c2VyX2lkIjo4LCJsb2dpbiI6IjEwMDdAeHN3aXRjaC5jbiIsInVzZXJfZG9tYWluIjoieHN3aXRjaC5jbiIsImxhc3RfdGltZSI6MTY3MTc2NDYyNH0.0AvgYJikG055xxPDllC58hKriN3TMvLGYYweS35Z3bc" \
-d 'extn=1007' localhost:8081/api/sessions/extn_token
如果分机也需要获取JWT Token,可以再请求中加上参数jwt=true
示例:
curl -H "X-XTRA-AUTH-ID: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX3V1aWQiOiIyNjU4ZjljYy1hOTg1LTQ4NTktYTUwZC0xODdkYmEwMDkzNGMiLCJleHBpcmVzIjoxNjcxODIyMjI0LCJ1c2VybmFtZSI6IjEwMDciLCJ1c2VyX2lkIjo4LCJsb2dpbiI6IjEwMDdAeHN3aXRjaC5jbiIsInVzZXJfZG9tYWluIjoieHN3aXRjaC5jbiIsImxhc3RfdGltZSI6MTY3MTc2NDYyNH0.0AvgYJikG055xxPDllC58hKriN3TMvLGYYweS35Z3bc" \
-d 'extn=1007&jwt=true' localhost:8081/api/sessions/extn_token
Websocket
Websocket认证地址是/ws
,在建立连接后进行认证。文档见JSON API相关文档。
Websocket可以使用用户Token也可以使用分机Token登录。
调试
在hash
方式的Session存储中,可以使用以下命令查看
hash select/xui/$token