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

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

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

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

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

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

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

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

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

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

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

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

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

Шаги отказа от API-ключей

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Долго ли длиться модерация для публикации/обновления интеграции и зачем она нужна?

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

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

Почему нельзя подгружать JS-код в виджет со сторонних ресурсов, чтобы оперативно менять его на лету под клиентов на своей стороне?

Такой запрет продиктован соображениям безопасности и стабильности системы для пользователей amoCRM. 

1. Нельзя гарантировать, что внешний ресурс будет доступен через какое-то время и по тому же адресу.
2. Фактически возможность подключения внешних JS файлов приведет к бесполезности модерации, т.к. код во внешнем источнике может меняться без нашего контроля.

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

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

Как должно происходить обновление на 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 авторизации закрыты. Подобные массово устанавливаемые решения мы будем рады видеть в нашем маркетплейсе.

Как мы будем загружать приватные виджеты с архивом, если будет скрыт раздел API с 1го июля?

Вы сможете создать приватный виджет, следуя пошаговой инструкции, размещённой в нашей документации.

Что будет с приватными виджетами после 1-го июля 2020-го года?

Для аккаунтов, зарегистрированных до 1-го июля 2020-го года произойдут следующие изменения:

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

– API ключ пользователя будет доступен в JS части виджета.

Для аккаунтов, зарегистрированных после 1-го июля 2020-го года API ключ будет скрыт как в интерфейсе, так и в JS части виджета.

Что будет с публичными интеграциями после 1-го июля 2020-го года?

Те интеграции, что подготовились к работе с oAuth, никак не изменятся.

Другие – будут работать до тех пор, пока у пользователя не сменится API ключ.