# Подключение и авторизация
В составе TrueConf Server поставляется служба TrueConf Bridge. Данная служба содержит HTTP и WebSocket сервер, используемый для реализации функционала API по работе с чатами. Служба TrueConf Bridge использует TCP порт 4309.
Для отправки запросов (команд) API необходимо предварительно подключиться к WebSocket-серверу и авторизовать подключение с помощью идентификационного токена и запроса auth.
Для подключения к серверу необходимо установить WebSocket-соединение по следующему адресу /weboscket/chat_bot/
:
C localhost напрямую к службе TrueConf Bridge (порт 4309) c использованием WebSocket (ws):
ws://localhost:4309/websocket/chat_bot/
Извне к службе TrueConf Web (порт 443 или иной) с использованием WebSocket Secure (wss):
wss://video.example.net/websocket/chat_bot/
Сервер поддерживает подпротокол json.v1, который передаётся в заголовке Sec-WebSocket-Protocol. Если заголовок не указан, то json.v1 будет использоваться по умолчанию.
# Поддерживаемые учетные записи
Поддерживаются учетные записи пользователей только текущего сервера TrueConf. Авторизация посредством учетных записей серверов подключенных по федерации или гостевыми аккаунтами не поддерживается. Поддерживаются учетные записи как в режиме Registry так и в режиме LDAP.
# Идентификационный токен
Идентификационный токен необходим для авторизации веб-сокет соединения. Получение токена происходит через HTTP запрос на адрес /bridge/api/client/v1/oauth/token
по стандарту OAuth 2.0 (opens new window). При этом, служба TrueConf Bridge не принимает HTTPS запросы. О том, как получить токен используя зашифрованное соединение (HTTPS) читайте ниже.
# Запрос на получение токена
Для получения идентификационного токена выполните POST-запрос:
POST /bridge/api/client/v1/oauth/token HTTP/1.1
Host: localhost:4309
Content-Type: application/json
Content-Length: 114
{
"client_id": "chat_bot",
"grant_type": "password",
"username": "user",
"password": "qwerty"
}
Параметр | Описание |
---|---|
client_id | Константная строка "chat_bot" |
grant_type | Константная строка "password" |
username | Логин пользователя (см. тут) |
password | Пароль пользователя |
# Успешная авторизация
В случае успешной авторизации, HTTP-сервер ответит кодом 201 Created:
HTTP/1.1 201 Created
Content-Type:application/json
Access-Control-Allow-Origin:*
Date:Mon, 09 Sep 2024 22:42:50 GMT
{
"access_token": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ",
"token_type": "JWE",
"expires_in": 31536000
}
Параметр | Описание |
---|---|
access_token | Идентификационный токен, используемый для авторизации WebSocket-соединения. |
token_type | Константная строка "JWE" . |
expires_in | Время жизни токена в секундах с момента формирования токена составляет один год. По истечении этого времени потребуется повторная авторизация. |
Подробнее про возвращаемую структуру в теле ответа (payload) читайте тут.
# Ошибка авторизации
В случае ошибки авторизации, HTTP-сервер ответит кодом 400 Bad Request:
HTTP/1.1 400 Bad Request
Content-Type:application/json
Access-Control-Allow-Origin:*
Date: Mon, 09 Sep 2024 22:42:50 GMT
{
"error": "invalid_grant",
"error_description": "Invalid username or password"
}
Параметр | Описание |
---|---|
error | Значение из перечисления OAUTH_ERROR. |
error_description | Человекочитаемый текст ошибки авторизации. |
Подробнее про возвращаемую структуру в теле ответа (payload) читайте тут.
# Использование HTTPS
HTTP-протокол используется для:
получения идентификационного токена;
загрузки файла в специальное хранилище на сервере.
При этом служба TrueConf Bridge не поддерживает протокол HTTPS. Если требуется использовать HTTPS, необходимо направлять запросы на веб-сервер TrueConf, реализуемый службой TrueConf Web Manager. Служба TrueConf Web Manager проксирует все HTTPS-запросы, поступающие по адресу /bridge/api/
, в службу TrueConf Bridge.
Таким образом, при необходимости использовать протокол HTTPS, запросы можно отправлять на порт 443 или иной порт, указанный в панели управления TrueConf Server, предварительно убедившись, что служба TrueConf Web Manager запущена:
https://video.example.net/bridge/api/client/v1/oauth/token
# Авторизация WebSocket соединения
После получения идентификационного токена, вам необходимо авторизовать ваше WebSocket подключение.
Запрос:
{
"type": 1,
"id": 1,
"method": "auth",
"payload": {
"token": "someToken",
"tokenType" : "JWE"
}
}
Параметр | Тип | Обяз. | Описание |
---|---|---|---|
type | uint32 | Да | Тип сообщения (по умолчанию 1 ). Соответствует MESSAGE_TYPE.REQUEST |
id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
method | string | Да | Тип отправляемой команды, по умолчанию auth |
token | string | Да | Авторизационный токен, полученный посредством HTTP-запроса |
tokenType | string | Да | По умолчанию JWE |
Ответ:
{
"type": 2,
"id": 1,
"payload": {
"userId": "someTrueConfUserId@someTrueConfServeName/someHash"
}
}
Параметр | Тип | Обяз. | Описание |
---|---|---|---|
type | uint32 | Да | Тип сообщения (по умолчанию 2 ). Соответствует MESSAGE_TYPE.RESPONSE |
id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
userId | string | Да | TrueConf ID авторизованного бота (пользователя сервера) |
В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode
. Список возможных значений доступен в соответствующем разделе документации.
# Отправка сообщений без авторизации
В том случае, если не выполнив команды auth
начать отправлять сообщения по веб-сокету, на любое сообщение будет приходить ошибка c кодом 200
.