암호화 키 로테이션을 사용하면 인스턴스의 마스터 암호화 키를 변경하지 않고도 자격 증명, OAuth 토큰 등 n8n 데이터를 암호화하는 키를 주기적으로 교체할 수 있습니다.

암호화 키 로테이션 작동 방식#

n8n은 2계층 키 모델을 사용합니다.

• 인스턴스 암호화 키(N8N_ENCRYPTION_KEY): 배포 시점에 설정하는 마스터 키입니다. 이 키는 절대 변경되지 않습니다. n8n은 이 키를 데이터 암호화 키를 보호하는 용도로만 사용합니다.
• 데이터 암호화 키: 자격 증명 데이터를 직접 암호화하는 키입니다. 이 키가 바로 로테이션 대상입니다. n8n은 이 키를 인스턴스 키로 보호된 상태로 암호화하여 데이터베이스에 저장합니다.

로테이션을 실행하면 n8n은 새로운 데이터 암호화 키를 생성하고 이후의 모든 쓰기 작업에 이 키를 사용합니다. 이전 키로 암호화된 기존 데이터는 계속 읽을 수 있습니다. n8n은 각 레코드가 다음번에 업데이트될 때 해당 레코드를 새 키로 자동 재암호화합니다.

시작하기 전에#

또한 다음 사항을 반드시 확인해야 합니다.

• 메인 인스턴스와 모든 워커를 포함한 모든 n8n 인스턴스가 동일한 N8N_ENCRYPTION_KEY 값을 공유해야 합니다.
• 환경 변수와 n8n 데이터베이스를 직접 제어할 수 있어야 합니다. 이는 셀프 호스팅 배포에서만 가능합니다.

암호화 키 로테이션 활성화#

1. 메인 인스턴스와 워커를 포함한 모든 n8n 인스턴스에 다음 환경 변수를 설정합니다.

   N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true
   

2. 모든 인스턴스를 다시 시작합니다. 시작 시 n8n은 초기 데이터 암호화 키를 자동으로 생성하고 암호화된 상태로 데이터베이스에 저장합니다.

3. 기능이 활성화되었는지 확인하려면 Settings > Data Encryption Keys로 이동합니다. 활성 키가 목록에 표시되어야 합니다.

활성 키 로테이션#

기능이 활성화되면 언제든지 새로운 데이터 암호화 키로 로테이션할 수 있습니다.

UI 사용#

Settings > Data Encryption Keys로 이동하여 Rotate key를 선택합니다.

API 사용#

/encryption/keys 엔드포인트에 POST 호출을 보냅니다. 이 요청에는 encryptionKey:manage 전역 스코프가 필요합니다. n8n은 API 응답에서 키 자체를 절대 반환하지 않으며, ID, 알고리즘, 상태, 타임스탬프 같은 메타데이터만 반환합니다.

로테이션 후에는 n8n이 모든 새로운 쓰기 작업에 새로운 활성 키를 사용합니다. 이전 키로 암호화된 레코드는 계속 읽을 수 있습니다. n8n은 각 레코드가 다음번에 업데이트될 때 새 키로 재암호화합니다.

하위 호환성 및 롤백#

암호화 키 로테이션을 활성화하면 n8n은 키 식별자를 포함하는 새로운 형식으로 자격 증명 및 기타 민감한 데이터를 기록하기 시작합니다. 이전 버전의 n8n이나 이 기능 플래그 없이 실행되는 인스턴스는 이 형식을 읽을 수 없습니다.

• 새로운 형식으로 데이터가 기록된 이후에는 기능 플래그를 비활성화하지 마세요. N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION을 제거하거나 false로 설정하면 기능을 활성화한 이후 암호화된 모든 데이터에 영구적으로 접근할 수 없게 됩니다.
• 활성화한 후에는 n8n 버전을 다운그레이드하지 마세요. 이전 버전은 새로운 형식을 복호화할 수 없습니다.

새로운 형식으로 암호화된 데이터를 레거시 형식으로 다시 변환하는 자동화된 도구는 없습니다. 유일한 복구 경로는 기능을 활성화하기 전에 수행한 데이터베이스 백업에서 복원하는 것입니다.

권장 절차#

1. 데이터베이스를 백업합니다. 변경 작업을 하기 전에 전체 스냅샷을 생성합니다.
2. 스테이징 환경에서 먼저 활성화합니다. 프로덕션이 아닌 환경에서 N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true를 설정하고 다시 시작한 다음, 자격 증명이 여전히 올바르게 복호화되는지 확인합니다.
3. 프로덕션 환경에서 활성화합니다. 스테이징 환경에서의 동작을 검증한 후에만 이 작업을 수행합니다.
4. 비활성화하거나 다운그레이드하지 마세요. 프로덕션 데이터가 새로운 형식으로 기록된 이후에는 플래그를 계속 활성화된 상태로 유지하고 동일하거나 더 최신 버전의 n8n을 사용하세요.

관련 리소스#

• 사용자 지정 암호화 키 설정: 인스턴스 수준의 N8N_ENCRYPTION_KEY 값을 설정합니다.
• 배포 환경 변수: N8N_ENCRYPTION_KEY 및 N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION에 대한 참조입니다.
• 큐 모드 구성: 모든 워커가 동일한 인스턴스 암호화 키를 공유하는지 확인하세요.