SAML 활성화#

1. n8n에서 Settings > SSO로 이동합니다.
2. n8n의 Redirect URL과 Entity ID를 기록해 둡니다.
   • 선택 사항: IdP에서 가져온 메타데이터로 SAML을 설정할 수 있는 경우, Entity ID URL로 이동하여 XML을 저장합니다.
   • 선택 사항: 로드 밸런서 뒤에서 n8n을 실행 중인 경우 N8N_EDITOR_BASE_URL이 구성되어 있는지 확인합니다.
3. ID 공급자(IdP)로 SAML을 설정합니다. Redirect URL과 Entity ID가 필요합니다. IdP 사용자를 위한 이메일 주소와 이름도 필요할 수 있습니다.
4. IdP에서 설정을 완료한 후, 메타데이터 XML을 n8n에 로드합니다. 메타데이터 URL 또는 원시(raw) XML을 사용할 수 있습니다:
   • 메타데이터 URL: IdP의 메타데이터 URL을 n8n의 Identity Provider Settings 필드에 복사합니다.
   • 원시 XML: IdP에서 메타데이터 XML을 다운로드하고, Identiy Provider Settings를 XML로 전환한 다음, 원시 XML을 Identity Provider Settings에 복사합니다.
5. Save settings를 선택합니다.
6. Test settings를 선택하여 SAML 설정이 올바르게 작동하는지 확인합니다.
7. SAML 2.0을 Activated로 설정합니다.

범용 IdP 설정#

IdP를 구성하는 단계는 선택한 IdP에 따라 다릅니다. 다음은 일반적인 설정 작업입니다:

• IdP에서 n8n용 앱을 생성합니다.
• n8n 속성을 IdP 속성에 매핑합니다:

인스턴스 및 프로젝트 액세스 프로비저닝#

n8n은 SSO를 통한 인스턴스 역할 및 프로젝트 역할 프로비저닝을 지원합니다. 사용자가 SAML을 통해 로그인하면, n8n은 SAML 응답의 속성을 기반으로 해당 사용자의 인스턴스 역할과 프로젝트 액세스를 자동으로 할당할 수 있습니다.

역할 프로비저닝은 1.122.2 버전에서 도입되었습니다.

역할 할당 방식 선택#

n8n에서 Settings > SSO로 이동합니다. Role assignment 드롭다운을 사용하여 SSO로 로그인하는 사용자에게 n8n이 역할을 할당하는 방식을 선택합니다. 기본값은 Assigned manually in n8n입니다.

옵션은 다음과 같습니다:

• Assigned manually in n8n: 관리자가 n8n에서 모든 역할을 직접 할당합니다. IdP로부터의 자동 매핑은 없습니다.
• Instance roles via SSO: n8n이 로그인 시 IdP로부터 사용자의 인스턴스 역할을 읽어옵니다. 프로젝트 액세스는 여전히 n8n에서 수동으로 관리됩니다.
• Instance and project roles via SSO: n8n이 로그인 시 IdP로부터 인스턴스 역할과 프로젝트 액세스를 모두 읽어옵니다.

역할은 로그인할 때마다 다시 평가되므로, IdP에서 변경한 내용은 사용자의 다음 로그인 시 적용됩니다.

역할 매핑 방법 선택#

Role assignment가 Instance roles via SSO 또는 Instance and project roles via SSO로 설정되면, Role mapping method 드롭다운이 나타납니다. 다음 중에서 선택할 수 있습니다:

• Map rules on your IdP: n8n이 SAML 응답에서 n8n 전용 속성(n8n_instance_role 및 n8n_projects)을 직접 읽어옵니다. IdP 관리자가 각 사용자 또는 그룹이 받을 n8n 역할이나 프로젝트를 구성합니다.
• Map rules inside n8n: 사용자의 SAML 속성을 평가하여 역할을 반환하는 표현식을 n8n에서 직접 정의합니다. IdP가 n8n 전용 역할 로직을 인코딩할 수 없거나, IT 거버넌스로 인해 IdP 측 변경이 느린 경우 이 옵션을 사용합니다.

IdP에서 규칙 매핑#

IdP의 그룹 또는 개별 사용자에 다음 속성을 구성합니다:

n8n_instance_role 속성 구성

n8n_instance_role은 IdP에서 그룹 또는 사용자에 대해 구성된 문자열입니다. 값이 설정되지 않은 경우, n8n은 global:member로 대체합니다.

지원되는 인스턴스 역할:

• global:member
• global:admin
• global:chatUser

n8n_projects 속성 구성

n8n_projects는 IdP에서 그룹 또는 사용자에 대해 구성된 문자열 배열입니다. 각 요소는 <project-id>:<role> 형식을 따라야 합니다.

예를 들어:

• bHsykgeFirmIhezz:viewer
• 4K3zrg3DvlMFFTB7:editor
• dCjnYuEpYOUBVaNe:admin

프로젝트 프로비저닝을 활성화하는 시점에 기존 액세스가 있는 경우, 다운로드한 CSV 파일에서 프로젝트 ID를 확인합니다.

새 프로젝트의 경우, 브라우저에서 해당 프로젝트를 볼 때 URL에서 프로젝트 ID를 확인할 수 있습니다. URL <your-domain>/projects/VVRWZaq5DRxaf9O1/workflows에서 프로젝트 ID는 VVRWZaq5DRxaf9O1입니다.

n8n 내부에서 규칙 매핑#

Map rules inside n8n은 2.19.0 버전 이상부터 사용할 수 있습니다.

이 옵션을 사용하면 IdP가 아닌 n8n 내부에서 그룹-역할 매핑을 정의할 수 있습니다. 각 규칙은 n8n이 IdP 응답의 SAML 속성에 대해 평가하는 표현식입니다.

표현식 작동 방식

• 표현식은 $claims 객체를 통해 IdP 응답의 모든 SAML 속성에 접근합니다.
• 표현식이 true를 반환하면, n8n은 해당 규칙에서 선택한 역할을 할당합니다.
• 규칙은 위에서 아래 순서로 평가됩니다. 처음 일치하는 규칙이 적용됩니다.
• 규칙은 로그인할 때마다 다시 평가되므로, 역할 변경은 사용자의 다음 세션에서 적용됩니다.
• $claims는 원시 SAML 속성을 노출합니다. n8n은 이를 정규화하지 않으므로, 사용 중인 IdP가 실제로 전송하는 구조에 맞게 표현식을 작성해야 합니다. SAML 그룹 멤버십은 보통 다중 값 속성으로 전달되지만, 정확한 형태는 IdP에 따라 다릅니다.

인스턴스 역할 규칙

Instance role rules 아래에서 Add rule을 선택하여 규칙을 생성합니다. 조건 표현식을 입력하고, 조건이 true를 반환할 때 할당할 인스턴스 역할을 선택합니다.

예를 들어, IdP의 admin 그룹에 속한 모든 사용자에게 Admin 역할을 할당하려면:

{{ $claims.groups.includes('admin') }}

Default condition 행은 어떤 규칙도 일치하지 않을 때 사용자가 받는 역할을 설정합니다. 기본값은 Member입니다.

프로젝트 역할 규칙

Project role rules 아래에서 Add rule을 선택하여 하나 이상의 프로젝트에 프로젝트 역할을 할당하는 규칙을 생성합니다.

예를 들어, operations 그룹에 속한 사용자에게 Operations 프로젝트에서 Project Editor 역할을 부여하려면, 표현식을 다음과 같이 설정합니다:

{{ $claims.groups.includes('operations') }}

assign 필드에서 역할을 선택하고, in 필드에서 대상 프로젝트를 선택합니다. 어떤 프로젝트 규칙에도 일치하지 않는 사용자는 프로젝트 액세스를 받지 못합니다.

일반적인 IdP를 위한 설정 리소스#

일반적인 IdP에 대한 문서 링크입니다.