Callback установки

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

Это полезный сценарий для приложений, которым не нужен отдельный пользовательский интерфейс или настройки, а вся бизнес-логика реализована, например, в виде автоматических обработчиков событий.

Несмотря на отсутствие пользовательского интерфейса, таким приложениям нужно получить токены авторизации. Для этого нужен callback-обработчик, путь к которому нужно указать в поле Путь для первоначальной установки. Опция Приложение само завершает установку должна быть выключена — по умолчанию так и есть. Если ее включить, Битрикс24 не отправит данные установки на обработчик и будет ждать вызова installFinish на странице мастера установки.

Сразу после добавления локального приложения Битрикс24 автоматически обратится к этому URL и передаст туда POST-запрос с данными авторизации OAuth 2.0, включая access_token и refresh_token.

Приложение должно сохранить эти токены на своей стороне. access_token действует ограниченное время, поэтому постоянный доступ к REST API обеспечивается не бессрочным токеном, а сохраненным refresh_token.

Пример получения и сохранения токеновПример получения и сохранения токенов

Callback-обработчик должен принять POST-запрос установки и сохранить объект auth. Для дальнейшей работы приложения важен refresh_token: по нему приложение сможет получать новую пару токенов без участия пользователя.

<?php
const AUTH_FILE = __DIR__ . '/auth.json';

function saveAuth(array $auth): void
{
    file_put_contents(AUTH_FILE, json_encode($auth, JSON_UNESCAPED_SLASHES));
}

if (isset($_POST['auth']) && is_array($_POST['auth']))
{
    saveAuth($_POST['auth']);

    header('Content-Type: application/json');
    echo json_encode(['status' => 'success']);
    exit();
}

http_response_code(400);
echo 'Auth data is required';

Сохраненный refresh_token нужно использовать для автоматического продления токенов OAuth 2.0. При каждом продлении Битрикс24 возвращает новую пару access_token и refresh_token, ее нужно перезаписать на стороне приложения.

В примере токены записываются в файл auth.json. В рабочем приложении храните токены в недоступном из браузера хранилище.

Получение первой пары токенов через полный OAuthПолучение первой пары токенов через полный OAuth

Если приложение не сохранило refresh_token при установке или нужно повторно получить первую пару токенов, используйте полный протокол авторизации OAuth 2.0. Этот сценарий не заменяет callback установки, а помогает заново пройти первичную авторизацию приложения.

Возьмите client_id и client_secret из формы локального приложения. Обратный адрес, на который Битрикс24 вернет пользователя после авторизации, берется из настроек приложения.

Сформируйте ссылку авторизации и откройте ее в браузере от имени пользователя, который дает приложению доступ к Битрикс24.

<?php
const CLIENT_ID = 'local.000000000000000000000000';

$domain = 'example.bitrix24.ru';

$authorizeUrl = 'https://' . $domain . '/oauth/authorize/?' . http_build_query([
    'client_id' => CLIENT_ID,
]);

header('Location: ' . $authorizeUrl);
exit();

После авторизации Битрикс24 перенаправит пользователя на redirect_uri и передаст параметр code. Это не токен для REST API, а одноразовый код авторизации. Время жизни code — 30 секунд, поэтому обменять его на токены нужно сразу.

<?php
const CLIENT_ID = 'local.000000000000000000000000';
const CLIENT_SECRET = 'client_secret';
const AUTH_FILE = __DIR__ . '/auth.json';

if (!isset($_GET['code']))
{
    http_response_code(400);
    echo 'Authorization code is required';
    exit();
}

$query = http_build_query([
    'grant_type' => 'authorization_code',
    'client_id' => CLIENT_ID,
    'client_secret' => CLIENT_SECRET,
    'code' => $_GET['code'],
]);

$response = file_get_contents('https://oauth.bitrix24.tech/oauth/token/?' . $query);
$auth = json_decode($response, true);

if (!is_array($auth) || isset($auth['error']))
{
    http_response_code(400);
    echo $response;
    exit();
}

file_put_contents(AUTH_FILE, json_encode($auth, JSON_UNESCAPED_SLASHES));

echo 'Authorization tokens saved';

Такой сценарий не создает бессрочный access_token. Приложение получает первую пару токенов, сохраняет refresh_token и использует его для продления доступа. Если refresh_token не обновлять, срок его действия закончится.

В случае callback-обработчика установки приложение также не должно вызывать JS-метод BX24.installFinish(), как это нужно делать для локальных приложений с мастером установки.

Даже если попытаться это сделать, метод не сработает. BX24.installFinish() работает только во фреймах интерфейса приложения в браузере, а callback-обработчик приложения вызывается с серверной стороны Битрикс24. Браузер в этом процессе не участвует.