Каждый PHP-разработчик, работающий с экосистемой Bitrix Framework, должен глубоко понимать работу её ключевых компонентов. В этой статье мы проведем подробный аудит темы «Упрощенный вариант получения токенов OAuth 2.0», проанализируем лучшие практики и покажем, как правильно использовать битрикс в реальных задачах.

Упрощенный вариант получения токенов OAuth 2.0

Простейшим сценарием для получения доступа к REST API является работа приложения в интерфейсе Битрикс24. В этом случае все необходимые авторизационные данные выдаются приложению при открытии, а также доступна возможность использования js-библиотеки для совершения вызовов к API.

Приложение получает следующий массив POST-данных:

array (
    'DOMAIN' => 'portal.bitrix24.com',
    'PROTOCOL' => '1',
    'LANG' => 'ru',
    'APP_SID' => 'dd8cec11e347088fe87c44870a9f1dba',
    'AUTH_ID' => 'ahodg4h37n89vo17gbkgq0x1l825nnb5',
    'AUTH_EXPIRES' => '3600',
    'REFRESH_ID' => '2lg086mxijlpvwh0h7r4nl19udm4try5',
    'member_id' => 'a223c6b3710f85df22e9377d6c4f7553',
    'status' => 'P'
)

При помощи значения параметра AUTH_ID можно сразу совершать запросы к API.

И, как написано выше, приложения в интерфейсе могут совершать запросы к API на стороне клиента, то есть браузера пользователя, подключив js-библиотеку и используя методы BX24.callMethod и BX24.callBatch. В этом случае работа с авторизацией будет происходить автоматически.

Таким образом, становится доступным простой сценарий получения авторизационных токенов пользователя при установке приложения. Как вы знаете (это было продемонстрировано в соответствующем примере), у публичного тиражного решения существует возможность задать отдельный скрипт установки, который будет показываться пользователю, устанавливающему ваше решение, во фрейме один раз — в момент установки решения. И в этот фрейм Битрикс24 передает те же самые данные в POST-запросе, что и в обычном случае. Следовательно, вы можете так разработать скрипт установки, чтобы сохранять токены (что самое важное — refresh_token в том числе) на стороне своего приложения, чтобы в дальнейшем реализовать сценарий автоматического возобновления токенов.

Событие установки приложения

Для приложений, не имеющих страницы в интерфейсе Битрикс24 (параметр Использует только API в форме редактирования приложения в партнерском кабинете или на портале), доступен вот такой способ авторизации. В форме редактирования версии (или в форме редактирования локального приложения на портале) можно указать значение параметра Ссылка-callback для события установки. Если указать в этом поле ссылку на обработчик на стороне приложения, то при установке приложения обработчик получит POST-запрос со следующими данными (application/x-www-form-urlencoded):

array(
    'event' => 'ONAPPINSTALL',
    'data' => array(
        'VERSION' => '1',
        'LANGUAGE_ID' => 'ru',
    ),
    'ts' => '1466439714',
    'auth' => array(
        'access_token' => 's6p6eclrvim6da22ft9ch94ekreb52lv',
        'expires_in' => '3600',
        'scope' => 'entity,im',
        'domain' => 'portal.bitrix24.com',
        'server_endpoint' => 'https://oauth.bitrix24.tech/rest/',
        'status' => 'F',
        'client_endpoint' => 'https://portal.bitrix24.ru/rest/',
        'member_id' => 'a223c6b3710f85df22e9377d6c4f7553',
        'refresh_token' => '4s386p3q0tr8dy89xvmt96234v3dljg8',
        'application_token' => '51856fefc120afa4b628cc82d3935cce',
    ),
)

Поля запроса содержат информацию о событии (event), данные события (data), а также авторизационные данные для доступа к REST API (auth) от имени пользователя, установившего приложение.

Значимые параметры:

• access_token — основной авторизационный токен, требуемый для доступа к REST API
• refresh_token — дополнительный авторизационный токен, служащий для продления сохраненной авторизации
• client_endpoint — адрес REST-интерфейса портала
• server_endpoint — адрес REST-интерфейса сервера
• status — статус приложения на портале

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