외부 시크릿 스토어를 사용하여 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 권한이 있어야 합니다.

n8n에게 AWS Secrets Manager의 모든 시크릿에 대한 접근 권한을 부여하려면 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 범위 시크릿을 검색할 수 있게 하지만 시크릿 값에 대한 접근은 제공하지 않습니다.

그 다음, n8n과 공유할 시크릿의 특정 Amazon Resource Names(ARN)로 secretsmanager:GetSecretValue 권한의 범위를 설정해야 합니다. 각 리소스 ARN에서 올바른 리전과 계정 ID를 사용하는지 확인하세요. AWS 대시보드의 시크릿에서 ARN 세부 정보를 찾을 수 있습니다.

예를 들어, 다음 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 문서를 참조하세요. n8n은 시크릿에 대한 단일 라인 값만 지원합니다.

GCP Secrets Manager#

최소 Secret Manager Secret Accessor 및 Secret Manager Secret Viewer 역할이 있는 서비스 계정의 서비스 계정 키(JSON)를 제공합니다. 자세한 내용은 Google의 서비스 계정 문서를 참조하세요.

HashiCorp Vault#

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

• 인증 방법에 대한 HashiCorp 문서를 참조하세요:
  • Token 인증 방법
  • AppRole 인증 방법
  • Userpass 인증 방법
• 볼트 네임스페이스를 사용하는 경우 n8n이 연결할 네임스페이스를 입력할 수 있습니다. HashiCorp Vault 네임스페이스에 대한 자세한 내용은 Vault Enterprise 네임스페이스를 참조하세요.

수동 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 정책을 보여줍니다:

# "secret/" KV v2 마운트에서 시크릿 읽기 및 목록 조회
path "secret/data/*" {
  capabilities = ["read"]
}
path "secret/metadata/*" {
  capabilities = ["read", "list"]
}

KV v1의 경우 단일 정책 경로만 필요합니다:

# "kv/" KV v1 마운트에서 시크릿 읽기 및 목록 조회
path "kv/*" {
  capabilities = ["read", "list"]
}

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 인스턴스를 연결하고, 프로덕션 환경용 토큰을 사용하여 프로덕션 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 권한만 필요할 수 있습니다. 사용 가능한 범위의 전체 목록은 Secret vault scopes를 참조하세요.

문제 해결#

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

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

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