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

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

전역 볼트#

기본적으로 시크릿 볼트는 **전역(global)**입니다. 인스턴스 전체의 사용자가 해당 볼트의 시크릿을 참조하는 자격 증명을 사용할 수 있습니다.

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

프로젝트 볼트#

인스턴스 관리자는 볼트를 특정 프로젝트와 공유할 수 있습니다. 볼트를 프로젝트에 할당하면 해당 프로젝트의 자격 증명만 그 볼트의 시크릿을 참조할 수 있습니다. 볼트를 단일 프로젝트에 종속시키거나 전역으로 유지할 수 있습니다.

볼트 범위를 변경하려면:

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#

access key ID, secret access key, region을 입력합니다. 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 Secret Manager 시크릿에 대한 접근만 부여할 수도 있습니다. 모든 리소스에 접근하려면 여전히 secretsmanager:ListSecrets와 secretsmanager:BatchGetSecretValue 권한을 허용해야 합니다. 이 권한들은 n8n이 ARN 범위로 지정된 시크릿을 조회할 수 있게 하지만, 시크릿 값에 대한 접근은 제공하지 않습니다.

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

vault name, tenant ID, client ID, client secret을 입력합니다. Microsoft Entra ID 앱을 등록하고 서비스 주체를 만드는 방법은 Azure 문서를 참고하세요. 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 정책을 보여줍니다:

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

KV v1의 경우, 단일 정책 경로만 있으면 됩니다:

# "kv/" KV v1 마운트에서 시크릿 읽기 및 목록 조회
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를 사용하는 Universal Auth를 권장합니다. 토큰은 만료되기 전에 자동으로 갱신됩니다.

Infisical에서, 대상 프로젝트의 시크릿을 읽을 수 있는 권한을 가진 역할을 Machine Identity에 부여하세요. 내장된 Viewer 역할을 사용해도 되고, 대상 환경과 시크릿 경로에 대해 secrets 권한의 Read Value와 Describe Secret을 부여하는 사용자 지정 역할을 만들어도 됩니다. Infisical의 프로젝트 역할 문서를 참고하세요.

Universal Auth

다음을 입력하세요:

• Client ID: 머신 아이덴티티의 Client ID입니다.
• Client Secret: 머신 아이덴티티의 Client Secret입니다.

Infisical에서 머신 아이덴티티를 만들고, 위에서 설명한 역할과 함께 프로젝트에 연결한 다음, Client ID와 Client Secret을 복사하세요. Infisical의 Universal Auth 문서를 참고하세요.

Access Token

다음을 입력하세요:

• Access Token: 머신 아이덴티티 내부에서 발급된 토큰입니다.

Infisical에서 머신 아이덴티티를 만들고, 위에서 설명한 역할과 함께 프로젝트에 연결한 다음, Add Auth Method를 클릭하고 Token Auth를 선택하세요. Infisical의 Token auth 문서를 참고하세요.

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 > Roles > Project roles > Create role로 이동합니다. 권한 목록에서 다음을 구성합니다:

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

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

문제 해결#

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

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

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

Footnotes

1. n8n에서 자격 증명은 특정 앱 및 서비스에 연결하기 위한 인증 정보를 저장합니다. 인증 정보(사용자 이름과 비밀번호, API 키, OAuth 시크릿 등)로 자격 증명을 만든 후, 연결된 앱 노드를 사용해 해당 서비스와 상호작용할 수 있습니다. ↩

2. n8n에서 표현식을 사용하면 JavaScript 코드를 실행하여 노드 매개변수를 동적으로 채울 수 있습니다. 정적 값을 제공하는 대신, n8n 표현식 구문을 사용해 이전 노드, 다른 워크플로, 또는 n8n 환경의 데이터를 기반으로 값을 정의할 수 있습니다. ↩