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

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。

  • 用户开发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的有效期。

POST /api/sessions

• jwt：true|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

GET /api/captchas/1

请求Body

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失效。

DELETE /api/sessions

正常返回一个Object。

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：空

通过/api/sessions获取到的Token是临时的，在系统重启后会失效。有时候，对于一些后台任务或需要长期Token的场景，可以使用开发Key进行身份验证。

用户登录后可以在用户详情界面上生成开发key，申请后永久有效。当然申请后还可以查询和删除。

用于API客户端创建申请某一服务器的开发key，申请完永久有效。得到的Key可以直接做为上一节中的Token使用。

默认情况下URL中的user_id部分需要填入自己的ID，admin可以填入其它用户的ID以便为其它用户生成开发Key。

POST http://host:port/api/users/$user_id/dev_keys

data对象：

• k：string，开发Key。
• enabled：数字字符串，是否启用。

• 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"
}

用户API客户端删除自己的开发key。

DELETE http://host:port/api/users/$user_id/dev_keys

• 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"
}

用于API客户端查询自己的开发key列表。

POST http://host:port/api/users/1/dev_keys

• 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登录的情况下，如在使用WebRTC发起呼叫等，可以产生分机Token。

POST /api/users/extn_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认证地址是/ws，在建立连接后进行认证。文档见JSON API相关文档。

Websocket可以使用用户Token也可以使用分机Token登录。

在hash方式的Session存储中，可以使用以下命令查看

hash select/xui/$token