이 문서는 Azure AD가 SAML 속성을 통해 n8n에 역할 정보를 전달하도록 구성하는 방법을 안내합니다. 이를 통해 Azure AD 그룹 멤버십에 따른 자동 역할 할당이 가능합니다.

사전 요구 사항#

Enterprise Applications에 대한 액세스 권한이 있는 Azure AD 계정과 n8n SAML 설정에서 제공하는 리디렉션 URL 및 엔티티 ID가 필요합니다.

먼저 SAML 설정 가이드를 읽어보세요.

n8n 요구 사항#

n8n은 SAML 어설션에 커스텀 SAML 속성이 포함되어 있어야 합니다.

n8n_instance_role의 유효한 값:

설정#

1단계: 표준 SAML 속성 구성

1. Azure AD 포털에서 n8n Enterprise Application으로 이동합니다.

2. Single sign-on > Attributes & Claims로 이동합니다.

3. 다음 표준 속성이 구성되어 있는지 확인합니다.

   클레임 이름	소스 속성
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	user.mail
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/firstname	user.givenname
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/lastname	user.surname
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn	user.userprincipalname

2단계: n8n_instance_role 클레임 추가

이 클레임은 조건부 로직을 사용하여 Azure AD 그룹 멤버십에 따라 서로 다른 역할 값을 내보냅니다.

1. Attributes & Claims에서 Add new claim을 클릭합니다.

2. 기본 설정을 구성합니다.

   • Name: n8n_instance_role
   • Namespace: 비워두기
   • Source: Attribute

3. Claim conditions를 펼치고 Add condition을 클릭합니다.

4. 각 Azure AD 그룹에 대해 조건을 추가합니다(우선순위 순서로):

   사용자 유형	범위 지정 그룹	소스	값
   Members	n8n-chatusers	Attribute	global:chatUser
   Members	n8n-users	Attribute	global:member
   Members	n8n-admins	Attribute	global:admin
   Members	n8n-owners	Attribute	global:owner

5. Save를 클릭합니다.

구성 테스트#

1. n8n에서 Settings > SSO로 이동합니다.
2. Role assignment를 Instance roles via SSO로 설정합니다.
3. Role mapping method를 Map rules on your IdP로 설정합니다.
4. Test settings를 클릭합니다.
5. SAML 응답에 올바른 n8n_instance_role 값이 표시되는지 확인합니다.

문제 해결#

클레임이 SAML 응답에 나타나지 않는 경우

• 해당 사용자가 구성된 그룹 중 하나 이상의 멤버인지 확인합니다.
• 그룹이 Enterprise Application에 할당되어 있는지 확인합니다.
• 조건이 Attribute를 소스로 사용하여 구성되었는지 확인합니다.
• 'SAML Chrome Panel'과 같은 브라우저 확장 플러그인을 사용하여 애플리케이션 SAML 응답을 확인합니다.

사용자에게 잘못된 역할이 할당되는 경우

• 조건 순서를 확인합니다(가장 높은 권한의 그룹이 마지막이어야 합니다).

그룹 기반 클레임 대신 앱 역할을 사용하여 여러 프로젝트 역할 할당#

여러 프로젝트 역할을 사용자에게 할당하기 위해 Azure AD 그룹 기반 클레임 조건을 사용하면 첫 번째로 일치하는 그룹 클레임만 SAML 어설션에 전송되는 경우가 많습니다. 이로 인해 사용자가 여러 그룹에 속해 있음에도 하나의 프로젝트에만 액세스할 수 있게 됩니다.

여러 프로젝트와 해당 역할을 안정적으로 할당하려면 그룹 기반 클레임 대신 App Registration에 정의된 App Roles를 사용하세요.

1. n8n SAML 앱의 App Registration에서 각 프로젝트 및 권한 조합을 나타내는 App Roles를 정의합니다(예: <projectId>:<role>).
2. 업데이트된 App Manifest를 저장합니다.
3. Enterprise Application에서 Users and groups 아래에 있는 App Roles에 사용자 또는 그룹을 할당합니다.
4. Single sign-on > Attributes & Claims에서 n8n_projects SAML 클레임을 user.assignedroles를 소스로 사용하도록 업데이트합니다. 이렇게 하면 할당된 모든 역할이 배열로 SAML 응답에 포함됩니다.

이 설정을 통해 n8n이 모든 프로젝트 할당을 올바르게 수신하여 여러 프로젝트에 걸쳐 적절한 액세스가 가능합니다. App Roles를 정의하면 초기 관리 오버헤드가 늘어나지만, 지속적인 사용자-역할 관리가 간소화되고 완전한 프로젝트 역할 동기화가 보장됩니다.

그룹 기반 클레임에서 App Roles로 마이그레이션할 때는 불완전한 프로젝트 액세스를 방지하기 위해 역할 정의와 클레임 매핑을 적절히 조정하세요.

참고 자료#

• n8n SAML Setup
• n8n Okta Guide (reference)
• Azure AD Claims Customization