임베딩 파트너를 위한 토큰 교환

OAuth 2.0 토큰 교환을 사용하여 임베드된 n8n 인스턴스 내에서 iframe SSO 및 위임된 API 접근을 통해 사용자를 인증하고 대리 작업을 수행하는 방법을 설명합니다.

기능 제공 범위 Enterprise 플랜에서 사용 가능합니다. N8N_ENV_FEAT_TOKEN_EXCHANGE 환경 변수를 true 로 설정하면 활성화됩니다. 셀프 호스팅 인스턴스는 직접 설정할 수 있습니다. Cloud 환경에서는 n8n 지원팀에 요청하세요. 서명된 JWT를 발급하는 외부 IdP(ID 공급자) 또는 백엔드를 운영하는 임베딩 파트너를 위해 설계되었습니다. 프리뷰 기능 토큰 교환은 환경 플래그 뒤에 있는 프리뷰 기능입니다. 환경 변수, 엔드포인트 경로, JWT 클레임 계약은 기능이 GA(General Availability)에 도달하기 전에 변경될 수 있습니다. n8n 버전을 고정하고 업그레이드 후 연동을 재테스트하세요. OAuth 2.0 토큰 교환( RFC 8693 {:target="_blank" .external-link})을 사용하면 임베딩 파트너가 임베드된 n8n 인스턴스 내에서 사용자를 인증하고 대리로 작업을 수행할 수 있습니다. 토큰 교환은 두 가지 사용 사례를 지원합니다: Iframe SSO : 외부 JWT를 n8n 세션 쿠키로 교환하여 iframe에 n8n을 임베드할 때 사용자가 원활하게 로그인할 수 있도록 합니다. 위임된 API 접근 : 외부 JWT를 n8n 액세스 토큰으로 교환하여 사용자를 대신해 n8n API를 호출합니다. 예를 들어 워크플로를 트리거하거나 자격 증명을 관리할 수 있습니다. 두 흐름은 동일한 방식으로 시작됩니다. 백엔드에서 개인 키로 서명된 단기 JWT를 발급합니다. n8n은 등록된 공개 키를 사용하여 이를 검증하고, 사용자를 확인한 다음 세션 쿠키 또는 액세스 토큰을 반환합니다. 시작하기 전에 # 다음이 필요합니다: 토큰 교환 기능이 활성화된 Enterprise 라이선스. 인스턴스에 프리뷰 기능 플래그 설정: N8N_ENV_FEAT_TOKEN_EXCHANGE=true . RSA 또는 EC 키 쌍, 또는 IdP가 이미 게시한 JWKS 엔드포인트. 키 쌍 생성 을 참고하세요. HTTPS로 제공되는 n8n 인스턴스. 브라우저는 일반 HTTP에서 SameSite=None; Secure 세션 쿠키를 거부하므로 iframe SSO 흐름이 자동으로 실패합니다. TLS 종료 프록시 뒤에서 n8n을 실행하는 경우, 프록시가 X-Forwarded-Proto 헤더를 설정하는지 확인하세요. 키 쌍 생성 # 비대칭 키 쌍이 필요합니다. 백엔드에서 개인 키 로 JWT에 서명하고, n8n은 공개 키 로 이를 검증합니다. RSA (RS256) EC (ES256) # Generate a 2048-bit RSA private key openssl genrsa -out private.pem 2048 # Extract the public key openssl rsa - in private.pem -pubout -out public.pem # Generate an EC private key using P-256 openssl ecparam -name prime256v1 -genkey -noout -out private.pe