В интеграциях с внешними приложениями часто используется протокол OAuth 2.0. Он позволяет приложению получить доступ к данным пользователя без передачи пароля. В этой статье разбирается практический сценарий: получение access_token , обновление токена, работа с ошибками и использование токена аккаунта для фоновых операций.
Подробная диаграмма последовательности процесса авторизации.
Далее описан алгоритм авторизации по протоколу OAuth 2.0.
1 Инициация - получение параметров аккаунта
Пользователь переходит из страницы настройки интеграции в стороннее приложение. В URL передаются параметры аккаунта: account_id и account_name
Стороннее приложение сохраняет account_id (идентификатор аккаунта) и account_name (наименование аккаунта). Они потребуются при создании подключения и получении токена аккаунта.
2 Перенаправление на сервер аутентификации
Приложение перенаправляет пользователя на сервер аутентификации для получения кода авторизации — authorization code :
Параметры запроса:
client_id
Идентификатор стороннего приложения
redirect_uri
URL, на который сервер авторизации перенаправляет пользователя после успешной авторизации.
scope
Запрашиваемые права стороннего приложения
state
Защита от подделки
После успешного входа сервер возвращает временный код авторизации, который может быть использован только один раз — authorization code . Время жизни кода ограничено.
3 Получение access_token и refresh_token (обмен кода на токены)
Сервер стороннего приложения выполняет POST-запрос к серверу аутентификации:
Параметры запроса:
code
Временный код, полученный на предыдущем шаге
grant_type
authorization_code
redirect_uri
URL возврата (должен совпадать с указанным ранее)
В ответе приходит json с access_token и refresh_token . Формат успешного ответа, если access_token получен:
Параметры ответа:
token_type
user_id
Уникальный идентификатор пользователя
expires_in
Время жизни access_token в секундах
expires_at
Дата и время истечения access_token
access_token
Токен доступа (короткоживущий, обычно 1 час)
refresh_token
Токен для обновления access_token (долгоживущий)
refresh_expires_in
Время жизни refresh_token в секундах
refresh_expires_at
Дата и время истечения refresh_token
Формат ответа при ошибке
После получения access_token приложение создаёт подключение в ресурсном сервере:
В случае успешного запроса, в ответе вернется app_id — идентификатор подключения.
Срок жизни access_token ограничен. После истечения срока жизни токена пользователю необходимо вновь пройти авторизацию. Чтобы не проходить авторизацию заново, когда access_token истекает, его обновляют через refresh_token . refresh_token всегда выдается с access_token в одном ответе.
В результате токен обновится или появится информация об ошибке.
После получения access_token приложение создаёт подключение в ресурсном сервере с помощью запроса:
В случае успешного запроса, в ответе вернется app_id — идентификатор подключения.
5 Токен аккаунта для фоновых процессов
После получения пользовательского access_token и refresh_token возникает вопрос: что делать, если интеграции нужно работать в фоне — без участия пользователя? В таких случаях используется токен аккаунта ( account_token ).
Без токена аккаунта фоновые операции привязаны к конкретному пользователю. Если пользователь выйдет из системы или его сессия истечёт — интеграция перестанет работать. Токен аккаунта привязан не к пользователю, а к аккаунту, и может работать независимо.
Пример запроса на получение access_token аккаунта
Что важно учесть
Для фоновых операций используй токен аккаунта — он не привязан к сессии пользователя и подходит для автоматических сценариев.
Для фоновых операций используй токен аккаунта — он не привязан к сессии пользователя и подходит для автоматических сценариев.
access_token имеет ограниченный срок жизни — следует обновлять его заранее через refresh_token , чтобы избежать сбоев в работе интеграции
access_token имеет ограниченный срок жизни — следует обновлять его заранее через refresh_token , чтобы избежать сбоев в работе интеграции
Не выводить токены в логи
Не выводить токены в логи
Заложить права доступа не только на сервере, но и в приложении, чтобы корректно обрабатывать ошибки
Заложить права доступа не только на сервере, но и в приложении, чтобы корректно обрабатывать ошибки