diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index ec77948a..44d15076 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -71,6 +71,7 @@ module.exports = { children: [ 'bot/bot-context', 'bot/message-segment', + 'bot/authorization', ] }, { diff --git a/docs/components/bot/authorization.md b/docs/components/bot/authorization.md new file mode 100644 index 00000000..7b2aee41 --- /dev/null +++ b/docs/components/bot/authorization.md @@ -0,0 +1,94 @@ +# 机器人接入鉴权 + +允许所有客户端接入框架是不安全的,因此框架提供了一个接入鉴权的功能,只有经过鉴权的客户端才能接入框架。 + +目前框架根据 [OneBot 12 标准中规定的鉴权方式](https://12.onebot.dev/connect/communication/http/#_1) +进行鉴权,即通过 `access_token` 进行鉴权。 + +## 鉴权流程 + + 1. 客户端在连接时,通过 OneBot 12 标准中规定的方式传递 `access_token` 参数。 + 2. 框架在接收到客户端的连接请求后,会根据 `access_token` 参数进行鉴权。 + 3. 如果鉴权成功,框架将会接受客户端的连接请求,并开始分发后续事件。 + 4. 如果鉴权失败,框架将会断开客户端的连接。 + +## 鉴权方式 + +框架提供了两种鉴权方式,分别是静态鉴权和动态鉴权,适应不同的使用场景。 + +### 静态鉴权 + +静态鉴权是指在配置文件中指定一个 `access_token`,并在客户端连接时传递相同的 `access_token` 参数。 + +```php +/* 要启动的服务器监听端口及协议 */ +$config['servers'] = [ + [ + 'host' => '0.0.0.0', + 'port' => 20001, + 'type' => 'websocket', + 'access_token' => '1234567890', // 静态鉴权 + ], + [ + 'host' => '0.0.0.0', + 'port' => 20002, + 'type' => 'http', + 'flag' => 20002, + 'access_token' => '0987654321', // 静态鉴权 + ], +]; +``` + +为不同的通信方式指定不同的 `access_token` 是完全可行的。 + +### 动态鉴权 + +在部分场景下,静态鉴权可能不太适用,例如多个客户端共享一个框架,或是客户端的 `access_token` 无法预先知晓的情况下。 + +框架提供了动态鉴权的功能,可以在客户端连接时,由给定的回调函数来决定是否接受客户端的连接请求。 + +```php +/* 要启动的服务器监听端口及协议 */ +$config['servers'] = [ + [ + 'host' => '0.0.0.0', + 'port' => 20001, + 'type' => 'websocket', + 'access_token' => function ($token) { + // 动态鉴权 + return $token === '1234567890'; + }, + ], + [ + 'host' => '0.0.0.0', + 'port' => 20002, + 'type' => 'http', + 'flag' => 20002, + 'access_token' => function ($token) { + // 动态鉴权 + return $token === '0987654321'; + }, + ], +]; +``` + +你可以在回调函数做任意处理,例如使用特定算法进行鉴权,或是从数据库中读取 `access_token` 进行鉴权。 + +## 自定义鉴权 + +除了上述方式外,你也可以通过留空 `access_token` 参数,并在 `WebsocketOpenEvent` 事件中自行进行鉴权。 + +```php +#[\BindEvent(\WebSocketOpenEvent::class)] +public function handle(WebsocketOpenEvent $event) +{ + // 自定义鉴权 + // $event->getRequest() 可以获取到客户端的连接请求 +} +``` + +如果拒绝接入,只需返回 401 响应即可,例如: + +```php +$event->withResponse(HttpFactory::createResponse(401, 'Unauthorized')); +```