С 1 июля мы перестанем выводить в интерфейсе API-ключи. Таким образом все уже установленные интеграции смогут продолжить работу до смены пароля пользователя из-под которого они работают.
Механизм API ключей прожил с нами практически все время, начиная со старта нашего проекта. Предоставил возможность разработки десятков и сотен тысяч различных интеграций. Но, к счастью, на его смену пришли новые инструменты, новые механизмы, новые требования по безопасности. На его смену пришел более безопасный, лишенный многих минусов API ключей механизм oAuth авторизации.
В том числе, он поможет нам с вами, нашим клиентам, нашим Заказчикам, нашим Разработчикам:
– прозрачно понимать какому стороннему сервису предоставлен тот или иной доступ к данным на текущий момент. Отзывать ненужные доступы;
– идентифицировать отдельно запросы от различных интеграций и устранять влияние одних интеграций на другие (речь и про блокировку аккаунтов, а не конкретных интеграций, и про разбор логов запросов и т.д.);
– больше не ломать связку интеграции при автоматической смене ключа во время смены пароля пользователя;
– давать пользователям четкое понимание в какой момент и в каком объеме будет предоставлен доступ к данным и какому сервису;
– повысить безопасность и за счет постоянного истечения действия токенов, и за счет изоляции их между аккаунтами, и за счет изоляции WEB-запросов и API.
и многое другое.
Для облегчения процесса перехода мы создали инструменты, одним из таких инструментов является PHP библиотека, в которой реализован интерфейс работы с oAuth 2.0
Также мы предусмотрели метод для обмена старых API ключей на oAuth токены. Для того, чтобы не беспокоить наших общих пользователей.
Чтобы еще больше облегчить жизнь разработчику, кроме инструкций ниже, мы хотели бы привести ряд вопросов, которые волнуют вас. Этот список будет пополняться. Таким образом мы сможем охватить вместе с вами большинство тем, и предоставить вам ответы на вопросы.
1 июля во всех аккаунтах для всех пользователей в интерфейсе больше не будет выводится API-ключ. Также ключ не будет доступен в переменных окружения. Мы очень аккуратно относимся к работоспособности уже подключенных интеграций, поэтому на части старых аккаунтов API-ключ останется в переменных окружения на дополнительный месяц.
В любом случае отсутствие API-ключа на новых аккаунтах не позволит производить подключение существующих интеграций по старой схеме.
Для всех приватных интеграций мы сгенерировали ключи для oAuth авторизации. Сами интеграции переехали из раздела API в раздел Интеграции.
– Если вы не используете обращения к backend amoCRM, а просто используете JS-виджет, то делать ничего не нужно
– Если вы используете API-ключи, то вам нужно дописать в обращениях к API amoCRM логику авторизации используя нашу официальную библиотеку или любую удобную для вас библиотеку реализующую oAuth 2.0. Все ключи вы сможете найти в разделе Интеграции, кликнув на нужную интеграцию и перейдя во вкладку Ключи
Если ваша интеграция установлена в большом количестве аккаунтов и содержит JS-архив виджета, то мы рекомендуем следующий подход:
Если интеграция установлена в большом количестве аккаунтов и НЕ содержит JS- виджет, то вы можете воспользоваться механизмом Внешних интеграций.
Если интеграция установлена в большом количестве аккаунтов, то, возможно, стоит задуматься о переводе виджета из приватной плоскости в публичную, что значительно упростит возможность его дистрибуции.
Где взять секретный ключи и ID интеграции?
Секретный ключ и ID интеграции можно увидеть в модальном окне интеграции, в вашем аккаунте. Для этого необходимо перейти в раздел “Настройки” -> “Интеграции”, кликнуть на название интеграции, а затем на перейти в раздел “Ключи”. Они уникальны для вашей интеграции, и с их помощью вы можете обменять код авторизации на токен доступа к данным аккаунта через метод, описанный в разделе “oAuth” документации для разработчиков под заголовком “Обмен кода авторизации”.
После обмена старого API ключа через метод обмена API ключей, API ключ не деактивируется и может быть использован до смены пароля пользователем. Единственное связанное ограничение – использовать метод обмена API ключей для одного и того же пользователя одна и та же интеграция может не чаще, чем раз в 5 минут. В данный момент количество вызовов метода не ограничено.
В среднем модерация занимает 1-2 рабочих дня. Мы не только аудируем код, но и тестируем функционально новое приложение. Если есть замечания и не соответствия требованиям, то, после проверки, мы сообщаем о всех замечания, которые необходимо устранить для повторной модерации. Данная процедура необходима для того, чтобы конечный пользователь получил качественный и безопасный продукт, следовательно это плюсы для всех сторон. Для того, чтобы этап модерации занимал меньше времени, рекомендуем ознакомится с требованиями к публичной интеграции.
Как ни странно, самой частой причиной для не успешного прохождения модерации и возврата интеграции на доработку является наличие вывода логов в консоль браузера.
Такой запрет продиктован соображениям безопасности и стабильности системы для пользователей amoCRM.
На данный момент можно заменить галочку подтверждения передачи данных на информирование и ссылку на политику конфиденциальности, в таком виде виджет пройдет модерацию в маркетплейс. Также, на данный момент мы прорабатываем общий механизм согласия к предоставлению доступа интеграции к данным для пользователей, чтобы сделать этот процесс универсальным и прозрачным для всех пользователей.
Нет, при отправке запросов из интерфейса вы действуете от имени текущего пользователя amoCRM.
Сразу, как пользователь нажмёт на кнопку “Установить” в модальном окне виджета.
Хук уходит сразу после того, как пользователь нажимает на кнопку “Завершить” в туре отраслевого решения, затем происходит вызов callback “finish_wizard” в вашем виджете. Важно отметить, что код авторизации в данный момент отправляется асинхронно от вызова callback “finish_wizard”.
То есть в отраслевом решении мы блокируем использование методов API до того момента, пока пользователь в туре окончательно не подтвердит намерение установить отраслевое решение, и возможности отката к стандартному туру у него не останется. В этот момент управление и доступы будут переданы интеграции отраслевого решения для настройки аккаунта.
Если у вас менее 10 клиентов, то, в данном случае, установка и обновления в каждом аккаунте не должны занимать много времени. Если у вас более 10 клиентов, то вы можете опубликовать интеграцию в нашем маркетплейс и стать публичным, что позволит вам делать подобные установки намного проще, а также стать доступными и для других клиентов.
Если вы хотите самостоятельно заниматься распространением виджетов собственной разработки, не размещая их в маркетплейс amoCRM, то вам доступны следующие варианты распространения:
– Создать подробную инструкцию для вашего клиента, с информацией о том, как ему самостоятельно создать интеграцию и загрузить архив, если он необходим.
– Воспользоваться техническим пользователем, который предоставляется в рамках партнёрской программы amoCRM. Для этого необходимо попросить вашего клиента, добавить вашего технического пользователя к себе в аккаунт как администратора. Вы же, от имени этого технического пользователя, имеете возможность настраивать аккаунт под потребности клиента, в т.ч. и заниматься установкой виджетов.
Приватные методы, которые раньше позволяли скрыто от пользователей устанавливать в аккаунты приватные интеграции используя API-ключ пользователя для нового механизма oAuth авторизации закрыты. Подобные массово устанавливаемые решения мы будем рады видеть в нашем маркетплейсе.
Вы сможете создать приватный виджет, следуя пошаговой инструкции, размещённой в нашей документации.
Для аккаунтов, зарегистрированных до 1-го июля 2020-го года произойдут следующие изменения:
– В интерфейсе будет скрыт API ключ пользователя.
– API ключ пользователя будет доступен в JS части виджета.
Для аккаунтов, зарегистрированных после 1-го июля 2020-го года API ключ будет скрыт как в интерфейсе, так и в JS части виджета.
Те интеграции, что подготовились к работе с oAuth, никак не изменятся.
Другие – будут работать до тех пор, пока у пользователя не сменится API ключ.