Механизм oAuth авторизации пришел на смену устаревшему механизму API-ключей пользователей. Новый механизм должен помочь разработчикам решить ряд задач, которые не решал старый. Основные задачи, которые вы можете решить с помощью механизма oAuth авторизации в amoCRM:
Чтобы облегчить процесс интеграции, мы разработали библиотеку для авторизации. На текущий момент мы поддерживаем только написанную на PHP библиотеку, но, нам кажется, что просмотр исходных файлов может подсказать решения и разработчикам на других языках.
Чтобы ваше приложение/сервис смогли обращаться к API amoCRM, вам необходимо добавить интеграцию в разделе Интеграции в вашем аккаунте. После заполнения минимальной формы 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 также будет отозван. Это значит, что пользователю, который предоставлял доступ, нужно будет предоставить доступ повторно.
