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

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

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

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

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

시작하기 전에#

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

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

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

n8n 3.0부터 암호화 키 로테이션은 기본으로 켜져 있어 설정할 것이 없습니다. 업그레이드 후 처음 시작할 때 n8n이 초기 데이터 암호화 키를 생성하고 암호화된 상태로 데이터베이스에 저장합니다.

n8n 2.x에서는 직접 기능을 켭니다.

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

   N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true
   

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

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

활성 키 로테이션#

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

UI 사용#

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

API 사용#

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

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

암호화 키 로테이션 끄기#

n8n 2.40.3부터 암호화 키 로테이션을 다시 끌 수 있습니다. 메인 인스턴스와 워커를 포함한 모든 n8n 인스턴스에 다음 환경 변수를 설정한 다음 다시 시작합니다.

N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=false

n8n 2.40.3 이전 버전에서는 n8n이 새로운 형식으로 데이터를 기록한 뒤 기능을 끄면 해당 데이터에 영구적으로 접근할 수 없게 됩니다. 먼저 n8n 2.40.3으로 업그레이드하세요.

하위 호환성 및 롤백#

암호화 키 로테이션이 켜지면 n8n은 키 식별자를 포함하는 새로운 형식으로 자격 증명 및 기타 민감한 데이터를 기록합니다. 이전 버전의 n8n은 이 형식을 읽을 수 없습니다.

• n8n이 새로운 형식으로 데이터를 기록한 후에는 n8n 버전을 다운그레이드하지 마세요. 이전 버전은 이를 복호화할 수 없습니다.
• n8n 2.40.3부터는 기능을 안전하게 끌 수 있습니다. 이전 버전에서 N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION을 false로 설정하면 기능을 켠 이후 암호화된 모든 데이터에 영구적으로 접근할 수 없게 됩니다.

새로운 형식으로 암호화된 데이터를 레거시 형식으로 다시 변환하는 자동화된 도구는 없습니다. 읽을 수 없는 n8n 버전을 사용하게 된 경우, 유일한 복구 경로는 데이터베이스 백업에서 복원하는 것입니다.

권장 절차#

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

관련 리소스#

• 보안: 셀프 호스팅 인스턴스를 점검하고, 강화하고, 제한합니다.
• 사용자 지정 암호화 키 설정: 인스턴스 수준의 N8N_ENCRYPTION_KEY 값을 설정합니다.
• 배포 환경 변수: N8N_ENCRYPTION_KEY 및 N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION에 대한 참조입니다.
• 큐 모드 구성: 모든 워커가 동일한 인스턴스 암호화 키를 공유하는지 확인하세요.
• n8n 3.0 주요 변경 사항: 암호화 키 로테이션을 포함해 업그레이드할 때 달라지는 내용입니다.