You need to enable JavaScript to run this app.
导航

使用 Token 完成鉴权

最近更新时间2024.01.04 16:48:07

首次发布时间2021.07.21 14:29:15

应用客户端在加入 RTC 房间,登录以收发实时消息时,都需要传入 Token 参数,完成鉴权。此 Token 来自你的应用服务端,由应用服务端在加入房间时,根据 RTC AppID、RTC AppKey、需要加入的 RTC RoomID、加入房间时使用的 RTC UserID、时间戳等参数实时生成。

RTC 服务端在收到进房请求时,会校验进房请求中携带的 Token 信息,如果校验不成功,进房会失败。

鉴权全流程

鉴权全流程如下。

  1. 客户端根据需要,向应用服务端申请 Token。

  2. 应用服务端生成 Token。

  3. 应用服务端将 Token 下发到客户端。

  4. 客户端使用获取到的 Token 申请加入房间。

    说明:加入房间时设置的 uid 和 roomid 需与用于生成 Token 的 uid 和 roomid 保持一致,否则会加入房间失败,并收到错误提示为 ERROR_CODE_INVALID_TOKENonRoomStateChanged 回调。

  5. RTC 服务端验证 Token。

  6. 应用客户端收到来自 RTC SDK 的回调,获取加入房间的结果(成功/失败)。

  7. Token 是有一定有效期的。Token 过期前 30 s,客户端会收到 onTokenWillExpire 回调。

    说明:Token 过期后,用户将被移出房间,并收到 ERROR_CODE_INVALID_TOKEN 回调,错误码是 ERROR_CODE_TOKEN_EXPIRED。需要在申请新的 Token 之后调用 JoinRoom 加入房间。

  8. 此时,如果客户端需要继续进行音视频通话,需要申请新的 Token。

  9. 如步骤2。

  10. 如步骤3。

  11. 调用 updateToken 接口,使用新的 Token,更新 Token。

你需要自行实现步骤 1,2,3,4,11 的代码逻辑。

生成 Token

你可以参考 RTC 提供的示例代码,在应用服务端实现 Token 的生成。

以下文件包含了多种语言实现的相关代码:

RTC_Token.zip
47.53KB

以 Golang 为例,参考以下代码:

var (
// 确保通话时使用的 appID, roomID 和 userID 与用于生成 Token 的相同,否则会导致进房失败。
    appID  = "xxxxx" 
    appKey = "xxxxx" 
    roomID = "room" // 生成用于登录实时消息服务的 Token 时传空值
    userID = "uid"
)
t := AccessToken.New(appID, appKey, roomID, userID)
// 添加此 Token 的有效时间,两小时过期。过期后,你无法使用此 Token 进房。
t.ExpireTime(time.Now().Add(time.Hour * 2))
// 添加订阅流权限
t.AddPrivilege(AccessToken.PrivSubscribeStream, time.Time{})
// 添加发布流权限
t.AddPrivilege(AccessToken.PrivPublishStream, time.Time{})
// 获取最终生成的 token
token,err := t.Serialize()
参数说明
appId 和 appKey在控制台添加应用时获得,参看开通服务
roomID 和 userID赋值规则详见参数赋值规范
ExpireTimeToken 的有效时长,建议设置为 24 小时。不建议设置得过长或永不过期。
PrivPublishStream 和 PrivSubscribeStreamToken 的发布和订阅权限的有效时长,用于连麦鉴权。至少需要设置其中一个参数才能成功进房,可设置为 0。
  • 如需通过 Token 控制连麦权限,请使用 Native SDK v3.50.3Web SDK v4.60 及以后版本,并联系技术支持团队开通白名单后进行设置。建议与 ExpireTime 相同。
  • Native SDK v3.50.3、Web SDK v4.60 之前的版本,为保留参数,但仍需赋值。例如,设置为 0
  • 使用通配 Token

    一般来说,在加入 RTC 房间时,客户端应获取此房间 ID 对应生成的 Token。但是在一些场景下,如果客户端需要频繁切换加入的房间,那么,生成和获取 Token 的过程可能造成进房延误和 Token 服务端压力过大等问题。为解决此问题,RTC 也支持在生成 Token 时,将 roomID 设置为通配符,同一用户使用此通配 Token 可以加入不同的 RTC 房间。

    生成通配 Token 的算法和上文介绍的算法完全一致。在生成通配 Token 时,你仅需要将 roomID 设置为 "*"

    注意:

    • 在使用通配 Token 加入不同房间时,应注意房间内的 userID 不可重复。
    • 一旦通配 Token 泄露,非法用户可能扰乱房间内秩序或造成信息泄露。你应仅在需要的场景下,使用通配 Token。另外,使用通配 Token 时,建议仅为这部分用户添加订阅流权限,不添加发布流权限;在需要发布流时,另外生成添加了发布流权限的 Token,并通过 updateToken 接口更新权限。
    • 通配 Token 过期时,应获取服务端重新生成的通配 Token 更新相关权限。
    • 仅有较新的 RTC SDK 支持通配 Token;不在此范围内的 RTC SDK 版本中使用通配 Token 时,无法进房。支持通配 Token 的 RTC SDK 有:
      • Native SDK 3.19+;
      • Web SDK 4.46+;
      • 微信小程序 SDK 3.0+;
      • 所有的 Electron,Flutter,和 Unity SDK。

    使用临时 Token

    在进行应用测试时,你可以在控制台上获取测试使用的临时 Token,无需在应用服务端部署 Token 生成服务。

    一般进行测试时,常用两台或多台设备进行音视频通话。进行测试时,这些设备应加入同一个房间。在申请临时 Token 和加入房间时,这些设备应使用同一个 roomId 和不同的 uid。申请 Token 时,临时 Token 是根据 roomId,uid,和时间戳信息生成的,每个临时 Token 都不一样。申请完临时 Token 后,你应记录下申请时的 roomId 和 uid,以及申请得到的临时 Token,以供使用设备加入房间时使用。
    当申请的临时 Token只用于进行实时消息功能测试时,房间 ID 可填写任意值。
    你可以在 控制台-应用管理 页面,输入相关信息,并生成对应的 Token,用于功能测试。
    image

    临时 Token 仅用于测试阶段,有使用时间限制,且安全性较低。若该项目准备正式上线,你必须使用遵循以上步骤在应用服务端生成的 Token。

    Token 使用常见问题

    常见问题参看Token 使用常见问题