JWE 토큰 복호화를 사용하면 ID 공급자가 OAuth 2.0 액세스 토큰과 ID 토큰을 JWE로 암호화하여 반환할 수 있습니다. 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 지원팀에 문의하여 요청하세요.
• main과 워커를 포함한 모든 n8n 인스턴스가 동일한 N8N_ENCRYPTION_KEY 값을 공유해야 합니다. n8n은 이 인스턴스 키를 사용하여 저장된 JWE 개인 키를 암호화합니다.
• RSA-OAEP-256 키 암호화 알고리즘을 사용하여 JWE로 암호화된 토큰을 지원하는 IdP.

JWE 토큰 복호화 활성화하기#

1. main과 워커를 포함한 모든 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
   

ID 공급자 구성하기#

IdP의 OAuth 2.0 클라이언트 또는 애플리케이션 구성에서 다음을 수행합니다.

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

Example: Okta

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

n8n에서 자격 증명 구성하기#

1. OAuth 2.0 API 자격 증명을 생성하거나 편집합니다.
2. Encrypted Tokens (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을 지원합니다. 토큰을 암호화할 때 IdP가 이 alg 값을 사용하도록 구성하세요. n8n은 콘텐츠 암호화 알고리즘(enc)을 제한하지 않으므로, IdP가 지원하는 어떤 값이든 사용할 수 있습니다.

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

문제 해결#

• 자격 증명에 Encrypted Tokens (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를 가져올 수 없습니다. JWKS 엔드포인트가 IdP에서 접근 가능한지 확인하세요. 리버스 프록시와 인증 미들웨어가 /rest/.well-known/jwks.json을 차단하는 경우가 있습니다. 이 엔드포인트는 인증 없이 공개적으로 접근 가능해야 합니다.
• IdP가 JWKS를 너무 자주 가져와서 속도 제한에 걸립니다. n8n 인스턴스에서 N8N_OAUTH_JWE_JWKS_PER_MINUTE를 늘리거나, IdP가 전체 max-age 기간 동안 JWKS 응답을 캐시하도록 구성하세요.

관련 자료#

• HTTP Request credentials: Using OAuth2: 범용 OAuth 2.0 자격 증명을 설정합니다.
• Deployment environment variables: N8N_ENV_FEAT_OAUTH2_JWE 및 N8N_OAUTH_JWE_JWKS_PER_MINUTE에 대한 참조입니다.
• Encryption key rotation: JWE 개인 키를 저장 상태에서 보호하는 데이터 암호화 키를 교체합니다.
• JSON Web Encryption (RFC 7516): JWE 사양입니다.