N8n key

N8n Key: Полное руководство по аутентификации и управлению доступом в платформе автоматизации n8n

N8n — это платформа автоматизации рабочих процессов с открытым исходным кодом, которая использует визуальный редактор для создания интеграций между различными сервисами и приложениями. В контексте n8n термин «key» (ключ) является фундаментальным понятием, относящимся к механизмам аутентификации и авторизации. Ключи используются для безопасного подключения узлов (нод) — строительных блоков рабочих процессов — к внешним API, базам данных и другим сервисам, требующим проверки подлинности. Понимание типов ключей, способов их создания, хранения и управления критически важно для эффективного и безопасного развертывания n8n.

Типы ключей и учетных данных в n8n

В n8n ключи представлены в нескольких формах, в зависимости от типа аутентификации, требуемого конкретным узлом или сервисом. Система аутентификации n8n гибка и поддерживает множество стандартов.

1. API Keys (Ключи API)

Это наиболее распространенный тип ключей. Многие облачные сервисы (например, SendGrid, Twilio, OpenAI, Stripe) предоставляют пользователям уникальные API-ключи для доступа к своим API. В n8n такие ключи вводятся в поля учетных данных соответствующих узлов. N8n обеспечивает их безопасное хранение и автоматически подставляет в заголовки или параметры запросов.

2. OAuth Keys и Tokens (Ключи и Токены OAuth)

Для сервисов, поддерживающих протокол OAuth (например, Google, Microsoft, Salesforce, GitHub), n8n управляет процессом получения токенов доступа (access tokens) и обновления (refresh tokens). Пользователь настраивает OAuth-приложение в стороннем сервисе, получает Client ID и Client Secret, которые затем вводит в n8n. Далее n8n проводит пользователя через процесс согласия, получая токены. Эти токены действуют как динамические ключи для доступа.

3. Учетные данные баз данных

Для узлов баз данных (PostgreSQL, MySQL, MongoDB и др.) ключами являются стандартные параметры подключения: имя пользователя (username), пароль (password), хост (host), порт (port) и название базы данных (database name).

4. SSH Keys (SSH-ключи)

Для доступа к серверам по протоколу SSH, например, при использовании узла «SFTP», могут применяться пары приватных и публичных SSH-ключей. Приватный ключ хранится в n8n в качестве секрета.

5. Access Tokens и Session Keys (Токены доступа и сессионные ключи)

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

Система управления учетными данными (Credentials) в n8n

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

• Создание учетных данных: В редакторе рабочего процесса при настройке узла, требующего аутентификации, пользователь нажимает «Create New Credential». Открывается форма с полями, специфичными для выбранного типа сервиса (API Key, OAuth и т.д.).
• Именование и идентификация: Учетным данным присваивается уникальное имя для удобства выбора в будущем. Это имя видно только внутри n8n.
• Безопасное хранение: По умолчанию n8n шифрует и сохраняет учетные данные в своей базе данных (SQLite, PostgreSQL, MySQL). Для повышения безопасности можно использовать внешние секрет-менеджеры.
• Разделение по средам: Учетные данные привязаны к конкретному экземпляру n8n. Для разделения сред (development, production) необходимо настраивать отдельные экземпляры или вручную управлять разными наборами учетных данных.
• Повторное использование: Созданные однажды учетные данные можно выбирать в любом количестве узлов, что обеспечивает консистентность и упрощает управление.

Безопасность ключей: лучшие практики

Поскольку ключи предоставляют доступ к критически важным сервисам и данным, их безопасность является приоритетом.

Практика	Описание	Реализация в n8n
Использование переменных окружения	Хранение ключей не в интерфейсе n8n, а в переменных окружения операционной системы или контейнера. Это предотвращает их попадание в экспортируемые файлы рабочих процессов.	В полях ввода учетных данных можно использовать выражение {{env.N8N_API_KEY}}. Ключи задаются в файле .env или в настройках контейнера/сервера.
Шифрование секретов	Обеспечение шифрования учетных данных при хранении в базе данных n8n.	Включено по умолчанию с использованием ключа шифрования N8N_ENCRYPTION_KEY. Этот ключ должен быть надежным и храниться отдельно.
Минимальные привилегии	Создание API-ключей в сторонних сервисах с минимально необходимым набором разрешений (Read-Only, доступ к конкретным ресурсам).	Зависит от внешнего сервиса. Необходимо настраивать ключи в панелях управления этих сервисов перед использованием в n8n.
Регулярная ротация ключей	Периодическая замена ключей на новые для снижения ущерба в случае компрометации.	Требует ручного или автоматизированного процесса: создание нового ключа в сервисе, обновление учетных данных в n8n (или переменной окружения) и деактивация старого ключа.
Аудит и логирование	Отслеживание использования ключей и доступа к рабочим процессам.	N8n Enterprise предоставляет расширенные возможности аудита. В облачной версии n8n логи управляются платформой. В self-hosted можно настраивать логи приложения и базы данных.

Интеграция с внешними секрет-менеджерами

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

• HashiCorp Vault: N8n может получать секреты (API-ключи, пароли) непосредственно из Vault, используя его API. Ключи никогда не хранятся в базе данных n8n, а извлекаются динамически при выполнении рабочего процесса.
• AWS Secrets Manager / Azure Key Vault / GCP Secret Manager: Аналогичная интеграция возможна с облачными секрет-менеджерами основных провайдеров. Это требует настройки узла HTTP Request или использования специальных узлов, если они доступны.
• Преимущества: Централизованное управление, автоматическая ротация секретов, детализированный аудит доступа, соответствие стандартам compliance (соответствия требованиям).

Ключи для доступа к самому n8n

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

Тип ключа	Назначение	Как получить
API Key для n8n API	Позволяет внешним приложениям взаимодействовать с API n8n для управления рабочими процессами, выполнения, просмотра данных и т.д. Ключ передается в заголовке запроса.	Генерируется в настройках экземпляра n8n (раздел «API» или «External API») в интерфейсе администратора. Требует настройки ролей и разрешений для пользователя.
Webhook Key	Используется для подписи вебхуков, исходящих из n8n. Позволяет принимающей стороне проверить, что запрос действительно был отправлен из вашего экземпляра n8n.	Настраивается в параметрах триггерного узла Webhook (опция «Add a webhook key»). Это произвольная строка, известная только отправителю и получателю.
Instance Encryption Key	Главный ключ (N8N_ENCRYPTION_KEY) для шифрования всех учетных данных в базе данных. Не является ключом API, но критически важен для безопасности.	Задается как переменная окружения при запуске n8n. Должен быть постоянным и храниться в надежном месте. Смена его требует повторного шифрования всех данных.

Проблемы и устранение неисправностей, связанных с ключами

Распространенные ошибки и их решения.

• «Invalid credentials» (Неверные учетные данные): Убедитесь, что ключ введен правильно, без лишних пробелов. Проверьте, не истек ли срок действия ключа или токена (особенно для OAuth access tokens). Для OAuth используйте узел «Refresh Token» для обновления.
• «Insufficient permissions» (Недостаточно прав): Ключ API, созданный во внешнем сервисе, не имеет необходимых разрешений (scopes). Перейдите в панель управления сервиса и выдайте ключу или OAuth-приложению дополнительные права.
• Проблемы с OAuth: Убедитесь, что в настройках OAuth-приложения правильно указаны callback/redirect URI (должен быть https://your-n8n-domain.com/rest/oauth2-credential/callback). Проверьте Client ID и Client Secret.
• Ключи в экспортированных workflow: При экспорте рабочего процесса (JSON) учетные данные по умолчанию не экспортируются. Они заменяются ссылкой на ID. Это защитная мера. Для переноса используйте функцию «Share Credentials» или настройте ключи через переменные окружения.

Часто задаваемые вопросы (FAQ)

Как безопасно передать рабочий процесс n8n коллеге, не передавая ему мои ключи?

При экспорте workflow в формате JSON учетные данные (ключи) не включаются в файл. В файле сохраняются только ссылки на них. При импорте этого файла на другом экземпляре n8n коллеге будет предложено создать новые учетные данные или выбрать существующие. Для полной безопасности используйте переменные окружения для хранения ключей — в этом случае в настройках узла будут указаны не сами ключи, а ссылки на переменные ({{env.KEY_NAME}}), которые необходимо отдельно настроить на каждом экземпляре.

В чем разница между использованием API Key и OAuth в n8n?

API Key — это статический ключ, который вы генерируете в панели управления сервиса и вставляете в n8n. Он обычно бессрочный, но его можно отозвать. OAuth — это протокол, при котором n8n перенаправляет пользователя на страницу сервиса для входа и получения разрешений, после чего сервис выдает n8n краткосрочный токен доступа (Access Token) и долгосрочный токен обновления (Refresh Token). OAuth безопаснее, так как не требует хранения основного пароля пользователя в n8n, позволяет гибко управлять разрешениями (scopes) и сроком действия доступа. API Key проще в настройке, но часто предоставляет полный доступ, соответствующий правам пользователя, создавшего ключ.

Можно ли автоматически обновлять просроченные OAuth-токены в n8n?

Да, система управления учетными данными n8n для OAuth-сервисов обычно поддерживает автоматическое обновление токенов доступа с использованием токена обновления (Refresh Token). Этот процесс происходит «за кулисами» при попытке выполнения запроса с просроченным токеном. Однако для некоторых сервисов может потребоваться ручная настройка узла «HTTP Request» для выполнения запроса на обновление токена по специальному URL.

Где физически хранятся мои ключи при использовании self-hosted n8n?

По умолчанию, при использовании встроенной базы данных SQLite или внешней (PostgreSQL/MySQL), зашифрованные учетные данные хранятся в таблице credentials_entity. Шифрование осуществляется с помощью ключа, заданного в переменной окружения N8N_ENCRYPTION_KEY. Сами файлы базы данных находятся на диске сервера, где развернут n8n. Если используются переменные окружения, ключи хранятся в памяти процесса и в файле конфигурации (например, .env), который должен быть защищен.

Что делать, если я случайно вставил ключ API в публичный репозиторий GitHub?

Немедленно отзовите (revoke) этот ключ в панели управления соответствующего сервиса (например, в консоли разработчика Google Cloud, настройках GitHub, панели Stripe и т.д.). Большинство сервисов позволяют мгновенно деактивировать старый ключ и создать новый. После этого обновите учетные данные в n8n, используя новый ключ. В будущем всегда используйте переменные окружения для хранения ключей в n8n, чтобы избежать их попадания в экспортированные файлы или скриншоты.