N8n auth

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

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

Архитектура системы аутентификации N8n

Система аутентификации N8n построена вокруг двух ключевых концепций: типов учетных данных (Credential Types) и самих учетных данных (Credentials). Тип учетных данных — это шаблон, который определяет, какие поля (например, API Key, OAuth Client ID, Secret, Username, Password) необходимы для подключения к конкретному сервису (например, Slack, Google Sheets, PostgreSQL). Сами Учетные данные — это экземпляры, где хранятся фактические секретные значения, введенные пользователем. Эти данные шифруются и сохраняются в базе данных N8n. Когда вы добавляете узел, требующий аутентификации, вы можете выбрать из существующих учетных данных или создать новые, что позволяет повторно использовать одни и те же учетные данные в разных рабочих процессах.

Основные методы аутентификации в N8n

N8n поддерживает широкий спектр методов аутентификации, адаптированных под возможности различных API.

1. Аутентификация с помощью API ключа (API Key Auth)

Наиболее распространенный метод. API-ключ обычно передается в заголовках HTTP-запроса (Headers) или в параметрах запроса (Query). В настройках узла это выглядит как добавление поля, например, `X-API-Key` со значением, хранящимся в учетных данных.

Где используется: Почти все сервисы, такие как Make (Integromat), Telegram, многие REST API.
Настройка: Пользователь вводит ключ в специальное поле при создании учетных данных. N8n автоматически подставляет его в нужное место запроса.

2. OAuth 1.0a и OAuth 2.0

Сложные, но стандартные протоколы для делегированного доступа. N8n обладает встроенной поддержкой OAuth для многих популярных сервисов (Google, GitHub, Microsoft 365).

OAuth 2.0: Пользователь нажимает кнопку «Connect» в настройках узла, перенаправляется на страницу сервиса-провайдера для авторизации, после чего N8n получает access token и refresh token. Токен обновляется автоматически.
OAuth 1.0a: Используется для таких сервисов, как Twitter (X). Требует Consumer Key, Consumer Secret, Access Token и Access Token Secret.
Преимущество: Пользователь не передает свой пароль, а доступ можно ограничить по времени и scope (области действий).

3. Базовая аутентификация (HTTP Basic Auth)

Метод, при котором в заголовок запроса добавляется строка `Authorization: Basic `, где строка — это логин и пароль, разделенные двоеточием. N8n автоматически выполняет кодирование в base64.

4. Аутентификация по паролю (Username/Password)

Используется для баз данных (MySQL, PostgreSQL) и некоторых API. Логин и пароль передаются в теле запроса или в параметрах соединения.

5. Собственная аутентификация (Custom Auth)

Для API с нестандартными схемами N8n позволяет вручную настроить заголовки, тело запроса или параметры. Часто используется в узле «HTTP Request».

6. Аутентификация с помощью токена доступа (Bearer Token)

Частный случай аутентификации через заголовок, где используется заголовок `Authorization: Bearer `. Широко применяется в современных API после получения токена через OAuth 2.0.

Таблица сравнения методов аутентификации

Метод	Сложность настройки	Безопасность	Типичное применение	Обновление токенов
API Key	Низкая	Средняя (ключ часто имеет широкие права)	Внешние API, сервисы SaaS	Вручную
OAuth 2.0	Высокая (требует предварительной регистрации приложения у провайдера)	Высокая (ограниченные scope, refresh tokens)	Google, Microsoft, GitHub, Facebook	Автоматическое
Basic Auth	Низкая	Низкая (пароль передается в кодировке, но не шифруется)	Старые API, некоторые веб-сервисы	Вручную
Username/Password	Низкая	Низкая/Средняя (зависит от протокола)	Базы данных, FTP, SSH	Вручную

Безопасное хранение и управление учетными данными

N8n использует несколько уровней защиты для учетных данных:

Шифрование: Все секретные значения (пароли, ключи, токены) шифруются с помощью алгоритма AES-256-GCM перед сохранением в базу данных. Ключ шифрования по умолчанию хранится в переменной окружения `N8N_ENCRYPTION_KEY`.
Изоляция: Учетные данные привязаны к владельцу (пользователю) в облачной версии или к экземпляру в self-hosted. Они никогда не отображаются в открытом виде в интерфейсе после сохранения.
Переменные окружения: Для максимальной безопасности (особенно в CI/CD) секреты можно хранить в переменных окружения сервера и ссылаться на них в рабочих процессах через выражения, например, `{{ $env.MY_API_KEY }}`.

Практическое руководство по настройке OAuth 2.0 для Google Сервисов

Создание проекта в Google Cloud Console: Создайте новый проект или выберите существующий. Активируйте нужный API (например, Google Drive API).
Настройка экрана согласия OAuth: Укажите название приложения, email поддержки, области авторизации (scopes).
Создание учетных данных OAuth 2.0: Выберите тип приложения «Веб-приложение». Добавьте URI перенаправления. Для self-hosted N8n это будет `https://your-n8n-domain.com/rest/oauth2-credential/callback`. Скопируйте Client ID и Client Secret.
Настройка в N8n: В узле Google Drive (или другом) создайте новые учетные данные. Выберите «OAuth2». Вставьте Client ID и Client Secret. Нажмите «Connect» и пройдите процесс авторизации в открывшемся окне Google.
Завершение: После согласия N8n сохранит токены, и узел будет готов к работе.

Работа с собственными (кастомными) API через HTTP Request узел

Узел «HTTP Request» является универсальным инструментом для подключения к любым API. Его настройки аутентификации включают:

Authentication: Выпадающий список с вариантами: None, Generic Credential, Basic Auth, Header Auth, OAuth1, OAuth2.
Generic Credential Type: Позволяет создать свой тип учетных данных с произвольными полями (например, `X-Custom-Token`). Эти поля затем можно использовать в заголовках или параметрах запроса.
Ручное добавление заголовков: В разделе «Headers» можно напрямую добавить `Authorization: Bearer {{ $secrets.MY_TOKEN }}`.

Аутентификация для баз данных

Узлы для баз данных (PostgreSQL, MySQL) используют аутентификацию по логину и паролю, а также SSL-шифрование. Учетные данные содержат хост, порт, имя базы данных, пользователя и пароль. Рекомендуется использовать SSL и, по возможности, помещать пароль в переменные окружения.

Проблемы и отладка аутентификации

«Invalid credentials» (Неверные учетные данные): Проверьте правильность ввода ключей, срок действия токенов. Для OAuth попробуйте переподключиться.
OAuth flow не запускается: Убедитесь, что корректно указаны redirect URI в провайдере и в N8n. Проверьте настройки Client ID и Secret.
Проблемы с правами доступа (scopes): Удалите учетные данные и создайте заново, запросив нужные области доступа.
Использование Debug режима: В узле HTTP Request включите опцию «Send Headers» в Debug-режиме, чтобы увидеть, какие заголовки фактически отправляются на сервер.

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

В корпоративной среде для хранения секретов часто используются внешние системы (HashiCorp Vault, AWS Secrets Manager). N8n может работать с ними косвенно: секрет из менеджера извлекается на этапе развертывания и устанавливается в переменную окружения N8n, либо с помощью узла HTTP Request делается запрос к API Vault для получения секрета в рантайме.

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

Вопрос: Где физически хранятся мои пароли и API ключи в N8n?

Ответ: Секретные данные хранятся в зашифрованном виде в базе данных вашего экземпляра N8n (по умолчанию SQLite или PostgreSQL). Ключ шифрования управляется переменной окружения `N8N_ENCRYPTION_KEY`. Никогда не храните ключ по умолчанию в продакшене.

Вопрос: Можно ли использовать один набор учетных данных для нескольких разных узлов и рабочих процессов?

Ответ: Да, это одна из ключевых возможностей. Создав учетные данные для, например, Slack, вы можете выбрать их в любом узле Slack в любом рабочем процессе на этом экземпляре N8n.

Вопрос: Что делать, если мой OAuth токен устарел или отозван?

Ответ: В интерфейсе N8n перейдите в раздел «Credentials». Найдите проблемные учетные данные. Обычно там будет кнопка «Reconnect» или «Update». Нажмите ее, чтобы повторно пройти процесс OAuth. N8n автоматически обновляет access token с помощью refresh token, если это предусмотрено провайдером и refresh token еще валиден.

Вопрос: Как безопасно работать с N8n в команде, чтобы не делиться секретами?

Ответ: В облачной версии N8n есть управление доступом. В self-hosted версии можно:

Использовать переменные окружения для секретов и делиться только именами переменных.
Экспортировать рабочие процессы без учетных данных (опция при экспорте).
Рассмотреть возможность использования Enterprise-версии с расширенным управлением доступом.

Вопрос: Поддерживает ли N8n двухфакторную аутентификацию (2FA) для внешних сервисов?

Ответ: Да, но не напрямую. Если сервис требует 2FA, процесс аутентификации обычно происходит во время OAuth flow или при создании специального ключа приложения (как в Google Account). Вам нужно использовать App Password или OAuth, которые обходят необходимость ввода 2FA кода при каждом запросе API.

Вопрос: Как настроить аутентификацию для самописного (custom) REST API?

Ответ: Используйте узел «HTTP Request». В зависимости от метода API:

Для API Key: Выберите «Header Auth» и укажите имя заголовка и значение.
Для Bearer Token: Выберите «Header Auth», установите имя заголовка как `Authorization`, а значение как `Bearer your_token`.
Для сложных схем создайте «Generic Credential Type» в настройках N8n (требуются административные права).

Вопрос: Можно ли автоматически обновлять учетные данные через API N8n?

Ответ: Да, N8n предоставляет REST API для управления учетными данными. Это позволяет интегрировать ротацию секретов из внешних систем. Однако это требует careful реализации и использования API ключа самого N8n с соответствующими правами.

В заключение, система аутентификации N8n представляет собой гибкий, безопасный и мощный механизм, способный удовлетворить требования интеграции с подавляющим большинством современных API и сервисов. Понимание ее принципов — от базовых методов вроде API Key до сложных OAuth 2.0 flow — является ключом к созданию надежных, безопасных и эффективных автоматизированных рабочих процессов. Рекомендуется всегда следовать принципу наименьших привилегий при выдаче прав учетным данным и использовать максимальный уровень безопасности, доступный в целевом сервисе.