JWE 토큰 복호화를 사용하면 IdP(ID 공급자)가 OAuth 2.0 액세스 토큰 및 ID 토큰을 JWE{:target="_blank" .external-link}로 암호화하여 반환할 수 있습니다. n8n 인스턴스는 OAuth 콜백 시 인스턴스에서 외부로 유출되지 않는 개인 키를 사용하여 토큰을 복호화합니다. 이를 통해 리버스 프록시, 브라우저, 로그를 포함하여 IdP와 n8n 사이에 위치한 모든 것으로부터 토큰 내용을 보호합니다.

JWE 토큰 복호화 작동 방식#

이 기능을 활성화하면 n8n이 다음을 수행합니다:

1. 시작 시 RSA 키 쌍을 생성하고, 인스턴스 암호화 키로 암호화된 개인 키를 데이터베이스에 저장합니다.
2. 인스턴스 전체 JWKS 엔드포인트에 매칭되는 공개 키를 게시하여 IdP가 이를 가져올 수 있도록 합니다.
3. JWE 헤더의 kid와 일치하는 개인 키를 사용하여 OAuth 콜백에서 수신된 JWE 토큰을 복호화합니다.

IdP는 JWKS 엔드포인트에서 가져온 공개 키로 각 토큰을 암호화합니다. 복호화는 해당 인스턴스만 수행할 수 있습니다.

시작하기 전에#

다음이 필요합니다:

• n8n 인스턴스에서 N8N_ENV_FEAT_OAUTH2_JWE=true 설정. 셀프 호스팅 인스턴스는 직접 활성화할 수 있습니다. Cloud의 경우 n8n 지원팀에 문의하여 요청하세요.
• 모든 n8n 인스턴스(메인 및 워커)가 동일한 N8N_ENCRYPTION_KEY 값을 공유해야 합니다. n8n은 이 인스턴스 키를 사용하여 저장 시 JWE 개인 키를 암호화합니다.
• RSA-OAEP-256 키 암호화 알고리즘으로 JWE 암호화 토큰을 지원하는 IdP.

JWE 토큰 복호화 활성화#

1. 모든 n8n 인스턴스(메인 및 워커 모두)에 다음 환경 변수를 설정합니다:

   N8N_ENV_FEAT_OAUTH2_JWE=true
   

2. 모든 인스턴스를 재시작합니다. 시작 시 n8n이 RSA 키 쌍을 생성하고 JWKS 엔드포인트에 공개 키를 게시합니다.

3. 기능이 활성화되었는지 확인하려면 JWKS 엔드포인트에 요청하여 "alg": "RSA-OAEP-256"이 포함된 키 하나가 반환되는지 확인합니다:

   curl https://<your-n8n-host>/rest/.well-known/jwks.json
   

IdP 구성#

IdP의 OAuth 2.0 클라이언트 또는 애플리케이션 구성에서:

1. n8n이 연결하는 클라이언트에 대해 암호화 토큰을 활성화합니다.
2. 클라이언트의 JWKS URI를 인스턴스의 JWKS 엔드포인트로 설정합니다. n8n은 자격 증명에서 이 URL을 표시하므로 자격 증명을 생성한 후 해당 위치에서 바로 복사할 수 있습니다(다음 섹션 참조).
3. 키 암호화 알고리즘(alg)으로 RSA-OAEP-256을 선택합니다. IdP가 지원하는 콘텐츠 암호화 알고리즘(enc)과 조합하세요. 예: A128CBC-HS256 또는 A256GCM.

예시: Okta

1. Okta 관리 콘솔에서 n8n이 사용하는 OAuth 2.0 애플리케이션을 열거나 새 웹 애플리케이션을 생성합니다.
2. 애플리케이션의 OpenID Connect 설정에서 토큰 암호화를 활성화합니다.
3. 키 관리 알고리즘을 RSA-OAEP-256으로 설정하고 콘텐츠 암호화 알고리즘을 선택합니다(예: A256GCM).
4. JWKS URI를 자격 증명의 JWKS URI 필드에 n8n이 표시하는 값으로 설정합니다.

n8n에서 자격 증명 구성#

1. OAuth 2.0 API 자격 증명을 생성하거나 편집합니다.
2. 암호화 토큰(JWE) 토글을 켭니다.
3. JWKS URI 필드의 값을 복사하여 아직 하지 않았다면 IdP의 JWKS URI 설정에 붙여넣습니다.
4. 자격 증명을 저장하고 연결합니다. n8n이 IdP에서 반환된 토큰을 복호화하고 워크플로에서 사용하기 위해 복호화된 형태로 저장합니다.

IdP의 응답에는 JWE 암호화 토큰(액세스 토큰, ID 토큰 또는 둘 다)이 하나 이상 포함되어야 합니다. 응답이 완전히 평문인 경우 n8n은 Expected at least one JWE-encrypted token but received only plaintext 오류와 함께 거부합니다.

JWKS 엔드포인트 참조#

n8n은 다음 위치에서 인스턴스의 공개 암호화 키를 노출합니다:

<instance-base-url>/<rest-endpoint>/.well-known/jwks.json

N8N_ENDPOINT_REST를 사용자 정의한 경우 경로에서 rest 대신 해당 값을 사용하세요.

지원 알고리즘#

n8n은 키 암호화에 RSA-OAEP-256을 지원합니다. 토큰 암호화 시 이 alg 값을 사용하도록 IdP를 구성하세요. n8n은 콘텐츠 암호화 알고리즘(enc)을 제한하지 않습니다. IdP가 지원하는 모든 값을 사용할 수 있습니다.

JWKS 스키마는 타원 곡선 알고리즘(ECDH-ES 및 변형)을 예약하고 있지만, n8n은 아직 EC 키를 생성하지 않습니다.

문제 해결#

• 자격 증명에 암호화 토큰(JWE) 토글이 나타나지 않습니다. 모든 n8n 인스턴스에 N8N_ENV_FEAT_OAUTH2_JWE=true를 설정했는지, 모든 인스턴스를 재시작했는지 확인하세요.
• 오류 Expected at least one JWE-encrypted token but received only plaintext. IdP가 평문 토큰을 반환했습니다. IdP에서 클라이언트의 토큰 암호화를 활성화했는지, IdP가 JWKS 엔드포인트에서 키를 가져왔는지 확인하세요.
• IdP가 JWKS URI를 가져올 수 없습니다. IdP에서 JWKS 엔드포인트에 접근 가능한지 확인하세요. 리버스 프록시 및 인증 미들웨어가 /rest/.well-known/jwks.json을 차단하는 경우가 있습니다. 이 엔드포인트는 인증 없이 공개적으로 접근 가능해야 합니다.
• IdP가 JWKS를 너무 자주 가져와 속도 제한에 걸립니다. n8n 인스턴스에서 N8N_OAUTH_JWE_JWKS_PER_MINUTE를 늘리거나, IdP가 전체 max-age 기간 동안 JWKS 응답을 캐시하도록 구성하세요.

관련 리소스#

• HTTP Request 자격 증명: OAuth2 사용: 범용 OAuth 2.0 자격 증명 설정.
• 배포 환경 변수: N8N_ENV_FEAT_OAUTH2_JWE 및 N8N_OAUTH_JWE_JWKS_PER_MINUTE 참조.
• 암호화 키 교체: 저장 시 JWE 개인 키를 보호하는 데이터 암호화 키 교체.
• JSON Web Encryption (RFC 7516){:target="_blank" .external-link}: JWE 사양.