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.luaconfig.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。
    • 用户开发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-Typestringapplication/jsonapplication/x-www-form-urlencoded

请求Body

参数必选类型备注
loginstring用户名
passwordstring密码
jwtstring是否返回JWT Token
  • jwttrue|false,字符串类型,在JSON格式中也可以使用布尔型

返回值

正常返回一个JSON Object。

  • code:结果代码
  • token:string,可用作Token (X-XTRA-AUTH-ID)
  • expires:int,UNIX时间戳,过期时间
  • user_id:用户ID
  • extn:默认分机号

如果出错,返回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

参数必选类型备注
loginstring用户名
passwordstring密码
captcha_strstring图形验证码

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。

返回字段必选类型备注
codeint结果码
textstring描述字符串

示例

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-Typestringapplication/json
X-XTRA-AUTH-IDstring合法的Token

请求Body

参数必选类型备注
descriptionstring开发Key的用途描述信息

返回值

返回字段必选类型备注
codeint状态码
messagestring状态描述
dataobject开发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-Typestringapplication/json
X-XTRA-AUTH-IDstring合法的Token值

返回值

返回字段必选类型备注
codeint状态码
textstring状态描述

状态码定义

状态码描述
200success
403Wrong Auth Id
406Missing Args
500service 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-Typestringapplication/json
X-XTRA-AUTH-IDstringkey值

返回值说明

返回字段必选类型备注
codeint状态码
messagestring状态描述
dataobjectKey数据

状态码定义

状态码描述
200success
403Wrong Auth Id
406Missing Args
500service 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-Typestringapplication/jsonapplication/x-www-form-urlencoded
X-XTRA-AUTH-IDstring用户Token

请求内容

  • extn:string,分机号
  • domain:string,域

返回值说明

  • extn_id:string,分机ID
  • token:string,Token
  • domain:分机所属的域

示例:

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