본문으로 건너뛰기

외부 시크릿

기능 가용성

  • 외부 시크릿 기능은 Enterprise 셀프 호스팅 및 Enterprise Cloud 요금제에서 사용할 수 있습니다.
  • n8n은 다음 시크릿 제공업체를 지원합니다: AWS Secrets Manager, Azure Key Vault, GCP Secrets Manager 및 HashiCorp Vault.
  • n8n 버전 2.10.0부터 각 시크릿 제공업체에 여러 개의 볼트(Vault)를 연결할 수 있습니다. 이전 버전에서는 제공업체당 하나의 볼트만 지원되었습니다.
  • n8n은 HashiCorp Vault Secrets를 지원하지 않습니다.

Infisical 폐기됨

Infisical은 더 이상 사용되지 않습니다. 버전 2.10.0부터 새로운 Infisical 볼트를 연결할 수 없지만, 기존 연결은 당분간 유지됩니다.

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

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

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

시크릿 값

n8n은 일반 텍스트 형식의 시크릿 값만 지원하며, JSON 객체 형식은 지원하지 않습니다.

  1. n8n에서 설정 > 외부 시크릿으로 이동합니다.

  2. 시크릿 볼트 추가를 클릭합니다.

  3. 볼트에 고유한 이름을 입력합니다. 이 이름은 자격 증명 내 표현식({{ $secrets.<볼트 이름>.<시크릿 이름> }})에서 볼트를 참조할 때 사용되는 첫 번째 부분입니다.

  4. 지원되는 시크릿 제공업체를 선택합니다.

  5. 제공업체의 자격 증명을 입력합니다:

    • Azure Key Vault: 볼트 이름, 테넌트 ID, 클라이언트 ID 및 클라이언트 시크릿을 제공합니다. Azure 문서 Microsoft Entra ID 앱 등록 및 서비스 주체 생성을 참조하세요. n8n은 시크릿의 단일 줄 값만 지원합니다.
    • AWS Secrets Manager: 액세스 키 ID, 비밀 액세스 키 및 리전을 제공합니다. IAM 사용자는 secretsmanager:ListSecrets, secretsmanager:BatchGetSecretValue 및 secretsmanager:GetSecretValue 권한을 보유해야 합니다.

n8n이 AWS Secrets Manager의 모든 시크릿에 접근할 수 있도록 하려면 다음 정책을 IAM 사용자에 연결할 수 있습니다. 또는 범위를 좁혀 특정 AWS Secrets Manager 시크릿에만 접근 권한을 부여할 수도 있습니다. 그러나 여전히 모든 리소스에 대한 secretsmanager:ListSecrets 및 secretsmanager:BatchGetSecretValue 권한은 허용되어야 합니다. 이러한 권한을 통해 n8n은 ARN 범위 내의 시크릿 목록을 가져오고 일괄 조회할 수 있지만, 실제 시크릿 값에 접근하려면 추가로 secretsmanager:GetSecretValue 권한이 필요합니다.

다음으로, secretsmanager:GetSecretValue 권한의 범위를 n8n과 공유하려는 특정 Amazon 리소스 이름(ARN)으로 제한해야 합니다. 각 리소스 ARN에 올바른 리전과 계정 ID가 포함되어 있는지 확인하세요. ARN 정보는 AWS 콘솔의 시크릿 상세 페이지에서 확인할 수 있습니다.

추가적인 IAM 권한 정책 예시는 AWS 문서를 참조하세요.

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

   * 사용 중인 인증 방법에 대한 자세한 내용은 HashiCorp 문서를 참조하세요: [Token 인증 방법](<https://developer.hashicorp.com/vault/docs/auth/token>), [AppRole 인증 방법](<https://developer.hashicorp.com/vault/docs/auth/approle>), [Userpass 인증 방법](<https://developer.hashicorp.com/vault/docs/auth/userpass>)
   * Vault 네임스페이스를 사용하는 경우, n8n이 연결해야 할 네임스페이스를 입력할 수 있습니다. HashiCorp Vault 네임스페이스에 대한 자세한 내용은 [Vault Enterprise 네임스페이스](<https://developer.hashicorp.com/vault/docs/enterprise/namespaces>)를 참조하세요.
 * **Google Cloud Platform**: 최소한 `Secret Manager Secret Accessor` 및 `Secret Manager Secret Viewer` 역할을 가진 서비스 계정의 **서비스 계정 키**(JSON 형식)를 제공합니다. 서비스 계정에 대한 자세한 내용은 Google의 [서비스 계정 문서](<https://cloud.google.com/iam/docs/service-account-overview>)를 참조하세요.

6. 저장합니다.

  1. 해당 저장소가 연결된 상태라면 자격 증명에서 그 시크릿을 참조할 수 있습니다.

볼트 공유​

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

인스턴스 관리자는 볼트를 특정 프로젝트로 제한할 수 있습니다. 볼트를 프로젝트에 할당하면 해당 프로젝트의 자격 증명만 시크릿을 참조할 수 있습니다. 볼트를 단일 프로젝트에 바인딩하거나 전역 상태로 유지할 수 있습니다.

공유 범위 설정:

  1. n8n에서 설정 > 외부 시크릿으로 이동합니다.
  2. 구성하려는 볼트를 찾아 편집을 선택합니다.
  3. 공유 아래에서 다음 옵션 중 하나를 선택합니다:
    • 전역(Global): 이 볼트를 전체 n8n 인스턴스에서 공유하여 인스턴스 내 모든 자격 증명이 해당 시크릿을 참조할 수 있도록 합니다.
    • 프로젝트(Project): 이 볼트를 특정 프로젝트로 제한합니다. 프로젝트를 선택하면 해당 프로젝트의 자격 증명만 시크릿에 접근할 수 있습니다.
  4. 저장합니다.

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

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

  1. 새 자격 증명을 생성하거나 기존 자격 증명을 엽니다.
  2. 시크릿을 사용하려는 필드에서:
    1. 해당 필드 위에 마우스를 올립니다.
    2. 표현식(Expression) 을 선택합니다.
  3. 해당 필드에 시크릿 이름을 참조하는 표현식을 입력합니다:
{{ $secrets.<볼트 이름>.<시크릿 이름> }}

<볼트 이름>은 저장소를 추가할 때 입력한 이름입니다. <시크릿 이름>은 볼트에 표시된 실제 시크릿 이름으로 바꾸세요.

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

n8n의 소스 코드 제어 및 환경 기능을 사용하면 Git을 기반으로 서로 다른 n8n 환경을 생성할 수 있습니다. 이 기능은 서로 다른 인스턴스에서 서로 다른 자격 증명을 사용하는 것을 지원하지 않습니다. 그러나 외부 시크릿 볼트를 활용해 각 n8n 인스턴스를 서로 다른 볼트나 프로젝트 환경에 연결함으로써, 서로 다른 환경에 대해 서로 다른 자격 증명을 제공할 수 있습니다. 예를 들어, 개발용과 프로덕션용으로 두 개의 n8n 인스턴스가 있다고 가정해 봅시다. 시크릿 제공업체 내에 개발 및 프로덕션 환경을 포함하는 프로젝트를 생성하고, 각 환경에 대해 토큰을 생성합니다. 개발 환경의 토큰을 사용해 개발용 n8n 인스턴스를 연결하고, 프로덕션 환경의 토큰을 사용해 프로덕션용 n8n 인스턴스를 연결합니다.

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

RBAC 프로젝트에서 외부 시크릿을 사용하려면 인스턴스 소유자 또는 인스턴스 관리자를 프로젝트 멤버로 추가해야 합니다.

공유 볼트 기능을 사용하여 볼트를 특정 프로젝트로 제한할 수 있습니다. 프로젝트에 할당된 볼트는 해당 프로젝트의 자격 증명에서만 사용할 수 있습니다.

문제 해결​

인스턴스 소유자 또는 관리자가 소유한 자격 증명에만 외부 시크릿 사용하기​

인스턴스 소유자 및 관리자는 권한이 높기 때문에 다른 사용자가 소유한 자격 증명을 시크릿 표현식으로 업데이트할 수 있습니다. 인스턴스 소유자나 관리자 입장에서는 미리보기 시 정상적으로 작동하는 것처럼 보일 수 있지만, 워크플로가 프로덕션 환경에서 실행될 때 시크릿이 해결되지 않을 수 있습니다.

외부 시크릿은 인스턴스 관리자 또는 소유자가 소유한 자격 증명에만 사용하세요. 이렇게 하면 프로덕션 환경에서도 올바르게 해결되도록 보장할 수 있습니다.