쿼리 파라미터 검증으로 n8n 웹훅 엔드포인트 보안 강화 - n8n 워크플로우

기본 인증 기능이 없는 시스템(예: Google 스프레드시트, 기본 HTML 폼)에서 간단한 웹훅을 사용하는 사용자.
고급 인증 방식 사용이 어려울 때 n8n 트리거를 보호할 안정적인 방법을 찾는 개발자 및 n8n 전문가.

• n8n 템플릿을 활용하며 승인된 호출만 핵심 n8n 워크플로우 로직을 실행하도록 보장해야 하는 모든 사용자.

기본적으로 n8n은 기본 인증(Basic Auth)이나 JWT 같은 강력한 내장 인증 방식을 제공하지만, Google 스프레드시트의 간단한 버튼이나 기본 IoT 기기와 같은 일부 외부 서비스는 복잡한 인증 헤더를 지원하지 못할 수 있습니다. 이 필수적인 n8n 워크플로우는 필수 쿼리 파라미터를 통한 검증을 적용하여 이 문제를 해결하고, 외부에 노출된 n8n 트리거의 보안을 보장합니다.

이 방식은 중요한 1차 방어선 역할을 합니다. n8n 노드로 들어오는 요청에 미리 정의된 보안 토큰 값(예: ?secret=abc123)이 포함되어 있지 않으면, 자동화는 즉시 n8n 워크플로우 실행을 중단하고 오류를 반환하여 무단 액세스 및 리소스 소모를 방지합니다. 이 간단한 보안 패턴은 비보안 트리거를 실제 운영 환경에서 사용할 수 있는 강력한 n8n 템플릿으로 전환하는 데 필수적입니다.

이 n8n 워크플로우는 간단한 검증 루프를 기반으로 작동합니다:

1. 트리거 시작: 프로세스는 "Unprotected" 웹훅 n8n 노드에서 시작되며, 고유한 URL로 들어오는 HTTP 요청(일반적으로 GET 또는 POST)을 수신 대기합니다. 이 n8n 트리거는 쿼리 파라미터를 포함한 모든 수신 데이터를 즉시 캡처합니다.


2. 보안 토큰 확인: 플로우는 요청을 Secret valid? n8n 노드로 전달합니다. 이 노드는 쿼리 파라미터 페이로드($json.query.secret)를 평가합니다. 제공된 보안 토큰 값이 미리 결정된 시크릿 토큰(이 템플릿에서는 기본값 123)과 정확히 일치하는지 확인합니다.


3. 성공 경로: 보안 검증이 성공하면(True), n8n 워크플로우는 플레이스홀더 노드인 Do whatever your workflow is supposed to do로 다음 단계들을 진행합니다.


4. 실패 경로: 보안 검증에 실패하면(False), 해당 n8n 노드는 실행을 Validation Failed 노드로 라우팅합니다. 이 Stop and Error n8n 노드는 실행을 즉시 중단하고 호출자에게 오류 응답을 보내 핵심 n8n 워크플로우 로직이 무단으로 실행되는 것을 방지합니다.

제공된 n8n 템플릿 JSON을 사용하여 이 보안 패턴을 배포하려면 다음 단계를 따르십시오:

1. n8n 워크플로우 가져오기: 제공된 JSON을 복사하여 워크플로우 탭(새로 만들기 > JSON에서 가져오기)을 통해 n8n 인스턴스로 직접 가져옵니다.


2. 웹훅 활성화: "Unprotected" 웹훅 n8n 노드를 찾습니다. 워크플로우를 저장하고 활성화하여 고유한 웹훅 URL을 생성합니다.


3. 보안 토큰 설정: Secret valid? If n8n 노드를 엽니다. 중요하게도, 기본값인 Right Value인 123을 해당 n8n 워크플로우 전용의 길고 복잡한 임의의 보안 키로 변경해야 합니다. 이 시크릿은 모든 성공적인 호출에 필요한 토큰입니다.


4. 호출자 업데이트: 외부 서비스(예: Google 시트 버튼, 외부 애플리케이션)를 구성하여 생성된 웹훅 URL을 호출하되, 항상 쿼리 파라미터를 추가해야 합니다: ...\/webhookid?secret=YOURNEWCOMPLEXSECRET.


5. 최종 테스트: 테스트 호출을 실행하여 시크릿이 존재하고 유효할 때만 n8n 트리거가 올바르게 작동하는지 확인합니다.

"Unprotected" Webhook (n8n 트리거):
기능: 외부 HTTP 요청을 수신 대기하며 n8n 워크플로우의 진입점 역할을 합니다.
주요 설정: 지정된 경로에서 수신 대기하도록 설정합니다. 이 n8n 노드는 쿼리 파라미터를 포함하여 수신되는 모든 요청 세부 정보를 캡처하며, 이는 검증에 필수적입니다.
Secret valid? (If n8n 노드):
기능: 필수 쿼리 파라미터 시크릿의 존재 여부와 정확성에 따라 n8n 워크플로우의 분기를 결정하는 기본 보안 검사를 구현합니다.
주요 설정: 표현식 ={{ $json.query.secret }}을 정의된 정적 시크릿 값(템플릿에서는 예시로 123; 사용자가 업데이트해야 함)과 비교하여 확인합니다.
Validation Failed (Stop and Error n8n 노드):
기능: 보안 검사에 실패했을 때 실행됩니다. n8n 워크플로우를 중단시키고 호출 서비스로 설명이 포함된 오류 메시지를 반환하여 다운스트림 노드의 무단 실행을 방지합니다.
주요 설정: errorMessage는 실패한 워크플로우를 식별하기 위해 =The Webhook Secret was invalid in {{ $workflow.name }}과 같이 표현식을 사용하여 동적으로 설정됩니다.
Do whatever your workflow is supposed to do (No-Op n8n 노드):
* 기능: 검증이 완료된 후 보안이 적용된 n8n 워크플로우의 핵심 비즈니스 로직이 연결되어야 할 위치를 나타내는 플레이스홀더 노드입니다.