oAuth 2.0

OAuth 2.0 – это протокол авторизации, позволяющий приложениям получать ограниченный доступ к учетным записям пользователей. В рамках данного протокола можно выделить следующие роли:

  • Владелец (пользователь): предоставляет приложению доступ к данным своей учетной записи;
  • Сервер ресурсов: здесь находятся данные аккаунтов пользователей, а также бизнес-логика авторизации, которая отвечает за выдачу OAuth-токенов и проверку их подлинности;
  • Клиентское приложение: сторонний сервис, нуждающийся в правах доступа к данным пользователя, которые в свою очередь находятся на сервере ресурсов. Пользователь должен авторизовать приложение. В процессе авторизации, приложение со стороны сервера ресурсов должно получить подтверждение об успешной авторизации в виде ключа (токена) доступа.

Как правило, авторизация oAuth подразумевает выполнение следующих шагов:

  1. Приложение запрашивает у пользователя разрешение на доступ к серверу ресурсов.
  2. После получения разрешения приложение сообщает об этом авторизационному серверу, а также предоставляет ему сведения о себе.
  3. Сервер авторизации проверяет подлинность разрешения и предоставленных сведений о приложении. В случае успешной проверки генерируется токен доступа.
  4. Далее приложение обращается к серверу ресурсов, предоставляя токен в качестве подтверждения пройденной авторизации.
  5. Сервер ресурсов проверяет действительность токена и выдает приложению доступ к запрашиваемому ресурсу.

OAuth в amoCRM

Аккаунт пользователя – это любая учетная запись amoCRM, которая в терминах OAuth представляет владельца (пользователя). Ваша интеграция здесь является клиентским приложением. Она будет получать доступ к данным аккаунта пользователя, существующего на серверах amoCRM (сервер ресурсов), в соответствии с запрошенными и предоставленными разрешениями. Посмотреть реализацию авторизации через oAuth вы можете на странице с пошаговым примером.

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

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

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

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

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

Запись токенов в базу данных

При записи данных для авторизации мы не рекомендуем обращать внимание на количество символов, так как само количество может варьироваться в зависимости от множества внутренних факторов, поэтому, записывая значения данных в БД, используйте тип text.


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

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