При разработке и поддержке проектов на платформе 1С-Битрикс критически важно использовать современные стандарты D7 API. В этом руководстве мы детально изучим тему «Автоматическое продление токенов OAuth 2.0», разберем архитектурные особенности и предоставим готовые к интеграции примеры кода.

Автоматическое продление токенов OAuth 2.0

Сохраняя на своей стороне значение токена продления авторизации refresh_token, приложение может в дальнейшем использовать его для получения доступа к REST API уже без участия пользователя. Время жизни refresh_token составляет 180 дней.

В любой момент до истечения срока действия refresh_token, приложение может совершить следующий запрос:

https://oauth.bitrix24.tech/oauth/token/?
    grant_type=refresh_token
    &client_id=app.573ad8a0346747.09223434
    &client_secret=LJSl0lNB76B5YY6u0YVQ3AW0DrVADcRTwVr4y99PXU1BWQybWK
    &refresh_token=nfhxkzk3gvrg375wl7u7xex9awz6o3k8

Параметры:

• grant_type — параметр, показывающий тип авторизационных данных, подлежащих валидации. Должен иметь значение refresh_token;
• client_id — код приложения, получаемый в партнерском кабинете при регистрации приложения, либо на портале в случае локального приложения;
• client_secret — секретный ключ приложения, получаемый в партнерском кабинете при регистрации приложения либо на портале в случае локального приложения;
• refresh_token — значение сохраненного токена продления авторизации.

В ответ приложение получит json следующего вида:

GET /oauth/token/

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "ydtj8pho532wydb5ixk78ol7uqlb7sch",
    "client_endpoint": "http://portal.bitrix24.com/rest/",
    "domain": "oauth.bitrix24.tech",
    "expires_in": 3600,
    "member_id": "a223c6b3710f85df22e9377d6c4f7553",
    "refresh_token": "3s6lr4kr3cv2od4v853gvrchb875bwxb",
    "scope": "app",
    "server_endpoint": "http://oauth.bitrix24.tech/rest/",
    "status": "T"
}

Значимые данные ответа:

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

На этом этапе приложение может получить ошибку авторизации. Например, если истек пробный или оплаченный период, или приложение было удалено с портала.

{
    "error": "PAYMENT_REQUIRED",
    "error_description": "Payment required"
}

Когда надо обновлять сохраненный токены?

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

Как уже было указано выше, refresh_token сохраняет свою актуальность в течение 180 дней. Это значит, что если ваше приложение по каким-то причинам не обращается к Битрикс24 чаще «само по себе» для реализации функционала приложения, то вам достаточно раз в 180 дней обращаться к серверу авторизации, только чтобы обновить сохраненные токены.

Мы сталкивались со случаями, когда разработчики приложений «на всякий случай» перед каждым обращением к REST сначала «дергали» сервер авторизации для обновления токена. Это неправильный сценарий, создающий лишнюю нагрузку. То же самое касается сценариев с автоматическим «обновлением токенов» раз в час, или раз в сутки — это лишнее.

Более того, создавая лишнюю нагрузку на сервер авторизации, вы рискуете, что ваше приложение в какой-то момент будет заблокировано автоматикой.

Рекомендуемая логика работы с токенами

• Сохраняйте полученные пары access_token и refresh_token токенов на своей стороне;
• Используйте сохраненные access_token для выполнения запросов;
• Если конкретный access_token потерял актуальность, вы получите в ответ соответтствующую ошибку. В этот момент надо:
• Сделать запрос к серверу авторизации на получение новой пары токенов, используя сохраненный refresh_token;
• Сохранить новую пару токенов на своей стороне;
• Повторить запрос к методу REST с теми же параметрами, что и раньше, но с новым access_token.