Zarządzanie Credentialami w N8N

Spis treści

1. Czym są credentiale w N8N?

2. Jak N8N przechowuje i szyfruje credentiale?

3. Typy credentiali — kompletny przegląd

4. Pierwsze kroki: tworzenie i edycja credentiali

5. OAuth2 — konfiguracja krok po kroku

6. Klucze API, tokeny Bearer i Basic Auth

7. Credentiale przez zmienne środowiskowe

8. Udostępnianie credentiali między użytkownikami

9. Bezpieczeństwo — najlepsze praktyki

10. Integracja z zewnętrznymi Vault

11. Debugowanie i rozwiązywanie problemów

12. Migracja credentiali między instancjami

13. FAQ — najczęściej zadawane pytania

14. Słownik pojęć

1. Czym są credentiale w N8N?

Credentiale w N8N to zaszyfrowane zestawy danych uwierzytelniających, które umożliwiają węzłom (nodes) bezpieczne łączenie się z zewnętrznymi usługami, API i systemami. Są fundamentem każdej automatyzacji — bez nich żaden workflow nie może komunikować się ze światem zewnętrznym.

N8N obsługuje ponad 400 predefiniowanych typów credentiali dla różnorodnych usług: od Google Workspace i Microsoft 365, przez Slack i Notion, po bazy danych PostgreSQL, systemy CRM jak Salesforce i HubSpot, bramki płatności, serwisy AI jak OpenAI i Anthropic, aż po własne REST API budowane przez programistów.

Bezpłatne warsztaty: Kali Linux od podstaw - fundament pracy pentestera

Naucz się instalacji i konfiguracji Kali Linux, pracy w terminalu, zarządzania uprawnieniami, budowy własnego laboratorium pentestowego oraz korzystania z narzędzi używanych przez specjalistów cyberbezpieczeństwa.

Odbierz dostęp do 13 maja do 23:59

Sprawdź szczegóły: https://asdevops.pl/warsztaty/

Kluczowe właściwości systemu credentiali N8N

Szyfrowanie AES-256-CBC — każdy credential jest szyfrowany przed zapisem do bazy danych. Bez klucza szyfrowania dane są niemożliwe do odczytania.
Maskowanie wartości — po zapisaniu credentiala N8N nigdy nie wyświetla jego wartości w postaci jawnej w interfejsie użytkownika.
Izolacja od logów — wartości credentiali nie pojawiają się w historii wykonań workflowu ani w logach systemowych.
Automatyczny refresh tokenów OAuth2 — N8N automatycznie odnawia wygasające tokeny bez interwencji użytkownika.
Współdzielenie z kontrolą dostępu — w trybie multi-user można precyzyjnie przydzielać dostęp do credentiali konkretnym użytkownikom lub projektom.
Reużywalność — jeden credential może być używany przez dowolną liczbę workflowów i węzłów jednocześnie.

Definicja. Credential w N8N to zaszyfrowany, bezpiecznie przechowywany zestaw danych autoryzacyjnych (klucz API, token OAuth2, login/hasło, connection string), który pozwala węzłom workflow łączyć się z zewnętrznymi usługami bez eksponowania wrażliwych danych w kodzie lub interfejsie. Credentials są centralnie zarządzane, mogą być współdzielone między użytkownikami i projektami, a ich bezpieczeństwo zapewnia szyfrowanie AES-256-CBC z kluczem przechowywanym w zmiennej środowiskowej N8N_ENCRYPTION_KEY.

Co może zawierać credential?

Zależnie od typu usługi, credential może przechowywać różne rodzaje danych:

Typ danych	Przykłady	Typowe zastosowanie
Klucze API	sk-proj-…, Bearer token	OpenAI, Stripe, Twilio, Airtable
OAuth2 tokeny	access_token + refresh_token	Google, Microsoft, Slack, GitHub
Login i hasło	admin / P@ssw0rd!	WordPress REST, Jenkins, JIRA Basic
Connection string	postgresql://user:pass@host:5432/db	PostgreSQL, MySQL, MongoDB
Klucze SSH	RSA/Ed25519 private key	SSH do serwerów, SFTP, Git
Certyfikaty TLS	PEM cert + private key	Mutual TLS, własne PKI
Klucze AWS	Access Key ID + Secret	S3, Lambda, SES, DynamoDB
Tokeny JWT	eyJhbGci…	Customowe API, wewnętrzne systemy

2. Jak N8N przechowuje i szyfruje credentiale?

Zrozumienie mechanizmu szyfrowania jest niezbędne dla każdego, kto zarządza N8N w środowisku produkcyjnym. N8N stosuje szyfrowanie symetryczne AES-256-CBC — standard bezpieczeństwa używany m.in. przez banki, rządy i największe firmy technologiczne na świecie.

Architektura szyfrowania krok po kroku

Generowanie klucza szyfrowania — przy pierwszym uruchomieniu N8N automatycznie generuje 256-bitowy klucz losowy i zapisuje go jako zmienną środowiskową N8N_ENCRYPTION_KEY. W instalacjach self-hosted wartość ta jest widoczna w pliku .env lub konfiguracji Docker.
Szyfrowanie przy zapisie — gdy użytkownik zapisuje credential (np. wpisuje klucz API), N8N szyfruje całość danych algorytmem AES-256-CBC używając N8N_ENCRYPTION_KEY jako klucza. Zaszyfrowany blob zapisywany jest do kolumny data w tabeli credentials_entity w bazie danych.
Przechowywanie metadanych w jawnej postaci — nazwa credentiala (np. 'My Slack API’), typ (np. 'slackApi’) oraz lista węzłów mających dostęp są przechowywane w postaci jawnej. Tylko wartości sekretne są szyfrowane.
Odszyfrowanie w pamięci RAM — podczas wykonywania workflowu N8N odszyfrowuje credential tymczasowo w pamięci RAM na czas wykonania węzła. Wartość nigdy nie trafia do logów ani historii.
Automatyczne czyszczenie — po zakończeniu wykonywania węzła odszyfrowane wartości są usuwane z pamięci. N8N nie przechowuje odszyfrowanych secretów dłużej niż to konieczne.

KRYTYCZNE: Backup klucza szyfrowania N8N_ENCRYPTION_KEY to najważniejszy sekret w całej instalacji N8N. Utrata tego klucza oznacza TRWAŁĄ utratę dostępu do wszystkich zapisanych credentiali — nie ma możliwości ich odczytania bez oryginalnego klucza. Obowiązkowe działania:• Zapisz N8N_ENCRYPTION_KEY w bezpiecznym menedżerze haseł (1Password, Bitwarden, KeePass)• Przechowuj kopię w zewnętrznym Vault (HashiCorp Vault, AWS Secrets Manager)• Nigdy nie commituj klucza do repozytorium Git• Dokumentuj procedurę odtworzenia w Runbooku zespołu

Gdzie fizycznie przechowywane są credentiale?

Credentiale zapisywane są w bazie danych N8N w tabeli credentials_entity. N8N wspiera trzy silniki bazodanowe:

Silnik bazodanowy	Lokalizacja domyślna	Środowisko
SQLite (domyślny)	~/.n8n/database.sqlite	Lokalny dev, małe instalacje
PostgreSQL	Konfiguracja przez zmienne env	Produkcja — rekomendowane
MySQL / MariaDB	Konfiguracja przez zmienne env	Produkcja — alternatywa

Struktura tabeli credentials_entity (schemat)

— Uproszczony schemat tabeli credentiali N8N

CREATE TABLE credentials_entity (

id VARCHAR(36) PRIMARY KEY, — UUID credentiala

name VARCHAR(128) NOT NULL, — np. 'My OpenAI API’ (jawne)

type VARCHAR(128) NOT NULL, — np. 'openAiApi’ (jawne)

data TEXT NOT NULL, — ZASZYFROWANY JSON (AES-256)

nodesAccess JSON, — węzły z dostępem (jawne)

createdAt DATETIME NOT NULL,

updatedAt DATETIME NOT NULL

);

— Przykładowa zawartość kolumny 'data’ (po szyfrowaniu):

— 'U2FsdGVkX1+Abc123…XYZ==’ — nie da się odczytać bez klucza

3. Typy credentiali — kompletny przegląd

N8N oferuje bogaty ekosystem typów credentiali. Poniżej przedstawiamy kompletną systematyzację, która pomoże wybrać właściwy typ dla każdej integracji.

3.1 Typy generyczne (do użytku z dowolnym API)

Typ N8N	Gdzie klucz jest wysyłany	Kiedy używać
	Niestandardowy nagłówek HTTP (np. X-API-Key)	Większość REST API z kluczem w nagłówku
	Parametr URL (?api_key=…)	Starsze API przekazujące klucz w URL
	Authorization: Bearer TOKEN	Tokeny JWT, tokeny sesji, PAT
	Authorization: Basic base64(user:pass)	WordPress, Jenkins, JIRA Basic Auth
	Nagłówek Digest Auth	Rzadkie; systemy wymagające Digest
	Bearer + automatyczny refresh	Dowolne API OAuth2 bez dedykowanego node
	Podpisane żądania OAuth1	Twitter API v1, stare API OAuth

3.2 Popularne dedykowane typy credentiali

Usługa	Typ credentiala	Wymagane dane	Uwagi
Google (Gmail, Drive, Sheets)	googleOAuth2Api	Client ID, Client Secret	OAuth2; wymaga aplikacji w Google Cloud Console
OpenAI / ChatGPT	openAiApi	API Key	Klucz z platform.openai.com
Anthropic Claude	anthropicApi	API Key	Klucz z console.anthropic.com
Slack	slackApi / slackOAuth2Api	Bot Token lub OAuth2	Bot token zaczyna się od xoxb-
GitHub	githubApi	Personal Access Token	PAT z odpowiednimi scope’ami
Airtable	airtableTokenApi	Personal Access Token	Zastąpił stary API Key
Stripe	stripeApi	Secret Key (sk_…)	NIGDY nie używaj klucza publishable!
AWS	aws	Access Key ID + Secret	Rekomendowane: dedykowane IAM user/role
PostgreSQL	postgres	Host, Port, DB, User, Password	Używaj SSL dla połączeń prod
Notion	notionApi	Integration Token	Token zaczyna się od secret_
HubSpot	hubspotAppToken	Private App Token	Bearer token z HubSpot Developer portal
Salesforce	salesforceOAuth2Api	Consumer Key + Secret	OAuth2; Connected App w Salesforce

4. Pierwsze kroki: tworzenie i edycja credentiali

N8N oferuje trzy główne sposoby tworzenia credentiali, każdy dopasowany do innego scenariusza użycia.

Metoda 1: Bezpośrednio z węzła (najczęstsza)

Podczas konfigurowania nowego węzła N8N automatycznie pyta o credential. W rozwijalnym menu przy polu 'Credential to connect with’ wybierz '+ Create new credential’. N8N otworzy formularz dopasowany do wybranego węzła — np. dla węzła Gmail pojawi się formularz Google OAuth2.

Metoda 2: Panel Credentials (rekomendowana dla przygotowania)

W lewym menu bocznym kliknij Credentials → Create credential. Wyszukaj usługę w pasku wyszukiwania (ponad 400 opcji) lub przewiń listę. Ta metoda jest zalecana, gdy chcesz przygotować credentiale zanim zaczniesz budować workflow — np. skonfigurować wszystkie połączenia z systemami klienta przed importem gotowych workflowów.

Metoda 3: API N8N (dla DevOps i CI/CD)

N8N udostępnia REST API pozwalające programistycznie zarządzać credentialami. Jest to niezbędne w środowiskach, gdzie wdrożenia są zautomatyzowane:

# Tworzenie credentiala przez REST API N8N

curl -X POST 'https://n8n.twojadomena.pl/api/v1/credentials’ \

-H 'X-N8N-API-KEY: twoj-klucz-api-n8n’ \

-H 'Content-Type: application/json’ \

-d '{

„name”: „OpenAI – Prod – Content”,

„type”: „openAiApi”,

„data”: {

„apiKey”: „sk-proj-…”

}

}’

# Pobranie listy wszystkich credentiali

curl -X GET 'https://n8n.twojadomena.pl/api/v1/credentials’ \

-H 'X-N8N-API-KEY: twoj-klucz-api-n8n’

Best Practice: Konwencja nazewnictwa credentiali. Dobra konwencja nazw credentiali ratuje czas przy zarządzaniu dziesiątkami integracji. Rekomendowany format: [USŁUGA] – [ŚRODOWISKO] – [CEL/KONTEKST] Przykłady: • OpenAI – Prod – Article Generation • Google OAuth2 – Dev – Drive Backup • PostgreSQL – Staging – Analytics DB • Slack – Prod – Customer Alerts Bot Unikaj ogólnych nazw: 'API’, 'test’, 'nowy’ — po roku nie wiadomo, co kryją.

Testowanie credentiala

Większość typów credentiali zawiera przycisk ’Retry’ (lub 'Connect my account’ dla OAuth2). N8N wykonuje testowe zapytanie do API (np. listę dysków Google Drive, profil GitHub, listę workspace’ów Slack) i informuje o powodzeniu lub komunikacie błędu.

Zawsze testuj credential bezpośrednio po utworzeniu i po każdej rotacji klucza — zanim workflow zacznie używać go w produkcji.

Edycja istniejącego credentiala

Wejdź w Credentials → kliknij nazwę credentiala. Formularz edycji otwiera się z ukrytymi (zamaskowanymi) wartościami. Wpisz nowe wartości tylko w polach, które chcesz zmienić — pozostałe pola możesz zostawić puste, N8N zachowa ich poprzednie zaszyfrowane wartości.

Uwaga: pola haseł i kluczy API pokazują placeholder (np. '••••••••’), ale nie wyświetlają aktualnej wartości. Jest to celowe zachowanie bezpieczeństwa.

5. OAuth2 — konfiguracja krok po kroku

OAuth2 to najczęściej używany protokół autoryzacji w nowoczesnych API (Google, Microsoft 365, Slack, GitHub, Salesforce, Notion i setki innych). N8N implementuje pełny Authorization Code Flow z PKCE — najbezpieczniejszy wariant standardu.

Jak działa OAuth2 w N8N — przepływ autoryzacji

Rejestracja aplikacji OAuth u dostawcy — wejdź w panel deweloperski usługi (Google Cloud Console, Azure App Registration, Slack API, GitHub Developer Settings) i stwórz nową aplikację OAuth. Zapisz Client ID (Identyfikator klienta) i Client Secret (Tajny klucz klienta).

Ustawienie Redirect URI — w ustawieniach aplikacji OAuth wpisz dokładnie: https://twoja-instancja.n8n.io/rest/oauth2-credential/callback. URI musi być identyczny po obu stronach — każda różnica (nawet trailing slash) spowoduje błąd.

Konfiguracja credentiala w N8N — wybierz typ credentiala (np. 'Google OAuth2 API’), wpisz Client ID, Client Secret i zaznacz wymagane zakresy (scopes). Zapisz.

Autoryzacja jednorazowa — kliknij 'Connect my account’ / 'Sign in with Google’. N8N otworzy okno przeglądarki z ekranem zgody dostawcy. Zaloguj się i zatwierdź uprawnienia.

Automatyczne zarządzanie tokenami — N8N otrzymuje access token (krótkotrwały, np. 1h) i refresh token (długotrwały). Automatycznie monitoruje czas wygaśnięcia access tokenu i pobiera nowy za pomocą refresh tokenu — bez interwencji użytkownika.

Zasada minimalnych uprawnień dla OAuth2 (Principle of Least Privilege). Zawsze wybieraj tylko te zakresy (scopes), które są niezbędne dla konkretnego workflowu: Zamiast: https://www.googleapis.com/auth/gmail (pełny dostęp) Użyj: https://www.googleapis.com/auth/gmail.readonly (tylko odczyt) Zamiast: repo (pełny dostęp do repozytoriów GitHub) Użyj: repo:status, read:user (tylko to, co potrzebne) Zmniejsza to ryzyko w przypadku wycieku tokenu lub kompromitacji konta.

Przykład: Pełna konfiguracja Google OAuth2

// Konfiguracja credentiala Google OAuth2 API w N8N

// (reprezentacja JSON — eksport/import przez API)

{

„name”: „Google OAuth2 – Prod – Workspace”,

„type”: „googleOAuth2Api”,

„data”: {

„clientId”: „123456789-abc.apps.googleusercontent.com”,

„clientSecret”: „GOCSPX-twoj-secret”, // zaszyfrowane po zapisie

„scope”: [

„https://www.googleapis.com/auth/gmail.readonly”,

„https://www.googleapis.com/auth/drive”,

„https://www.googleapis.com/auth/spreadsheets”

„authUrl”: „https://accounts.google.com/o/oauth2/v2/auth”,

„accessTokenUrl”: „https://oauth2.googleapis.com/token”,

„authentication”: „body”,

„grantType”: „authorizationCode”

}

Generic OAuth2 — dla nieobsługiwanych usług

Gdy N8N nie posiada wbudowanego credentiala dla danej usługi, możesz użyć typu ’OAuth2 API’ (Generic). Wymaga ręcznego podania wszystkich parametrów:

Authorization URL — endpoint autoryzacji dostawcy
Access Token URL — endpoint wymiany kodu na token
Client ID i Client Secret — z aplikacji OAuth dostawcy
Scope — zakresy oddzielone spacją lub przecinkami
Auth URI Query Parameters — dodatkowe parametry (np. response_type=code, access_type=offline)

Rozwiązywanie problemów OAuth2

Błąd	Przyczyna	Rozwiązanie
redirect_uri_mismatch	Redirect URI w N8N ≠ URI w aplikacji OAuth	Skopiuj URI z N8N (Settings > Credentials) i wklej dokładnie w aplikacji
invalid_client	Błędny Client ID lub Client Secret	Sprawdź czy Client Secret nie zawiera spacji na początku/końcu
invalid_grant	Wygasły refresh token lub zmienione hasło	Kliknij 'Reconnect’ i przejdź ponownie przez OAuth flow
access_denied	Użytkownik odrzucił uprawnienia lub scope za szeroki	Sprawdź czy konto ma dostęp do żądanych zasobów
invalid_scope	Nieprawidłowy lub niedostępny scope	Sprawdź dokumentację API dostawcy dla właściwych wartości scope

6. Klucze API, tokeny Bearer i Basic Auth

Klucze API i tokeny są najprostszym i najszerzej stosowanym typem autoryzacji. W N8N obsługiwane są przez kilka generycznych typów credentiali oraz przez setki dedykowanych integracji.

Kiedy używać którego typu?

Sytuacja	Rekomendowany typ	Przykład
API wymaga klucza w nagłówku X-API-Key	httpHeaderAuth	Wiele SaaS API (Airtable legacy, Mailgun)
API wymaga klucza jako ?api_key= w URL	httpQueryAuth	Starsze API, Google Maps (nie rekomendowane)
API używa Bearer tokenów JWT	httpBearerAuth	Wewnętrzne API, Keycloak, Auth0
API używa loginu i hasła (Base64)	httpBasicAuth	WordPress /wp-json, Jenkins, Prometheus
Dedykowane API, np. OpenAI	openAiApi (dedykowany)	Lepsze UX i walidacja pól

Konfiguracja HTTP Header Auth — przykład

// HTTP Header Auth — klucz API w niestandardowym nagłówku

{

„name”: „My Custom API – Prod”,

„type”: „httpHeaderAuth”,

„data”: {

„name”: „X-API-Key”, // nazwa nagłówka

„value”: „my-secret-key-…” // wartość (AES-256 po zapisie)

}

// Wynikowy nagłówek HTTP:

// X-API-Key: my-secret-key-…

KRYTYCZNY BŁĄD BEZPIECZEŃSTWA: Klucze w polach wyrażeń. NIGDY nie wpisuj kluczy API bezpośrednio w polach wyrażeń (expressions) węzłów! Złe podejście (NIEBEZPIECZNE): Pole 'API Key’ > Expression: {{ „sk-proj-abc123xyz” }} Dlaczego to niebezpieczne: • Klucz trafia do historii wykonań workflowu w postaci jawnej • Klucz pojawia się w eksportach workflowu (JSON) • Klucz może trafić do logów systemowych • Klucz jest widoczny w debuggerze N8N Zawsze używaj mechanizmu Credentials lub zmiennych środowiskowych ($env)!

7. Credentiale przez zmienne środowiskowe

Zmienne środowiskowe to kluczowy mechanizm bezpiecznego wstrzykiwania sekretów do N8N z zewnątrz — bez twardego kodowania wartości. Są szczególnie ważne w środowiskach zarządzanych przez DevOps: Docker, Kubernetes, CI/CD pipeline.

N8N_ENCRYPTION_KEY — najważniejsza zmienna

# Generowanie bezpiecznego 32-bajtowego klucza (Linux/macOS)

openssl rand -hex 32

# Przykład: a1b2c3d4e5f6789012345678901234567890abcdef12345678abcdef12345678

# Plik .env (NIGDY nie commituj do Git!)

N8N_ENCRYPTION_KEY=a1b2c3d4e5f6789012345678901234567890abcdef12345678

# docker-compose.yml

services:

n8n:

image: n8nio/n8n:latest

environment:

– N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}

– DB_TYPE=postgresdb

– DB_POSTGRESDB_HOST=postgres

– DB_POSTGRESDB_DATABASE=n8n

– DB_POSTGRESDB_USER=${DB_USER}

– DB_POSTGRESDB_PASSWORD=${DB_PASSWORD}

env_file:

– .env

Używanie zmiennych środowiskowych w wyrażeniach

N8N pozwala odczytywać zmienne środowiskowe w wyrażeniach za pomocą obiektu $env. Wymaga to ustawienia N8N_BLOCK_ENV_ACCESS_IN_NODE=false (domyślna wartość dla self-hosted).

// W polach wyrażeń (expressions) węzłów:

// Przykład użycia w węźle HTTP Request:

// Header: Authorization

// Value: Bearer {{ $env.MY_SERVICE_TOKEN }}

Ważne: bezpieczeństwo $env w trybie multi-user. W instancjach N8N ze wspólnymi użytkownikami (tryb multi-user) dostęp do $env oznacza, że WSZYSCY użytkownicy z dostępem do edycji workflowów mogą odczytywać zmienne środowiskowe przez wyrażenia. Jeśli różni użytkownicy nie powinni widzieć Twoich sekretów: • Ustaw N8N_BLOCK_ENV_ACCESS_IN_NODE=true • Użyj dedykowanego Vault (sekcja 10) • Stosuj oddzielne instancje N8N na środowisko (dev/prod)

Kubernetes Secrets — produkcyjna konfiguracja

# 1. Tworzenie Kubernetes Secret

kubectl create secret generic n8n-credentials \

–from-literal=encryption-key=’TWOJ_KLUCZ_AES256′ \

–from-literal=openai-api-key=’sk-proj-…’ \

–from-literal=db-password=’super-secure-password’

# 2. Deployment manifest — przekazanie secretów jako ENV

apiVersion: apps/v1

kind: Deployment

spec:

template:

spec:

containers:

– name: n8n

image: n8nio/n8n:latest

env:

– name: N8N_ENCRYPTION_KEY

valueFrom:

secretKeyRef:

key: encryption-key

– name: OPENAI_API_KEY

valueFrom:

secretKeyRef:

key: openai-api-key

8. Udostępnianie credentiali między użytkownikami

W N8N w trybie multi-user (dostępnym w wersji Cloud i Enterprise, a od wersji 0.227+ w self-hosted) możliwe jest granularne zarządzanie dostępem do credentiali. To kluczowa funkcja dla zespołów.

Model uprawnień

Rola	Widzi credential	Edytuje wartości	Udostępnia	Usuwa
Owner instancji	Wszystkie	Wszystkie	Tak	Tak
Admin	W swojej przestrzeni	Własne + udostępnione	Tak	Własne
Member (właściciel credentiala)	Własne + udostępnione jemu	Własne	Tak (własne)	Własne
Member (dostęp współdzielony)	Nazwa (nie wartości)	Nie	Nie	Nie

Jak udostępnić credential — instrukcja krok po kroku

Otwórz panel Credentials w lewym menu.
Kliknij w nazwę credentiala, który chcesz udostępnić.
Przejdź do zakładki Sharing.
Kliknij Add users i zacznij wpisywać adres e-mail użytkownika lub nazwę projektu.
Zatwierdź przyciskiem Save. Użytkownik zobaczy credential na swojej liście (z zamaskowanymi wartościami).

Projekty N8N — rekomendowane podejście dla zespołów. Od N8N 1.0 dostępna jest funkcja Projektów. Credentiale można przypisywać do projektu zamiast do indywidualnych użytkowników: • Utwórz projekt dla każdego klienta lub domeny biznesowej (np. 'Klient ABC’, 'Automatyzacja Marketingu’, 'Finance Team’) • Przypisz credentiale do projektu • Wszyscy członkowie projektu automatycznie mają dostęp • Zarządzanie uprawnieniami na poziomie projektu, nie per-użytkownik Jest to znacznie skalowalniejsze niż udostępnianie credential-po-credentialu.

9. Bezpieczeństwo — najlepsze praktyki

Bezpieczeństwo credentiali to nie tylko szyfrowanie w bazie danych — to cały zestaw praktyk obejmujący zarządzanie cyklem życia kluczy, kontrolę dostępu, monitoring i procedury awaryjne.

9.1 Zasada minimalnych uprawnień (Principle of Least Privilege)

Każdy credential powinien mieć absolutne minimum uprawnień. Konkretne zalecenia:

Bazy danych: twórz dedykowanych użytkowników DB z uprawnieniami tylko do konkretnych tabel i operacji (SELECT, INSERT — bez DROP, ALTER, CREATE)
AWS IAM: twórz dedykowane role IAM z politykami ograniczonymi do konkretnych zasobów (ARN) i akcji. Nigdy nie używaj root credentials lub AdministratorAccess
Google Service Accounts: twórz oddzielne Service Accounts dla różnych celów, nadawaj im minimalne role (np. roles/storage.objectViewer zamiast roles/storage.admin)
GitHub PAT: używaj fine-grained Personal Access Tokens (nie classic) z dostępem tylko do konkretnych repozytoriów i operacji
Slack Bot: podczas tworzenia aplikacji Slack zaznaczaj tylko te uprawnienia, które są niezbędne

9.2 Rotacja kluczy API

Regularna rotacja kluczy API jest najlepszą praktyką bezpieczeństwa. Rekomendowany harmonogram:

Kategoria ryzyka	Przykłady	Częstotliwość rotacji
Krytyczny (produkcja, dane wrażliwe)	Klucze płatności, DB produkcyjne, PII	Co 30–90 dni
Wysoki (produkcja, dane biznesowe)	CRM, ERP, wewnętrzne API prod	Co 90–180 dni
Średni (narzędzia, komunikacja)	Slack, GitHub, Notion	Co 6–12 miesięcy
Niski (dev/staging)	Środowiska testowe, sandbox API	Co rok lub przy zmianie zespołu
Natychmiastowa rotacja zawsze gdy:	Podejrzenie wycieku, odejście pracownika, exploit API	Natychmiast

9.3 Procedura rotacji klucza API w N8N

Wygeneruj nowy klucz API w panelu usługi (np. OpenAI Platform, Stripe Dashboard)
W N8N wejdź w Credentials → edytuj credential → wpisz nowy klucz
Kliknij 'Test credential’ — upewnij się, że nowy klucz działa poprawnie
Zapisz credential
W panelu usługi unieważnij (revoke) stary klucz
Sprawdź czy żaden działający workflow nie zgłasza błędów autoryzacji

9.4 Audyt credentiali — checklist

Przeprowadzaj audyt co najmniej raz na kwartał:

Sprawdź listę wszystkich credentiali — usuń nieużywane i zduplikowane
Zweryfikuj kto ma dostęp do których credentiali (panel Sharing)
Sprawdź daty ostatniej modyfikacji — stare credentiale mogą wymagać rotacji
Upewnij się, że każdy credential ma opisową nazwę (środowisko, usługa, cel)
Sprawdź czy odeszli pracownicy nie mają nadal dostępu do credentiali
Zweryfikuj logi N8N pod kątem błędów 401/403 — mogą wskazywać wygasłe klucze
Sprawdź czy N8N_ENCRYPTION_KEY jest bezpiecznie przechowywany i zbackupowany

9.5 Konfiguracja sieciowa dla bezpieczeństwa

# Zmienne środowiskowe wzmacniające bezpieczeństwo N8N

# Wymuszenie HTTPS (wymagane dla OAuth2 callback)

N8N_PROTOCOL=https

N8N_EDITOR_BASE_URL=https://n8n.twojadomena.pl

# Wyłączenie telemetrii i diagnostyki

N8N_DIAGNOSTICS_ENABLED=false

N8N_VERSION_NOTIFICATIONS_ENABLED=false

# Blokada dostępu do $env w workflowach (multi-tenant)

N8N_BLOCK_ENV_ACCESS_IN_NODE=true

# Ograniczenie dostępu do API zewnętrznych (allowlist)

N8N_ALLOW_ORIGIN=https://n8n.twojadomena.pl

# Timeout dla połączeń (zapobiega zawieszeniu)

N8N_DEFAULT_HTTP_REQUEST_TIMEOUT=300000

10. Integracja z zewnętrznymi Vault

W zaawansowanych środowiskach produkcyjnych warto zintegrować N8N z dedykowanymi systemami zarządzania sekretami (Secret Management Systems). Zapewniają one centralne zarządzanie, audyt dostępu, automatyczną rotację i ścieżkę audytu (audit trail).

Dostępne rozwiązania Vault

Rozwiązanie	Provider	Najlepsze dla
HashiCorp Vault	Open-source / Enterprise	Self-hosted, duże organizacje, pełna kontrola
AWS Secrets Manager	Amazon Web Services	Środowiska AWS, automatyczna rotacja RDS
Azure Key Vault	Microsoft Azure	Środowiska Azure, integracja z AD
Google Secret Manager	Google Cloud	Środowiska GCP, proste API
Infisical	Open-source / Cloud	Mniejsze zespoły, łatwa konfiguracja
Doppler	SaaS	Szybkie wdrożenie, dobre DevEx

Podejście 1: Vault → Zmienne środowiskowe → N8N

Najprostsze i najbardziej rekomendowane podejście: system wdrożeń pobiera sekrety z Vault i przekazuje je jako zmienne środowiskowe do kontenera N8N.

# External Secrets Operator (Kubernetes) — synchronizacja z HashiCorp Vault

apiVersion: external-secrets.io/v1beta1

kind: ExternalSecret

metadata:

namespace: n8n

spec:

refreshInterval: 1h

secretStoreRef:

kind: ClusterSecretStore

target:

data:

– secretKey: N8N_ENCRYPTION_KEY

remoteRef:

key: secret/n8n/prod

property: encryption_key

– secretKey: OPENAI_API_KEY

remoteRef:

key: secret/n8n/prod

property: openai_api_key

Podejście 2: Dynamiczne pobieranie z Vault w workflow

N8N może sam pobierać sekrety z Vault API w czasie wykonywania workflow, co pozwala na bardziej granularne zarządzanie:

// Węzeł HTTP Request — pobieranie sekretu z HashiCorp Vault

{

„method”: „GET”,

„url”: „https://vault.internal:8200/v1/secret/data/n8n/{{ $env.N8N_ENV }}”,

„headers”: {

„X-Vault-Token”: „{{ $env.VAULT_TOKEN }}”

}

// Dostęp do odczytanego sekretu w kolejnym węźle:

// {{ $json.data.data.openai_api_key }}

11. Debugowanie i rozwiązywanie problemów

Problemy z credentialami są jedną z najczęstszych przyczyn błędów w N8N. Poniższy przewodnik pomoże szybko zdiagnozować i rozwiązać każdy problem.

Tabela diagnozowania błędów

Komunikat błędu	Przyczyna	Rozwiązanie
401 Unauthorized	Zły klucz, wygasły token, brak nagłówka auth	Przetestuj credential, zaktualizuj token OAuth2
403 Forbidden	Poprawne credentiale, brak uprawnień do zasobu	Sprawdź scopes OAuth2, uprawnienia konta API
Could not decrypt data	Zmieniony N8N_ENCRYPTION_KEY	Przywróć oryginalny klucz z backupu
invalid_grant (OAuth2)	Wygasły refresh token, zmienione hasło	Kliknij 'Reconnect’ w credentialu
Credential not found	Credential usunięty lub brak dostępu	Sprawdź panel Credentials lub skontaktuj z właścicielem
ECONNREFUSED	Serwer DB niedostępny, zły host/port	Sprawdź host, port i reguły firewalla
redirect_uri_mismatch	URI OAuth2 nie zgadzają się	Skopiuj URI z N8N Settings i wklej w aplikacji OAuth
SSL/TLS error	Brak certyfikatu lub self-signed cert	Dodaj certyfikat CA lub ustaw rejectUnauthorized: false (dev only)

Komendy diagnostyczne

# Sprawdzenie czy N8N_ENCRYPTION_KEY jest ustawiony

docker exec -it n8n sh -c 'echo $N8N_ENCRYPTION_KEY | wc -c’

# Powinno zwrócić 65 (64 znaki hex + newline)

# Lista credentiali w bazie danych (tylko metadane, bez wartości)

docker exec -it n8n-postgres psql -U n8n -d n8n \

-c „SELECT id, name, type, \”createdAt\” FROM credentials_entity ORDER BY \”createdAt\” DESC;”

# Logi N8N — filtrowanie błędów autoryzacji

# Test połączenia z URL OAuth2 callback

curl -I 'https://n8n.twojadomena.pl/rest/oauth2-credential/callback’

# Oczekiwany wynik: HTTP/1.1 4xx (N8N oczekuje parametrów — to normalne)

12. Migracja credentiali między instancjami

Migracja credentiali między instancjami N8N (np. z dev na prod, przy zmianie serwera lub przy przejściu z SQLite na PostgreSQL) wymaga szczególnej ostrożności.

KRYTYCZNE: Szyfrowanie jest powiązane z kluczem. Zaszyfrowane credentiale w bazie danych są nierozłącznie powiązane z konkretnym N8N_ENCRYPTION_KEY. Skopiowanie tylko bazy danych na nową instancję NIE wystarczy.Nowa instancja musi używać IDENTYCZNEGO N8N_ENCRYPTION_KEY co stara instancja,aby móc odszyfrować i poprawnie odczytać credentiale.

Scenariusz A: Migracja z zachowaniem klucza

Zrób backup bazy danych starej instancji (pg_dump, mysqldump lub skopiuj plik .sqlite)
Skopiuj wartość N8N_ENCRYPTION_KEY ze starej instancji
Przywróć bazę danych na nowym serwerze
Ustaw identyczny N8N_ENCRYPTION_KEY na nowej instancji
Uruchom nową instancję i sprawdź czy credentiale działają (przycisk Test)

Scenariusz B: Reset credentiali (nowy klucz)

Gdy nie możesz lub nie chcesz przenosić starego klucza (np. po incydencie bezpieczeństwa):

Zrób listę wszystkich credentiali ze starej instancji (nazwy, typy, których usług dotyczą)
Przygotuj listę wartości do ponownego wprowadzenia (klucze API, Client ID/Secret itp.) — zbierz je z oryginalnych źródeł, nie z N8N
Uruchom nową instancję N8N z nowym, wygenerowanym kluczem
Utwórz wszystkie credentiale od nowa
Importuj workflow — N8N powiąże je z nowymi credentialami po nazwie
Przetestuj wszystkie kluczowe workflow przed ostatecznym przełączeniem ruchu

13. FAQ — najczęściej zadawane pytania

Jak N8N szyfruje credentiale?

N8N stosuje algorytm AES-256-CBC. Kluczem szyfrowania jest wartość zmiennej środowiskowej N8N_ENCRYPTION_KEY. Wszystkie pola credentiala (klucze API, hasła, tokeny) są szyfrowane jako jeden JSON blob przed zapisem do bazy danych. Metadane (nazwa, typ) są przechowywane jawnie.

Czy N8N Cloud jest bezpieczniejszy niż self-hosted pod względem credentiali?

N8N Cloud zarządza kluczami szyfrowania i infrastrukturą zgodnie z najlepszymi praktykami (SOC 2 Type II, szyfrowanie at-rest i in-transit). Self-hosted daje pełną kontrolę, ale odpowiedzialność za bezpieczeństwo spada na Twój zespół. Obydwa mogą być równie bezpieczne przy właściwej konfiguracji.

Co zrobić gdy zgubiłem N8N_ENCRYPTION_KEY?

Bez oryginalnego klucza nie ma możliwości odczytania zaszyfrowanych credentiali. Musisz uruchomić N8N z nowym kluczem i ręcznie ponownie wprowadzić wszystkie credentiale. Stara baza danych jest bezużyteczna bez klucza — co jest zamierzoną cechą systemu bezpieczeństwa. Dlatego backup klucza jest krytyczny.

Czy mogę używać jednego credentiala w wielu workflowach?

Tak, to zalecana praktyka. Jeden credential może być używany przez dowolną liczbę workflowów. Zmiana klucza API wymaga tylko jednej aktualizacji w panelu Credentials — wszystkie workflow automatycznie używają nowej wartości.

Jak sprawdzić, które workflowy używają konkretnego credentiala?

W panelu Credentials kliknij credential — zobaczysz sekcję 'Workflows using this credential’. Możesz też zapytać bazę danych: SELECT DISTINCT workflowId FROM workflow_entity WHERE nodes::text LIKE '%CredentialName%’.

Jak zaktualizować wygasły token OAuth2?

N8N automatycznie odświeża tokeny używając refresh tokenu. Jeśli token wygasł (zmienione hasło, odwołane uprawnienia): Credentials → kliknij credential → 'Reconnect’ lub 'Connect my account’ → przejdź ponownie przez OAuth flow.

Czy credentiale są eksportowane razem z workflowami?

Nie. Funkcja eksportu workflowu (JSON) nie zawiera wartości credentiali — są one celowo usuwane ze względów bezpieczeństwa. Eksportowany plik zawiera tylko nazwy i typy credentiali, dzięki czemu workflow można importować do innej instancji i przypisać tam nowe credentiale.

Czy N8N obsługuje rotację kluczy szyfrowania (key rotation)?

N8N nie ma natywnej funkcji rotacji klucza szyfrowania (re-encryption). Zmiana N8N_ENCRYPTION_KEY wymaga manualnego procesu: eksport credentiali (przez API), reset bazy, import z nowym kluczem. Jest to rzadka operacja — rotacja klucza szyfrowania jest inna niż rotacja kluczy API.

14. Słownik pojęć

Krótki słownik terminów używanych w kontekście zarządzania credentialami w N8N.

Termin	Definicja
Credential (N8N)	Zaszyfrowany, bezpiecznie przechowywany zestaw danych uwierzytelniających (klucz API, token OAuth2, login/hasło) umożliwiający węzłom N8N komunikację z zewnętrznymi usługami.
N8N_ENCRYPTION_KEY	Zmienna środowiskowa przechowująca 256-bitowy klucz AES używany do szyfrowania i deszyfrowania credentiali w N8N. Jej utrata oznacza trwałą utratę dostępu do credentiali.
AES-256-CBC	Standard szyfrowania symetrycznego używany przez N8N. AES-256 oznacza klucz 256-bitowy; CBC to tryb łańcuchowania bloków. Uznawany za bezpieczny przez NIST i NSA.
OAuth2	Protokół autoryzacji umożliwiający aplikacjom (N8N) dostęp do zasobów użytkownika w usługach (Google, Slack) bez przekazywania hasła. N8N implementuje Authorization Code Flow z PKCE.
Access Token	Krótkotrwały token (zwykle 1h–24h) OAuth2 używany do autoryzacji zapytań API. N8N automatycznie odświeża access tokeny przed ich wygaśnięciem.
Refresh Token	Długotrwały token OAuth2 używany do pobierania nowych access tokenów. Przechowywany zaszyfrowany w N8N; nigdy nie jest wysyłany bezpośrednio do API.
API Key	Statyczny sekretny ciąg znaków służący jako uwierzytelnienie do API. Prostszy niż OAuth2, ale bez mechanizmu automatycznego wygasania.
Bearer Token	Token przesyłany w nagłówku HTTP 'Authorization: Bearer TOKEN’. Może być kluczem API, JWT lub tokenem sesji.
Client ID / Client Secret	Para identyfikatorów aplikacji OAuth2. Client ID jest publiczny; Client Secret jest prywatny i musi być chroniony (szyfrowany w N8N).
Scope (OAuth2)	Zbiór uprawnień żądanych od dostawcy OAuth2. Zgodnie z zasadą minimalnych uprawnień należy żądać tylko tych scope’ów, które są faktycznie potrzebne.
Principle of Least Privilege	Zasada bezpieczeństwa: każdy podmiot (credential, użytkownik, serwis) powinien mieć tylko te uprawnienia, które są niezbędne do wykonania swojego zadania — i nic więcej.
Secret Manager / Vault	Dedykowany system zarządzania sekretami (np. HashiCorp Vault, AWS Secrets Manager) zapewniający centralne przechowywanie, audyt i rotację sekretów.
Key Rotation	Proces regularnej wymiany kluczy kryptograficznych lub kluczy API na nowe, minimalizujący ryzyko wynikające z potencjalnego wycieku.