# Работа с API сервера
Расширить возможности по использованию TrueConf Server можно с помощью RESTful API, доступного во всех версиях, в том числе и бесплатной.
# Принципы работы API и OAuth 2.0
Раздел API → OAuth2 предназначен для управления приложениями или сервисами, работающими с TrueConf Server API. Управление доступом происходит согласно протоколу авторизации OAuth 2.0, подробнее о котором вы можете прочитать в официальной документации к RFC 6749 (opens new window), а также во врезке ниже.
Основная идея протокола OAuth 2.0 состоит в выдаче прав на доступ к API отдельным приложениям (client в терминологии OAuth) с ограниченной областью видимости и правами. Такой подход позволяет в любой момент отключить доступ конкретному приложению или его пользователю к ресурсам сервера. Протокол также позволяет безопасно авторизовать сторонние приложения и совершать действия на сервере через API от имени пользователя. При этом пользователь не должен сообщать свои логин или пароль стороннему приложению (метод Authorization Code).
Каждое стороннее приложение обязано получить ключ доступа (access token) в результате процесса авторизации на TrueConf Server по протоколу OAuth 2.0. Приложения, имеющие валидный ключ доступа, могут в любой момент обращаться к TrueConf Server API, список вызовов которого описан в документации. Через данный раздел панели управления администратор TrueConf Server имеет контроль не только над доступами сторонних приложений, но и над ключами, полученными через эти приложения.
Примеры работы с Труконф API показаны в нашем блоге.
После авторизации приложение получает ключ доступа (access token) с ограниченным временем жизни и с серверной либо пользовательской областью видимости. Например, серверная область видимости позволяет получать данные о любых конференциях, а пользовательская — только о конференциях, где пользователь является участником или владельцем. Область видимости определяется выбранным разработчиком стороннего приложения типом авторизации, а набор прав на доступ к ресурсам сервера определяется администратором сервера.
| Метод авторизации OAuth 2.0 | Область видимости ключа доступа | Результат авторизации |
|---|---|---|
| Client Credentials Приложение получает ключ доступа, область видимости которого не ограничена данными конкретного пользователя. Авторизация для пользователя не требуется. Рекомендуется использовать только для доверенных приложений. | Не ограничена. | Выдаётся ключ доступа (access token) со временем жизни 1 час. |
| User Credentials (он же Resource Owner Password Credentials Grant)
Для получения ключа доступа необходимо передать логин и пароль пользователя, полученные на стороне приложения. | Ограничена областью видимости авторизованного пользователя. | Выдаётся ключ доступа на 1 час, а также ключ продления доступа (refresh token) на 7 дней. |
| Authorization Code Ключ доступа (access token) выдаётся после самостоятельной авторизации пользователя на стороне TrueConf Server. Логин и пароль пользователя приложению недоступны. | Ограничена областью видимости авторизованного пользователя. | Выдаётся ключ доступа на 1 час, а также ключ продления доступа на 7 дней. |
| Refresh Token Данный метод авторизации позволяет получить новый ключ доступа (access token) на основе существующего ключа продления доступа (refresh token). | Ограничена областью видимости пользователя, которому был выдан ключ продления доступа. | Выдаётся новый ключ доступа на 1 час. Обновить его с помощью этого метода нельзя. |
Каждый запрос на создание ключа доступа требует указания ID приложения (Application ID) и секрета приложения (Secret), которые можно получить и обновить, создав или, соответственно, отредактировав приложение в этом разделе. ID приложения создаётся автоматически и не может быть изменён в дальнейшем, в отличие от секрета приложения, который можно сгенерировать заново.
# Описание разрешений
Возможности стороннего приложения по работе с API зависят от выданных ему разрешений.
| Разрешение | Описание |
|---|---|
| conferences:read | Чтение информации о конференции |
| conferences:write | Создание, редактирование, удаление конференции |
| conferences.records:read | Чтение информации о записях конференций |
| conferences.participants:read | Чтение списка участников конференции |
| conferences.participants:write | Создание, редактирование, удаление участников конференции |
| conferences.invitations | Чтение и редактирование списка приглашённых в конференцию абонентов |
| conferences.sessions:read | Чтение информации об определённой сессии (активном сеансе видеосвязи) |
| conferences.sessions.participants:read | Чтение списка участников активной конференции и их ролей |
| conferences.sessions.podiums.participants | Приглашение участника активной конференции на трибуну и удаление его с трибуны |
| groups:read | Чтение информации о группе пользователей |
| groups:write | Создание, редактирование, удаление групп пользователей. Недоступно в LDAP |
| groups.users:read | Чтение списка пользователей группы |
| groups.users:write | Создание, редактирование, удаление пользователей групп. Недоступно в LDAP |
| users:read | Чтение информации о пользователях сервера |
| users:write | Создание, редактирование, удаление пользователей сервера. Недоступно в LDAP |
| users.addressbook:read | Чтение контактов из адресных книг пользователей |
| users.addressbook:write | Создание, редактирование, удаление контактов в адресной книге пользователей |
| users.avatar:read | Чтение информации об аватарах пользователей |
| users.avatar:write | Добавление и удаление аватаров пользователей |
| templates.conferences:read | Чтение информации о шаблонах конференций |
| templates.conferences:write | Создание, редактирование, удаление шаблонов конференций |
| logs.calls:read | Чтение списка конференций из логов сервера |
| logs.calls.participants:read | Чтение списка участников конференции из логов сервера |
| logs.calls.invites:read | Чтение списка приглашённых в конференцию пользователей из логов сервера |
В документации к TrueConf Server API для каждого метода указан набор разрешений, требуемых для его успешного вызова.
Если OAuth-приложению требуется доступ как на чтение так и на запись некоторого параметра, то вместо указания разрешений <permission>:read и <permission>:write можно указать общее разрешение <permission> если это доступно. Например, для того, чтобы приложение могло читать и редактировать учётные записи пользователей сервера, то вместо выбора обоих флажков users:read и users:write можно указать только один users.
# Форма создания нового OAuth 2.0 приложения
Для добавления OAuth 2.0 приложения:
Нажмите Создать новое приложение.
Укажите его идентификатор в поле Имя. Он используется только для отображения в списке приложений.
Для авторизации методом Authorization Code в поле Переадресация URL укажите URL-адрес, на который будет перенаправлено приложение. Для остальных методов авторизации можно указать адрес
https://localhost/.В списке Разрешения отметьте необходимые для вашего приложения права.
Сохраните изменения с помощью кнопки Создать.
# Страница редактирования приложения
На странице приложения помимо редактирования его свойств возможно также увидеть список ключей доступа, которые были получены пользователями этого приложения. Вы можете в любой момент удалить ключи доступа для конкретных пользователей, что не позволит им более обращаться к ресурсам сервера через API.
Вы также можете Перегенерировать секрет приложения, что может быть полезно в целях безопасности для прекращения доступа к серверу этому приложению, а также всем его новым пользователям. Обратите внимание, что ключи доступа и продления доступа, полученные с использованием старого секрета, продолжат работать до окончания их времени жизни.