외부 비밀 저장소 사용하기

외부 비밀 저장소 사용하기 (Use External Secret Stores)

출처: 공식문서

n8n과 함께 외부 비밀 볼트(vault) 를 사용하는 방법을 설명할게요.

기능 제공 범위

외부 비밀(External secrets)은 다음 환경에서 쓸 수 있어요.

n8n Cloud: Enterprise
셀프호스팅: Enterprise

지원 제공자

n8n이 지원하는 시크릿 제공자는 다음과 같아요: 1Password(Connect Server 사용), AWS Secrets Manager, Azure Key Vault, GCP Secrets Manager, HashiCorp Vault, Infisical. n8n은 HashiCorp Vault Secrets(HCP 서비스)는 지원하지 않아요.

n8n 2.10.0부터 제공자당 여러 볼트를 연결할 수 있어요. 더 오래된 버전은 제공자당 볼트 하나만 지원해요.
n8n 2.13.0부터, 활성화하면 프로젝트 편집자가 자기 프로젝트 안에서 외부 비밀을 쓸 수 있고, 프로젝트 관리자는 프로젝트 볼트를 관리할 수 있어요.

외부 시크릿 저장소에 저장된 자격증명은 자격증명 필드에서만 해석되고, 표현식을 지원하는 다른 필드에서는 해석되지 않아요.

외부 시크릿 저장소를 쓰면 n8n용 자격증명[^1]을 관리할 수 있어요.

n8n은 모든 자격증명을 데이터베이스에 암호화해서 저장하고 기본적으로 접근을 제한해요. 외부 시크릿 기능을 쓰면 민감한 자격증명 정보를 외부 볼트에 저장하고, 필요할 때 n8n이 불러오게 할 수 있어요. 이렇게 하면 보안에 한 겹 더 보태지고, 여러 n8n 환경에서 쓰는 자격증명을 한 곳에서 관리할 수 있어요.

글로벌 볼트 (Global vaults)

기본적으로 시크릿 볼트는 글로벌(global) 이에요. 인스턴스 전체의 사용자가 그 볼트의 시크릿을 참조하는 자격증명을 쓸 수 있어요.

개인 프로젝트에서는 인스턴스 소유자와 관리자만 글로벌 볼트의 시크릿을 자격증명에 쓸 수 있어요.

프로젝트 볼트 (Project vaults)

인스턴스 관리자는 볼트를 특정 프로젝트와 공유할 수 있어요. 볼트를 프로젝트에 지정하면 그 프로젝트의 자격증명만 그 볼트의 시크릿을 참조할 수 있어요. 볼트를 단일 프로젝트에 묶을지, 글로벌로 유지할지 선택할 수 있어요.

볼트 범위를 바꾸려면:

n8n에서 Settings > External Secrets로 가요.
구성할 볼트를 찾아 Edit을 선택해요.
Share에서 다음 중 하나를 선택해요.
- Global: 이 볼트를 n8n 인스턴스 전체에 공유해요. 인스턴스 전체의 자격증명이 이 시크릿을 참조할 수 있어요.
- Project: 이 볼트를 특정 프로젝트로 제한해요. 프로젝트를 선택하면 시크릿 접근을 그 프로젝트의 자격증명으로만 한정해요.
Save로 구성을 저장해요.

n8n을 시크릿 저장소에 연결하기

💡 시크릿 값: n8n은 시크릿 값으로 평문(plaintext)만 지원하고 JSON 객체는 지원하지 않아요.

n8n에서 Settings > External Secrets로 가요.
Add secrets vault를 클릭해요.
볼트에 고유한 이름을 입력해요. 이 이름은 자격증명에서 {{ $secrets.<vault-name>... }} 표현식으로 이 볼트를 참조할 때 첫 번째 세그먼트가 돼요.
지원되는 시크릿 제공자 중 하나를 선택해요.
제공자의 자격증명을 입력해요. 자세한 내용은 아래 제공자별 섹션을 참고하세요.
Save로 구성을 저장해요.

이 저장소가 연결되어 있는 동안 자격증명에서 그 시크릿을 참조할 수 있어요.

1Password

1Password Connect Server 필요: n8n은 1Password에 머신 접근하기 위한 셀프호스팅 API인 1Password Connect Server와 통합해요. 이건 개인/팀 1Password 계정과는 달라요. 이 제공자를 쓰려면 Connect Server를 직접 배포·실행해야 해요.

Connect Server URL과 Access Token을 제공해요. Connect Server URL은 서버에 접근할 수 있는 주소(예: http://localhost:8080)예요. Access Token은 Connect Server 통합용으로 만든 토큰이에요.

n8n은 토큰이 접근할 수 있는 모든 볼트와 아이템을 읽어요. 각 1Password 아이템이 시크릿이 되고, 아이템의 필드는 속성으로 접근 가능해요. 특정 필드 값을 접근하려면 {{ $secrets.<vault-name>.<item-title>.<field-label> }}을 사용해요.

AWS Secrets Manager

인증 방법을 선택해요.

IAM User: IAM 사용자의 access key ID, secret access key, region을 제공해요.
Auto Detect: n8n이 AWS SDK 기본 자격증명 체인으로 n8n이 실행되는 환경(예: 환경 변수, 공유 자격증명 파일, EC2/ECS/EKS 인스턴스 역할)에서 자격증명을 자동으로 찾아요. n8n이 이미 AWS 자격증명이 있는 어딘가에서 실행되고 있다면, 장기 보관용 access key를 관리하지 않아도 되므로 이 방식을 쓰면 좋아요.

어느 방법을 선택하든, 기본 IAM 아이덴티티는 secretsmanager:ListSecrets, secretsmanager:BatchGetSecretValue, secretsmanager:GetSecretValue 권한을 가져야 해요.

⚠️ Auto Detect와 시크릿 스코핑

Auto Detect는 n8n이 그 볼트에 어떤 자격증명 입력도 받지 않고, 실행 환경에 있는 아이덴티티를 그대로 해석해요. 즉 같은 n8n 인스턴스에서 Auto Detect로 구성한 모든 볼트가 하나의 IAM 아이덴티티와 권한 세트를 공유해요. Auto Detect 볼트마다 다른 IAM 스코프(예: 한 볼트는 프로젝트 A의 시크릿으로, 다른 볼트는 프로젝트 B의 시크릿으로 제한)를 지정할 수 없어요.

볼트·프로젝트·팀별로 시크릿 접근을 스코프해야 한다면 IAM User를 쓰세요. 볼트마다 별도 IAM 사용자와 access key를 만들고, 각각에 ARN 스코프 정책을 붙여요(아래 제한적 ARN 스코프 정책 예시 참고). Auto Detect는 단일 글로벌 볼트나, 그 볼트를 공유하는 모든 프로젝트에 같은 AWS 접근을 줘도 되는 구성에 가장 적합해요.

AWS Secrets Manager의 모든 시크릿에 n8n 접근을 주려면 IAM 사용자에게 다음 정책을 붙일 수 있어요.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "AccessAllSecrets",
			"Effect": "Allow",
			"Action": [
				"secretsmanager:ListSecrets",
				"secretsmanager:BatchGetSecretValue",
				"secretsmanager:GetResourcePolicy",
				"secretsmanager:GetSecretValue",
				"secretsmanager:DescribeSecret",
				"secretsmanager:ListSecretVersionIds"
			],
			"Resource": "*"
		}
	]
}

더 제한적으로 해서 n8n이 특정 AWS Secrets Manager 시크릿에만 접근하도록 할 수도 있어요. 그 경우에도 리소스 전체에 secretsmanager:ListSecrets와 secretsmanager:BatchGetSecretValue 권한을 허용해야 해요. 이 권한들은 n8n이 ARN 스코프 시크릿을 검색(retrieve)하게 하지만, 시크릿 값에 대한 접근은 제공하지 않아요.

그다음 secretsmanager:GetSecretValue 권한의 스코프를 n8n과 공유할 시크릿의 특정 ARN(Amazon Resource Names) 으로 설정해야 해요. 각 리소스 ARN에서 올바른 리전과 계정 ID를 사용해야 해요. ARN 상세는 AWS 대시보드의 시크릿에서 확인할 수 있어요.

예를 들어 다음 IAM 정책은 지정된 AWS 계정·리전에서 이름이 n8n으로 시작하는 시크릿에만 접근을 허용해요.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "ListingSecrets",
			"Effect": "Allow",
			"Action": [
				"secretsmanager:ListSecrets",
				"secretsmanager:BatchGetSecretValue"
			],
			"Resource": "*"
		},
		{
			"Sid": "RetrievingSecrets",
			"Effect": "Allow",
			"Action": [
				"secretsmanager:GetSecretValue",
				"secretsmanager:DescribeSecret"
			],
			"Resource": [
				"arn:aws:secretsmanager:us-west-2:123456789000:secret:n8n*"
			]
		}
	]
}

더 많은 IAM 권한 정책 예시는 AWS 문서를 참고하세요.

Azure Key Vault

기능 제공 범위: Azure Cloud 설정은 n8n 2.35.0부터 사용 가능해요. 이전 버전은 Azure Public Cloud에만 연결해요. 기존 구성은 변경 없이 Azure Public Cloud를 계속 사용해요.

tenant ID, client ID, client secret을 제공해요. Microsoft Entra ID 앱을 등록하고 서비스 주체를 만드는 방법은 Azure 문서의 register a Microsoft Entra ID app and create a service principal을 참고하세요. n8n은 시크릿에 대해 한 줄 값만 지원해요.

Key Vault가 호스팅되는 Azure Cloud 환경을 선택해요. 이 설정이 볼트 URL과 Microsoft Entra 기관(authority) 호스트를 결정해요.

Azure Cloud	Vault URL 접미사	Entra authority host
Azure Public Cloud (기본)	`vault.azure.net`	`https://login.microsoftonline.com`
Azure US Government	`vault.usgovcloudapi.net`	`https://login.microsoftonline.us`
Azure China	`vault.azure.cn`	`https://login.partner.microsoftonline.cn`
Custom	전체 URL을 직접 제공	호스트를 직접 제공

Azure Public Cloud, Azure US Government, Azure China에서는 Vault Name을 제공해요. n8n이 이름과 선택한 클라우드의 접미사로 볼트 URL을 만들어요.

Custom에서는 볼트 이름 대신 전체 Vault URL(예: https://my-vault.vault.usgovcloudapi.net)을 제공해요. 다른 Microsoft Entra 기관에 인증하려면 선택적으로 Authority Host(예: https://login.microsoftonline.us)도 설정할 수 있어요. Authority Host를 비워두면 기본값(https://login.microsoftonline.com)을 사용해요. Azure Stack이나 프록시 환경 같은 구성에 Custom을 쓰세요.

GCP Secrets Manager

다음 최소 역할을 가진 서비스 계정의 Service Account Key(JSON)를 제공해요: Secret Manager Secret Accessor, Secret Manager Secret Viewer. 자세한 내용은 Google의 service account documentation을 참고하세요.

HashiCorp Vault

볼트 인스턴스의 Vault URL을 제공하고 Authentication Method를 선택해요. 인증 세부 정보를 입력해요. 선택적으로 네임스페이스를 제공해요.

인증 방법에 대한 HashiCorp 문서:
볼트 네임스페이스를 쓴다면 n8n이 연결할 네임스페이스를 입력할 수 있어요. 네임스페이스에 대한 자세한 내용은 Vault Enterprise namespaces를 참고하세요.

수동 KV 마운트 구성

기본적으로 n8n은 sys/mounts를 읽어 KV 시크릿 엔진을 자동 탐지해요. Vault 토큰에 sys/mounts 접근 권한이 없다면 KV 엔진 마운트 경로와 버전을 수동으로 지정할 수 있어요.

KV Mount Path: KV 시크릿 엔진의 마운트 경로(예: secret/). 설정하면 n8n은 sys/mounts 자동 탐지를 건너뛰고 이 경로를 직접 사용해요. 비워두면 자동 탐지를 사용해요.
KV Version: KV 엔진 버전(v1 또는 v2). 기본값은 v2예요. KV Mount Path를 지정했을 때만 적용돼요.

Vault 토큰은 여전히 KV 경로 자체에 대한 읽기·목록 접근이 필요해요. 다음은 secret/에 마운트된 KV v2에 대한 최소 Vault 정책 예시예요.

# Read and list secrets at the "secret/" KV v2 mount
path "secret/data/*" {
  capabilities = ["read"]
}
path "secret/metadata/*" {
  capabilities = ["read", "list"]
}

KV v1은 정책 경로 하나만 있으면 돼요.

# Read and list secrets at the "kv/" KV v1 mount
path "kv/*" {
  capabilities = ["read", "list"]
}

Infisical

기능 제공 범위: Infisical 시크릿 관리 지원은 n8n 2.26.0부터 사용 가능해요.

Infisical에 연결하려면 다음을 제공해요.

Site URL: Infisical 인스턴스의 기본 URL. 기본값은 https://app.infisical.com이에요. Infisical을 셀프호스팅할 때만 바꾸세요.
Project ID: 시크릿을 읽을 Infisical 프로젝트의 ID.
Environment: 환경 슬러그(예: dev, staging, prod).
Secret Path: 프로젝트 안에서 시크릿을 읽을 경로. 기본값은 /이에요.
Authentication Method: Universal Auth(권장) 또는 Access Token을 선택해요.

n8n은 Infisical Machine Identity를 사용하는 Universal Auth를 권장해요. 토큰은 만료 전에 자동으로 갱신돼요.

Infisical에서 타깃 프로젝트의 시크릿을 읽을 권한을 Machine Identity에 부여해요. 내장 Viewer 역할로 충분하며, 타깃 환경·시크릿 경로에서 secrets 권한 Read Value와 Describe Secret을 부여하는 커스텀 역할을 만들어도 돼요. 자세한 내용은 Infisical의 project role docs를 참고하세요.

Universal Auth — 제공할 것:

Client ID: 머신 아이덴티티의 Client ID.
Client Secret: 머신 아이덴티티의 Client Secret.

Infisical에서 머신 아이덴티티를 만들고 위 역할로 프로젝트에 연결한 뒤, Client ID와 Client Secret을 복사해요. 자세한 내용은 Infisical의 Universal Auth docs를 참고하세요.

Access Token — 제공할 것:

Access Token: 머신 아이덴티티 안에서 발급된 토큰.

Infisical에서 머신 아이덴티티를 만들고 위 역할로 프로젝트에 연결한 뒤, Add Auth Method를 클릭하고 Token Auth를 선택해요. 자세한 내용은 Infisical의 Token auth docs를 참고하세요.

n8n 자격증명에서 시크릿 사용하기

저장소의 시크릿을 n8n 자격증명에서 쓰려면:

새 자격증명을 만들거나 기존 것을 열어요.
시크릿을 쓰고 싶은 필드에서:
1. 필드 위에 마우스를 올려요.
2. Expression을 선택해요.
시크릿을 쓰고 싶은 필드에 시크릿 이름을 참조하는 표현식[^2]을 입력해요.
```
{{ $secrets.<vault-name>.<secret-name> }}
```
<vault-name>은 저장소를 추가할 때 입력한 이름이에요. <secret-name>은 내 볼트에 나타나는 이름으로 바꿔요.

n8n 환경과 함께 외부 시크릿 사용하기

n8n의 소스 컨트롤과 환경 기능은 Git 기반으로 서로 다른 n8n 환경을 만들게 해줘요. 이 기능은 인스턴스마다 다른 자격증명을 사용하는 걸 지원하지 않아요. 외부 시크릿 볼트를 쓰면 각 n8n 인스턴스를 다른 볼트나 프로젝트 환경에 연결해서 환경마다 다른 자격증명을 제공할 수 있어요.

예를 들어 개발용과 프로덕션용 n8n 인스턴스 두 개가 있다고 해요. 시크릿 제공자에서 development와 production 두 환경을 가진 프로젝트를 만들어요. 제공자의 각 환경용 토큰을 생성해요. development 환경의 토큰으로 개발 n8n 인스턴스를, production 환경의 토큰으로 프로덕션 n8n 인스턴스를 연결해요.

프로젝트에서 외부 시크릿 사용하기

볼트를 프로젝트와 공유해서 그 프로젝트의 자격증명만 그 시크릿을 참조하게 할 수 있어요. 설정 단계는 프로젝트 볼트를 참고하세요. 프로젝트 스코프 볼트는 n8n 2.11.0부터 사용 가능해요.

프로젝트 역할의 접근

기능 제공 범위: 프로젝트 편집자·관리자에게 외부 시크릿 접근을 부여하는 것은 n8n 2.13.0부터 가능해요. n8n 2.13.0 이전에는 RBAC 프로젝트에서 외부 시크릿을 쓰려면 인스턴스 소유자 또는 인스턴스 관리자가 프로젝트 멤버로 있어야 했어요.

n8n 2.13.0부터 인스턴스 소유자·관리자는 프로젝트 편집자와 프로젝트 관리자에게 외부 시크릿 접근을 부여할 수 있어요.

활성화하려면:

Settings > External Secrets로 가요.
Enable external secrets for project roles을 켜요.

활성화하면 Project Editors는 다음을 할 수 있어요.

프로젝트와 공유된 사용 가능한 외부 시크릿 볼트 보기 (Project > Settings)
프로젝트 볼트의 시크릿을 자격증명에서 사용

Project Admins는 같은 접근에 더해 다음도 할 수 있어요.

프로젝트용 새 볼트 만들기 (Project > Settings)
프로젝트에 지정된 볼트 갱신·삭제

글로벌 볼트 접근: Settings > External Secrets에서 만든 글로벌 볼트는 Project > Settings에 보이지만 프로젝트 역할에게 읽기 전용이에요. 글로벌 볼트를 수정·삭제할 수 있는 건 인스턴스 관리자뿐이에요.

커스텀 역할

더 세밀한 접근 제어를 위해 인스턴스 소유자·관리자는 커스텀 프로젝트 역할을 만들 수 있어요. Settings > Roles > Project roles > Create role로 가요. 권한 목록에서 다음을 구성해요.

Secrets vaults: 볼트 관리(보기·생성·편집·삭제·동기화)를 통제해요.
Secrets: 역할이 자격증명 표현식에서 시크릿을 쓸 수 있는지 통제해요.

두 권한은 서로 독립적이에요. 예를 들어 역할이 볼트를 관리하지 않고 자격증명에서 시크릿만 쓰면 될 때 Secrets 권한만 필요할 수 있어요. 사용 가능한 스코프 전체 목록은 Secret vault scopes를 참고하세요.

문제 해결

프로덕션에서 시크릿이 해석되지 않아요

기능 제공 범위: 프로젝트 역할의 접근에서 설명한 대로 프로젝트 편집자·관리자로서 자격증명에서 외부 시크릿을 쓰는 것은 n8n 2.13.0부터 가능해요. 아래 제한은 더 오래된 버전 또는 옵트인 토글이 꺼져 있을 때만 적용돼요.

n8n 2.13.0 이전 버전(또는 Enable external secrets for project roles가 꺼져 있을 때)에는 인스턴스 소유자와 관리자만 실행 시점에 시크릿을 해석할 수 있어요. 소유자·관리자가 다른 사용자의 자격증명을 시크릿 표현식으로 갱신하면, 미리보기에서는 동작하는 것처럼 보여도 프로덕션에서는 실패할 수 있어요.

이 경우 인스턴스 소유자·관리자가 소유한 자격증명에서만 외부 시크릿을 사용하세요.

자격증명을 보호하고 공유하는 다른 방법은 자격증명 관리를 참고하세요.

더 알아보기 (Learn more)

자격증명 관리

[^1]: n8n에서 자격증명은 특정 앱·서비스에 연결하기 위한 인증 정보를 저장해요. 인증 정보(사용자 이름·비밀번호, API 키, OAuth 시크릿 등)로 자격증명을 만든 뒤 해당 앱 노드로 서비스와 상호작용할 수 있어요.

[^2]: n8n에서 표현식은 JavaScript 코드를 실행해서 노드 파라미터를 동적으로 채우게 해줘요. 정적 값을 주는 대신 n8n 표현식 문법으로 이전 노드·다른 워크플로·내 n8n 환경의 데이터로 값을 정의할 수 있어요.