oAuth 2.0

Механизм oAuth авторизации пришел на смену устаревшему механизму API-ключей пользователей. Новый механизм должен помочь разработчикам решить ряд задач, которые не решал старый. Основные задачи, которые вы можете решить с помощью механизма oAuth авторизации в amoCRM:

  1. Получить доступ к данным аккаунта в котором вы являетесь администратором “под собой”, используя упрощенную механику авторизации, без использования редиректов. Для простых задач – простые решения.
  2. Получить авторизацию и разрешения от пользователя amoCRM на доступ к данным его аккаунта в соответствии с запрошенными разрешениями.
  3. Регистрировать и авторизовывать пользователя в своем приложении на основе авторизации amoCRM, используя Кнопку входа amoCRM
  4. Загружать виджет в систему для использования в браузере.

Чтобы облегчить процесс интеграции, мы разработали библиотеку для авторизации. На текущий момент мы поддерживаем только написанную на PHP библиотеку, но, нам кажется, что просмотр исходных файлов может подсказать решения и разработчикам на других языках.

Что такое интеграция?

Чтобы ваше приложение/сервис смогли обращаться к API amoCRM, вам необходимо добавить интеграцию в разделе Интеграции в вашем аккаунте. После заполнения минимальной формы amoCRM сгенерирует и отобразит необходимые для авторизации ключи, которые вы сможете использовать в процессе авторизации.
Некоторые ключи являются уникальными для интеграции и будут видны всегда только в том аккаунте, в котором вы создадите эту интеграцию, а аккаунт будет считаться аккаунтом разработчика. При этом все администраторы данного аккаунта смогут редактировать данную интеграцию.

Установленная интеграция

Именно после создания интеграции у нее появляются два уникальных именно для нее параметра. Они будут использоваться независимо от аккаунта, в котором она будет включаться: Secret key и Integration ID, которые в дальнейшем будут использоваться при работе с авторизацией.

Что такое виджет?

Виджет является дополнением интеграции и несет в себе архив с файлами, которые будут подгружены пользователю и будут выполняться в браузере клиента. Архив содержит набор изображений, необходимых для его отображения в разных местах системы, набор языковых файлов, которые необходимы виджету для работы. А также js-файлы, которые будут выполняться и файл manifest.json, в котором описаны основные параметры виджета.

Что такое установка?

Связь интеграции и конкретного аккаунта, в котором была включена интеграция. Интеграция – это отдельный объект. Он связан с аккаунтом разработчика, в котором создали интеграцию. Чтобы интеграция получила доступ к конкретному аккаунту, ее необходимо установить/включить в этом аккаунте.

Как только вы включаете интеграцию в конкретном аккаунте, у этой связки появляется временный идентификатор – Authorization code.

Что такое Authorization code?

Код авторизации необходим для первичного получения пары access и refresh токенов. Доступен в интерфейсе или через Redirect URI, если авторизация прошла через модальное окно предоставления доступов. Срок жизни кода – 20 минут. Этот код не является скрытым, т.е. пользователь может увидеть его в серверных запросов. Именно поэтому в рамках протокола oAuth 2.0 его необходимо обменять на ключи доступа Refresh и Access, используя известные только вам ключи приложения.

В рамках связки интеграция-аккаунт (т.е. установки) может быть несколько Authorization code и несколько связок Access token/Refresh token, т.к. интеграция в одном аккаунте может быть установлена разными администраторами аккаунта одновременно.

Что такое Access token?

Строка в стандарте JSON Web Token, которая позволяет обращаться к сервисам amoCRM от имени определенного пользователя. По сути является аналогом идентификатора сессии.

Каждый токен обязательно содержит:

  1. идентификатор пользователя, к которому привязан токен
  2. идентификатор приложения, к которому привязан токен
  3. набор действий, доступных приложению
  4. идентификатор аккаунта, к которому привязан токен

Токен имеет ограниченный срок жизни (1 сутки) и может быть получен с помощью кода авторизации или Refresh токена.

Что такое Refresh token?

Дополнительная строка, которая выдается вместе с токеном. Refresh токен используется для обновления access токена, время жизни которого истекает. Данный токен имеет срок жизни равный 3 месяцам, при каждом обновлении access token выдается новый refresh token.
Каждый раз по истечении сессии вы обновляете оба ключа, и старым ключем воспользоваться уже будет невозможно. Если пройдет 3 месяца, то мы считаем, что интеграция не используется и refresh token также будет отозван. Это значит, что пользователю, который предоставлял доступ, нужно будет предоставить доступ повторно.


Смотрите также

Возможности платформы
Пример по шагам
Библиотека