XSwitch 认证鉴权接口

XSwitch.cn  

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