C 1 июля 2020 года мы перестали выводить в интерфейсе API-ключи. Если ваша интеграция до сих пор использует авторизацию по API-ключам, вам необходимо адаптировать код вашей интеграции под oAuth авторизацию.

Цель перехода

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

В том числе, он поможет нам с вами, нашим клиентам, нашим Заказчикам, нашим Разработчикам:

• прозрачно понимать какому стороннему сервису предоставлен тот или иной доступ к данным на текущий момент. Отзывать ненужные доступы;

• идентифицировать отдельно запросы от различных интеграций и устранять влияние одних интеграций на другие (речь и про блокировку аккаунтов, а не конкретных интеграций, и про разбор логов запросов и т.д.);

• больше не ломать связку интеграции при автоматической смене ключа во время смены пароля пользователя;

• давать пользователям четкое понимание в какой момент и в каком объеме будет предоставлен доступ к данным и какому сервису;

• повысить безопасность и за счет постоянного истечения действия токенов, и за счет изоляции их между аккаунтами, и за счет изоляции WEB-запросов и API.

и многое другое.

Для облегчения процесса перехода мы создали инструменты, одним из таких инструментов является PHP библиотека, в которой реализован интерфейс работы с oAuth 2.0

Также мы предусмотрели метод для обмена старых API ключей на oAuth токены. Для того, чтобы не беспокоить наших общих пользователей.

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

Отказ от API-ключей

В интерфейсе пользователя мы перестали выводить API-ключ. Также ключ более не доступен в переменных окружения.

В любом случае отсутствие API-ключа на новых аккаунтах не позволит производить подключение существующих интеграций по старой схеме.

Что нужно сделать разработчику приватной интеграции, чтобы перейти на механику oAuth?

Для всех приватных интеграций мы сгенерировали ключи для oAuth авторизации.

• Если вы не используете обращения к backend amoCRM, а просто используете JS-виджет, то делать ничего не нужно

• Если вы используете API-ключи, то вам нужно дописать в обращениях к API amoCRM логику авторизации используя нашу официальную библиотеку или любую удобную для вас библиотеку реализующую oAuth 2.0. Все ключи вы сможете найти в окне интеграции во вкладке "Ключи"

Если ваша интеграция установлена в большом количестве аккаунтов и содержит JS-архив виджета, то мы рекомендуем следующий подход:

1. Доработать backend часть интеграции, чтобы она могла одновременно работать с двумя типами авторизации.
2. Составить инструкцию для администраторов аккаунтов, чтобы они смогли передать секретные ключи интеграции вам безопасным способом и вы осуществили переезд на новые ключи. Наилучшим способом является работа из-под выделенного технического пользователя в аккаунте.

Если интеграция установлена в большом количестве аккаунтов и НЕ содержит JS- виджет, то вы можете воспользоваться механизмом Внешних интеграций.

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

Если интеграция установлена в большом количестве аккаунтов, то, возможно, стоит задуматься о переводе виджета из приватной плоскости в публичную, что значительно упростит возможность его дистрибуции.

Где взять секретный ключи и ID интеграции?

Секретный ключ и ID интеграции можно увидеть в окне интеграции, в разделе “Ключи”. Данные параметры уникальны для вашей интеграции, и с их помощью вы можете обменять код авторизации на токен доступа к данным аккаунта через метод, описанный в статье "Пример по шагам"..

Если мы сконвертируем API ключ, доступ по API ключу становится недоступен?

После обмена старого API ключа через метод обмена API ключей, API ключ не деактивируется и может быть использован до смены пароля пользователем. Единственное связанное ограничение – использовать метод обмена API ключей для одного и того же пользователя одна и та же интеграция может не чаще, чем раз в 5 минут. В данный момент количество вызовов метода не ограничено.

Нужен ли флаг (галочка) подтверждающая передачу данных пользователя стороннему сервису?

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

Как должно происходить обновление на oAuth для публичных интеграций?

1. Сначала вам необходимо подготовить свой backend для работы с использованием oAuth ключей amoCRM одновременно со старым механизмом.
2. Затем, в том методе, который принимает login и api_key пользователя необходимо, при каждом входящем запросе конвертировать их при помощи метода обмена API ключа, а также обменять все существующие ключи.
3. Следующим шагом, необходимо на своём backend подготовить endpoint для redirect_url, а затем указать его в настройках интеграции.
4. Последним этапом будет полное удаление методов и таблиц, которые связаны со старыми авторизационными данными.

Нужны ли oAuth ключи при отправке запросов из script.js?

Нет, при отправке запросов из интерфейса вы действуете от имени текущего пользователя amoCRM.

В какой момент уходит хук oAuth при установке виджета?

Сразу, как пользователь нажмёт на кнопку "Установить" в модальном окне виджета.

В какой момент уходит хук oAuth при установке отраслевого решения?

Хук уходит сразу после того, как пользователь нажимает на кнопку "Завершить" в туре отраслевого решения, затем происходит вызов callback "finish_wizard" в вашем виджете. Важно отметить, что код авторизации в данный момент отправляется асинхронно от вызова callback "finish_wizard".

То есть в отраслевом решении мы блокируем использование методов API до того момента, пока пользователь в туре окончательно не подтвердит намерение установить отраслевое решение, и возможности отката к стандартному туру у него не останется. В этот момент управление и доступы будут переданы интеграции отраслевого решения для настройки аккаунта.

Как распространять приватные виджеты по аккаунтам?

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

Если вы хотите самостоятельно заниматься распространением виджетов собственной разработки, не размещая их в маркетплейс amoCRM, то вам доступны следующие варианты распространения:

• Создать подробную инструкцию для вашего клиента, с информацией о том, как ему самостоятельно создать интеграцию и загрузить архив, если он необходим.

• Воспользоваться техническим пользователем, который предоставляется в рамках партнёрской программы amoCRM. Для этого необходимо попросить вашего клиента, добавить вашего технического пользователя к себе в аккаунт как администратора. Вы же, от имени этого технического пользователя, имеете возможность настраивать аккаунт под потребности клиента, в т.ч. и заниматься установкой виджетов.

Приватные методы, которые раньше позволяли скрыто от пользователей устанавливать в аккаунты приватные интеграции используя API-ключ пользователя для нового механизма oAuth авторизации закрыты.
Подобные массово устанавливаемые решения мы будем рады видеть в нашем маркетплейсе.