n8n의 자격 증명을 관리하기 위해 외부 시크릿 저장소를 사용할 수 있습니다.

n8n은 모든 자격 증명을 데이터베이스에 암호화하여 저장하고, 기본적으로 접근을 제한합니다. 외부 시크릿 기능을 사용하면 민감한 자격 증명 정보를 외부 볼트에 저장하고, 필요할 때 n8n이 불러오도록 할 수 있습니다. 이를 통해 보안을 한 층 강화하고, 여러 n8n 환경에서 사용되는 자격 증명을 한 곳에서 관리할 수 있습니다.

글로벌 볼트#

기본적으로 시크릿 볼트는 글로벌입니다. 즉, 인스턴스의 모든 사용자가 해당 볼트의 시크릿을 참조하는 자격 증명을 사용할 수 있습니다.

개인 프로젝트에서는 인스턴스 소유자와 관리자만 글로벌 볼트의 시크릿을 자격 증명에 사용할 수 있습니다.

프로젝트 볼트#

인스턴스 관리자는 특정 프로젝트와 볼트를 공유할 수 있습니다. 볼트를 프로젝트에 할당하면 해당 프로젝트의 자격 증명만 볼트의 시크릿을 참조할 수 있습니다. 볼트를 단일 프로젝트에만 연결하거나 글로벌로 유지하도록 선택할 수 있습니다.

볼트 범위를 변경하려면:

1. n8n에서 Settings > External Secrets로 이동합니다.
2. 설정할 볼트를 찾아 Edit를 선택합니다.
3. Share 아래에서 다음 중 하나를 선택합니다:
   • Global: 전체 n8n 인스턴스에서 이 볼트를 공유합니다. 인스턴스 전체의 자격 증명이 이 시크릿을 참조할 수 있습니다.
   • Project: 이 볼트를 특정 프로젝트로 제한합니다. 프로젝트를 선택하면 해당 프로젝트의 자격 증명만 시크릿에 접근할 수 있습니다.
4. 설정을 Save합니다.

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

1. n8n에서 Settings > External Secrets로 이동합니다.
2. Add secrets vault를 클릭합니다.
3. 볼트의 고유한 이름을 입력합니다. 이 이름은 자격 증명의 {{ $secrets.<vault-name>... }} 표현식에서 볼트를 참조할 때 첫 번째 세그먼트로 사용됩니다.
4. 지원되는 시크릿 제공업체 중 하나를 선택합니다.
5. 제공업체의 자격 증명을 입력합니다. 자세한 내용은 아래 제공업체별 섹션을 참조하세요.
6. 설정을 Save합니다.

이 저장소가 연결되어 있는 한 자격 증명에서 시크릿을 참조할 수 있습니다.

1Password#

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#

액세스 키 ID, 시크릿 액세스 키, 리전을 입력합니다. IAM 사용자에게는 secretsmanager:ListSecrets, secretsmanager:BatchGetSecretValue, secretsmanager:GetSecretValue 권한이 있어야 합니다.

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": "*"
		}
	]
}

더 세밀하게 제한하여 특정 AWS Secrets Manager 시크릿에만 n8n 접근 권한을 부여할 수도 있습니다. 모든 리소스에 대해 secretsmanager:ListSecrets와 secretsmanager:BatchGetSecretValue 권한은 계속 허용해야 합니다. 이 권한은 n8n이 ARN 범위의 시크릿을 가져올 수 있도록 하지만, 시크릿 값에 대한 접근은 허용하지 않습니다.

그 다음, n8n과 공유할 특정 시크릿의 Amazon Resource Names(ARN)에 secretsmanager:GetSecretValue 권한의 범위를 설정해야 합니다. 각 리소스 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#

볼트 이름, 테넌트 ID, 클라이언트 ID, 클라이언트 시크릿을 입력합니다. Microsoft Entra ID 앱을 등록하고 서비스 주체를 만드는 방법은 Azure 문서 Microsoft Entra ID 앱 등록 및 서비스 주체 만들기를 참조하세요. n8n은 시크릿에 대해 한 줄짜리 값만 지원합니다.

GCP Secrets Manager#

최소한 Secret Manager Secret Accessor와 Secret Manager Secret Viewer 역할을 가진 서비스 계정의 Service Account Key(JSON)를 입력합니다. 자세한 내용은 Google의 서비스 계정 문서를 참조하세요.

HashiCorp Vault#

볼트 인스턴스의 Vault URL을 입력하고 Authentication Method를 선택합니다. 인증 세부 정보를 입력합니다. 선택적으로 네임스페이스를 제공할 수 있습니다.

• 사용하는 인증 방법에 대한 HashiCorp 문서를 참조하세요:
  • Token auth method
  • AppRole auth method
  • Userpass auth method
• 볼트 네임스페이스를 사용하는 경우 n8n이 연결할 네임스페이스를 입력할 수 있습니다. HashiCorp Vault 네임스페이스에 대한 자세한 내용은 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을 연결하려면 다음 정보를 입력하세요:

• 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{:target="_blank" .external-link}를 사용하는 Universal Auth를 권장합니다. 토큰은 만료 전에 자동으로 갱신됩니다.

Infisical에서 Machine Identity에 타깃 프로젝트의 시크릿을 읽을 수 있는 역할을 부여하세요. 내장된 Viewer 역할을 사용하거나, 타깃 환경 및 시크릿 경로에 대해 secrets 권한의 Read Value와 Describe Secret을 부여하는 커스텀 역할을 만들 수 있습니다. Infisical의 프로젝트 역할 문서{:target="_blank" .external-link}를 참조하세요.

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

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

1. 새 자격 증명을 만들거나 기존 자격 증명을 엽니다.
2. 시크릿을 사용할 필드에서:
   1. 필드 위로 마우스를 가져갑니다.
   2. Expression을 선택합니다.
3. 시크릿을 사용할 필드에 시크릿 이름을 참조하는 표현식을 입력합니다:

   {{ $secrets.<vault-name>.<secret-name> }}
   

   <vault-name>은 저장소를 추가할 때 입력한 이름입니다. <secret-name>은 볼트에 표시되는 이름으로 교체하세요.

n8n 환경에서 외부 시크릿 사용하기#

n8n의 소스 컨트롤 및 환경 기능을 사용하면 Git을 기반으로 다양한 n8n 환경을 만들 수 있습니다. 이 기능은 서로 다른 인스턴스에서 다른 자격 증명을 사용하는 것을 지원하지 않습니다. 외부 시크릿 볼트를 사용하면 각 n8n 인스턴스를 서로 다른 볼트 또는 프로젝트 환경에 연결하여 환경마다 다른 자격 증명을 제공할 수 있습니다.

예를 들어, 개발용과 프로덕션용 n8n 인스턴스가 각각 있다고 가정합니다. 시크릿 제공업체에서 개발과 프로덕션, 두 가지 환경을 가진 프로젝트를 만듭니다. 각 환경에 대한 토큰을 생성합니다. 개발 환경의 토큰을 사용하여 개발용 n8n 인스턴스를 연결하고, 프로덕션 환경의 토큰을 사용하여 프로덕션 n8n 인스턴스를 연결합니다.

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

볼트를 프로젝트와 공유하여 해당 프로젝트의 자격 증명만 볼트의 시크릿을 참조하도록 할 수 있습니다. 설정 단계는 프로젝트 볼트를 참조하세요. 프로젝트 범위 볼트는 버전 2.11.0부터 사용할 수 있습니다.

프로젝트 역할에 대한 접근 권한#

버전 2.13.0부터 인스턴스 소유자와 관리자는 프로젝트 편집자와 프로젝트 관리자에게 외부 시크릿 접근 권한을 부여할 수 있습니다.

이를 활성화하려면:

1. Settings > External Secrets로 이동합니다.
2. Enable external secrets for project roles를 켭니다.

활성화하면 Project Editors가 할 수 있는 작업:

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

Project Admins는 위와 동일한 권한에 더해 다음도 가능합니다:

• 프로젝트용 새 볼트 생성(Project > Settings에서).
• 프로젝트에 할당된 볼트 업데이트 및 삭제.

커스텀 역할#

더 세밀한 접근 제어를 위해 인스턴스 소유자와 관리자는 커스텀 프로젝트 역할을 만들 수 있습니다. Settings > Project roles > Create role로 이동합니다. 권한 목록에서 다음을 설정합니다:

• Secrets vaults: 볼트 관리(보기, 만들기, 편집, 삭제, 동기화)를 제어합니다.
• Secrets: 역할이 자격 증명 표현식에서 시크릿을 사용할 수 있는지 제어합니다.

두 권한은 독립적입니다. 예를 들어, 볼트를 관리하지 않고 자격 증명에서 시크릿만 사용하는 역할에는 Secrets 권한만 필요할 수 있습니다. 사용 가능한 전체 범위 목록은 시크릿 볼트 범위를 참조하세요.

문제 해결#

프로덕션에서 시크릿이 해석되지 않는 경우#

버전 2.13.0 이전(또는 Enable external secrets for project roles가 꺼진 경우), 런타임에 시크릿을 해석할 수 있는 사용자는 인스턴스 소유자와 관리자뿐입니다. 소유자나 관리자가 다른 사용자의 자격 증명을 시크릿 표현식으로 업데이트하면, 미리보기에서는 작동하는 것처럼 보이지만 프로덕션에서는 실패할 수 있습니다.

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