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