Callback установки

Callback установки — способ получить токены авторизации на своем сервере. Сразу после установки локального приложения Битрикс24 отправляет на адрес из поля Путь для первоначальной установки POST-запрос события ONAPPINSTALL. Данные авторизации OAuth 2.0, включая access_token и refresh_token, приходят в объекте auth.

Когда применятьКогда применять

Вариант подходит приложениям, которым не нужна первоначальная настройка: например, вся логика работает в обработчиках событий. Если интерфейс не нужен, оставьте пустыми поля Название пункта меню — приложение не появится в левом меню, но сможет регистрировать виджеты в местах встройки.

Опцию Приложение само завершает установку оставьте выключенной, как по умолчанию. Если ее включить, Битрикс24 не отправит данные на обработчик и будет ждать вызова BX24.installFinish() на странице мастера установки.

Как настроить установкуКак настроить установку

Обработчик из примера проверит токен из запроса установки и сохранит данные авторизации в файл. Чтобы он получил запрос:

1. Создайте локальное приложение: заполните поле Путь вашего обработчика и выберите права доступа. Поле Путь для первоначальной установки пока не заполняйте. После сохранения формы в ней появится client_id приложения
2. Укажите client_id в коде обработчика и разместите обработчик на своем сервере, доступном по HTTPS. Примеру ниже нужны PHP 7.4 или новее с расширением cURL и каталог /var/app-data, в который PHP может писать
3. Впишите адрес обработчика в поле Путь для первоначальной установки и сохраните форму
4. Нажмите в форме Переустановить — это может сделать только администратор. Битрикс24 отправит запрос установки на обработчик

Пример обработчикаПример обработчика

Фрагмент запроса, значения сокращены:

$_POST = [
  'event' => 'ONAPPINSTALL',
  'auth' => [
    'access_token' => '***',
    'refresh_token' => '***',
    'expires_in' => 3600,
    'client_endpoint' => 'https://example.bitrix24.ru/rest/',
    'member_id' => '***',
    'application_token' => '***'
  ]
];

Обработчик доступен по публичному адресу, поэтому запрос на него может прислать кто угодно. Прежде чем сохранять токены, проверьте их методом app.info.

Локальное приложение работает в одном Битрикс24, и его адрес известен заранее. Адрес client_endpoint в запросе задает отправитель, поэтому вызовите метод с полученным access_token по адресу своего Битрикс24. Если токен выдан вашему приложению, поле CODE в ответе совпадет с client_id приложения. Фрагмент ответа:

{
  "result": {
    "ID": 1,
    "CODE": "local.000000000000000000000000",
    "STATUS": "L",
    "INSTALLED": true
  }
}

<?php
const CLIENT_ID = 'local.000000000000000000000000';
// адрес REST API вашего Битрикс24
const PORTAL_ENDPOINT = 'https://example.bitrix24.ru/rest/';
// храните токены вне публичного каталога сайта
const AUTH_FILE = '/var/app-data/auth.json';

$auth = $_POST['auth'] ?? [];

$ch = curl_init(PORTAL_ENDPOINT . 'app.info');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(['auth' => $auth['access_token'] ?? '']));
$response = curl_exec($ch);
if ($response === false)
{
    error_log('app.info: ' . curl_error($ch));
}
curl_close($ch);

$result = json_decode((string)$response, true);
if (isset($result['error']))
{
    error_log('app.info: ' . $result['error']); // токены в лог не пишем
}

$required = ['access_token', 'refresh_token', 'member_id', 'application_token'];
$isComplete = count(array_filter($required, fn($key) => !empty($auth[$key]))) === count($required);

if (($_POST['event'] ?? '') !== 'ONAPPINSTALL' || !$isComplete || ($result['result']['CODE'] ?? '') !== CLIENT_ID)
{
    http_response_code(403);
    exit();
}

if (file_put_contents(AUTH_FILE, json_encode($auth, JSON_UNESCAPED_SLASHES)) === false)
{
    http_response_code(500);
    exit();
}

После переустановки проверьте, что файл /var/app-data/auth.json появился и в нем есть access_token, refresh_token, member_id и application_token. Если файла нет, посмотрите ответ обработчика и журнал ошибок PHP:

• в журнале app.info: и текст ошибки cURL — сервер приложения не смог обратиться к Битрикс24. Проверьте адрес в PORTAL_ENDPOINT и доступ сервера к нему, затем нажмите Переустановить
• в журнале app.info: и код ошибки — метод вернул ошибку. Например, invalid_token значит, что Битрикс24 не принял токен, а expired_token — что токен истек. Остальные коды описаны в статье Коды ошибок. Если запрос был настоящим, нажмите Переустановить
• ответ 403 без записи в журнале — пришло не событие ONAPPINSTALL, в auth не хватает полей, app.info вернул ответ не в формате JSON или CODE не совпал с CLIENT_ID. Если запрос был настоящим, проверьте client_id в коде обработчика и адрес в PORTAL_ENDPOINT, затем нажмите Переустановить
• ответ 500 — PHP не смог записать файл. Проверьте права на каталог, затем нажмите Переустановить

Вместе с токенами сохраните application_token и member_id. По ним другие обработчики приложения сверяют входящие события, подробнее — в статье Безопасность в обработчиках.

По сохраненному refresh_token приложение продлевает доступ без участия пользователя. При каждом продлении приходит новая пара токенов — сохраняйте ее вместо прежней. Порядок продления — в статье Автоматическое продление токенов OAuth 2.0.

Если токены не сохранилисьЕсли токены не сохранились

Если приложение не сохранило refresh_token при установке, получите первую пару токенов по полному протоколу авторизации OAuth 2.0. Возьмите client_id и client_secret из формы приложения. После авторизации Битрикс24 вернет пользователя на адрес из поля Путь вашего обработчика. В ответе OAuth нет application_token: если он сохранился при установке, не перезаписывайте его. Если не сохранился, нажмите в форме приложения Переустановить — обработчик получит его заново.

Продолжите изучениеПродолжите изучение

• Установка локальных приложений: обзор сценариев
• Мастер установки локального приложения
• Автоматическое продление токенов OAuth 2.0
• Безопасность в обработчиках