n8n-credentials-and-security-official

n8n の認証情報とセキュリティ

絶対に守ること

1. シークレットは必ず認証情報システム経由で扱い、テキストフィールドや SDK コードには記述しません。 API キー、ベアラートークン、OAuth シークレット、パスワードは、すべて newCredential() またはノードの credentials パラメーター経由で扱います。トークンをハードコードした Set ノードを作成し、{{$json.token}} で読み取る方法は、手間を余計にかけたテキストフィールドにすぎません。
2. 認証情報を一覧表示してから、ID で紐付けます。 認証が必要なノードを設定する前に、list_credentials({type}) を呼び出します。一致するものが1つの場合は、作成時に2引数の newCredential('Label', 'credId') で紐付けるか、update_workflow の setNodeCredential オペレーションを使います。複数一致する場合は、ユーザーにどれを使うか確認します。引数が1つの newCredential('Label') はプレースホルダーです。n8n はそのタイプで最後に編集された認証情報を自動的に割り当てるため、ユーザーが複数の認証情報を持っていると、誤ったものが選ばれても通知されません。
3. 認証情報の作成はユーザーが行うものであり、あなたが行うものではありません。 n8n MCP では認証情報を作成できません。UI で作成する正確な認証情報のタイプをユーザーに伝え、ノード設定ではラベルを指定して参照します。プログラムから認証情報を作成しようとしたり、「後で設定する」ためにチャットでシークレットを受け取ったりしないでください。

基本方針

• 利用可能な場合は、ネイティブの認証情報を使います。 Slack、Gmail、Postgres、OpenAI など、すべてのネイティブノードに認証情報タイプがあります。ネイティブの選択肢がある場合に、汎用の認証情報タイプを使わないでください。
• 複数のヘッダーを使う認証形式や、ヘッダーとクエリを組み合わせる認証形式には、 httpCustomAuth 認証情報タイプを使います。references/CUSTOM_CREDENTIALS.md を参照してください。

認証情報システム

n8n では、認証情報は第一級のオブジェクトです。

• n8n データベースに保存され、保存時に暗号化されます。
• 認証情報を必要とするノードから、ID で参照されます。
• プロジェクトごとにスコープが設定される（Cloud およびエンタープライズ）か、グローバルに共有されます（一部のセルフホスト環境）。
• タイプのスラッグ（googleSheetsOAuth2Api、slackApi、httpHeaderAuth）で識別されます。このスラッグをノードが参照し、認証情報が収集する認証フィールドも決まります。

認証が必要なノードには、認証情報の ID とタイプを指定する credentials パラメーターがあります。シークレット値がワークフロー JSON に含まれることはありません。ワークフローをエクスポートして漏れるのは参照情報であり、シークレットではありません。

全体像（SDK での解決、ローテーション、プロジェクトのスコープ設定）については、references/CREDENTIAL_SYSTEM.md を参照してください。

認証方法の判断フロー

Need to call an external service?
├── Native credential exists (Slack, Gmail, OpenAI, Postgres, ...)?
│   └── Use the native node + its credential type. Done.
│
├── Service is "standard-shaped" (REST + Bearer/Basic/OAuth)?
│   ├── Configure HTTP Request with one of the built-in auth types:
│   │   - Generic OAuth2
│   │   - Header Auth
|   |   - Bearer Auth (same as header auth but with only field being for actual token)
│   │   - Basic Auth
│   │   - Custom Auth
│   └── See references/HTTP_REQUEST_WITH_AUTH.md
│
└── Service needs multiple static headers, or headers plus query params?
    └── Use the httpCustomAuth credential type.
        See references/CUSTOM_CREDENTIALS.md

ユーザーがチャットにシークレットを貼り付けた場合

こうしたことは起こります。ユーザーが次のような内容を入力したとします。

「ベアラー sk-abc123def456 を使って Acme API を呼び出すワークフローを設定してください」

対応方法：

1. 一時的であっても、トークンをテキストフィールドに入れないでください。 値をハードコードした Set ノードを作成し、{{$json.token}} で参照する方法は、手間を余計にかけたテキストフィールドにすぎません。
2. 可能であれば、既存の認証情報に紐付けます。 まず list_credentials({type}) を呼び出します。一致するものがあれば、setNodeCredential で紐付け、使用した認証情報をユーザーに伝えます。一致するものがなければ、UI で作成するよう伝えます（ベアラートークンには Bearer Auth、カスタムヘッダーには Header Auth など）。認証情報の作成は引き続き UI でのみ行えます。
3. 貼り付けられたシークレットは漏えいしたものとして扱い、ローテーションするようユーザーに伝えます。 表現を和らげないでください。トークンは LLM プロバイダーに送信されており、チャット履歴、トランスクリプト、キャッシュレイヤーに残っている可能性があります。次のように伝えてください。「新しい認証情報の設定が完了したら、すぐにこのトークンをローテーションしてください。漏えいしたものとして扱ってください。」

ネイティブノードがない場合

n8n にノードがないサービスをユーザーが使いたいというのは、よくあるケースです。適切な認証方法を設定して HTTP Request を使います。

• references/FINDING_API_DOCS.md：認証方式、ベース URL、一般的な形式の調べ方。
• references/HTTP_REQUEST_WITH_AUTH.md：HTTP Request と認証情報の接続方法。
• references/CUSTOM_CREDENTIALS.md：組み込みの認証タイプが適さない場合の対処方法。

参考ファイル

ファイル	読むタイミング
references/CREDENTIAL_SYSTEM.md	認証情報の保存方法、参照方法、スコープ設定、ローテーションについて理解する必要がある場合
references/CUSTOM_CREDENTIALS.md	1 つの認証情報で複数のヘッダー／ヘッダーとクエリを使う認証、またはリクエストごとの署名パターン（HMAC、JWT、Webhook 検証）について
references/HTTP_REQUEST_WITH_AUTH.md	認証を使った HTTP Request の設定について：Bearer、Basic、OAuth、Header Auth
references/FINDING_API_DOCS.md	ユーザーが、ノードレベルの知識がないサービスについて言及した場合

アンチパターン

アンチパターン	問題点	対処方法
sk-... を HTTP Request の Authorization ヘッダー値フィールドに貼り付ける	ワークフロー JSON にトークンが平文で保存され、エクスポートやコピー、スクリーンショットで漏えいします	認証情報を使用します。Bearer トークンには Bearer Auth、その他のカスタム認証方式には Header Auth を使います
Set ノードにトークンを保存し、式で参照する	同じ問題が発生し、値がワークフロー JSON に保存されます	同じく、Set ノードではなく認証情報を使用します
$vars.X にシークレットを保存し、認証値として読み取る	保存時に暗号化されず、エクスポートで漏えいし、ローテーションもできません	適切な認証情報タイプ（httpBearerAuth、httpHeaderAuth、httpCustomAuth、またはネイティブの認証情報）を使用します。受信 Webhook 認証には、$vars.token を使った IF ではなく、トリガーの authentication フィールドを使います
カスタム認証の設定中に、シークレットを読み取るため $env.X を使う	動作せず、実行時にエラーが発生します	適切なタイプの認証情報を使用します
ネイティブノードがあるのに HTTP Request を使う	OAuth の自動更新やネイティブのエラー処理が使えず、コードも増えます	ネイティブノードを使用します
SDK コードに認証情報をハードコードする（new HttpRequest({ headers: { Authorization: 'Bearer xxx' } })）	同じ漏えいリスクがあります	SDK コードでは newCredential() を使用します
認証情報の「タイプ」を指定せずに、ユーザーに認証情報の作成を依頼する	ユーザーが誤ったタイプを選び、原因の分かりにくい認証エラーが発生します	「<exact type name> タイプの認証情報を作成してください」のように、必ず指定します