OAuth 2.0 – это протокол авторизации, позволяющий приложениям получать ограниченный доступ к учетным записям пользователей. В рамках данного протокола можно выделить следующие роли:
Как правило, авторизация oAuth подразумевает выполнение следующих шагов:
Аккаунт пользователя – это любая учетная запись amoCRM, которая в терминах OAuth представляет владельца (пользователя). Ваша интеграция здесь является клиентским приложением. Она будет получать доступ к данным аккаунта пользователя, существующего на серверах amoCRM (сервер ресурсов), в соответствии с запрошенными и предоставленными разрешениями. Посмотреть реализацию авторизации через oAuth вы можете на странице с пошаговым примером.
Механизм oAuth авторизации пришел на смену устаревшему механизму API-ключей пользователей. Новый механизм должен помочь разработчикам решить ряд задач, которые не решал старый. Основные задачи, которые вы можете решить с помощью механизма oAuth авторизации в amoCRM:
Чтобы облегчить процесс написания кода интеграции, мы разработали библиотеку для авторизации. На текущий момент мы поддерживаем только написанную на PHP библиотеку, но, нам кажется, что просмотр исходных файлов может подсказать решения и разработчикам на других языках.
Чтобы ваше приложение/сервис смогли обращаться к API amoCRM, вам необходимо добавить интеграцию в вашем аккаунте. Сделать это можно нажав на три точки в правом верхнем углу, находясь в разделе amoMarket. После заполнения минимальной формы amoCRM сгенерирует и отобразит необходимые для авторизации ключи, которые вы сможете использовать в процессе авторизации.
Некоторые ключи являются уникальными для интеграции и будут видны всегда только в том аккаунте, в котором вы создадите эту интеграцию, а аккаунт будет считаться аккаунтом разработчика. При этом все администраторы данного аккаунта смогут редактировать данную интеграцию.
После создания интеграции у нее появятся два уникальных параметра: Secret key и Integration ID. Они будут использоваться при авторизации независимо от аккаунта, в котором интеграция будет установлена.
Виджет является дополнением интеграции и несет в себе архив с файлами, которые будут подгружены пользователю и будут выполняться в браузере клиента. Архив содержит набор изображений, необходимых для его отображения в разных местах системы, набор языковых файлов, которые необходимы виджету для работы. А также js-файлы, которые будут выполняться и файл manifest.json, в котором описаны основные параметры виджета.
Связь интеграции и конкретного аккаунта, в котором была включена интеграция. Интеграция – это отдельный объект. Он связан с аккаунтом разработчика, в котором создали интеграцию. Чтобы интеграция получила доступ к конкретному аккаунту, ее необходимо установить/включить в этом аккаунте.
Как только вы включаете интеграцию в конкретном аккаунте, у этой связки появляется временный идентификатор – Authorization code.
Код авторизации необходим для первичного получения пары access и refresh токенов. Доступен в интерфейсе или через Redirect URI, если авторизация прошла через модальное окно предоставления доступов. Срок жизни кода – 20 минут. Этот код не является скрытым, т.е. пользователь может увидеть его в серверных запросов. Именно поэтому в рамках протокола oAuth 2.0 его необходимо обменять на ключи доступа Refresh и Access, используя известные только вам ключи приложения.
В рамках связки интеграция-аккаунт (т.е. установки) может быть несколько Authorization code и несколько связок Access token/Refresh token, т.к. интеграция в одном аккаунте может быть установлена разными администраторами аккаунта одновременно.
Строка в стандарте JSON Web Token, которая позволяет обращаться к сервисам amoCRM от имени определенного пользователя. По сути является аналогом идентификатора сессии.
Каждый токен обязательно содержит:
Токен имеет ограниченный срок жизни (1 сутки) и может быть получен с помощью кода авторизации или Refresh токена.
Дополнительная строка, которая выдается вместе с токеном. Refresh токен используется для обновления access токена, время жизни которого истекает. Данный токен имеет срок жизни равный 3 месяцам, при каждом обновлении access token выдается новый refresh token.
Каждый раз по истечении сессии вы обновляете оба ключа, и старым ключем воспользоваться уже будет невозможно. Если пройдет 3 месяца, то мы считаем, что интеграция не используется и refresh token также будет отозван. Это значит, что пользователю, который предоставлял доступ, нужно будет предоставить доступ повторно.
При записи данных для авторизации мы не рекомендуем обращать внимание на количество символов, так как само количество может варьироваться в зависимости от множества внутренних факторов, поэтому, записывая значения данных в БД, используйте тип text.
