Callback установки

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

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

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

Сразу после добавления локального приложения Битрикс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. Браузер в этом процессе не участвует.