OIDC 설정 및 활성화#

1. n8n에서 Settings > SSO로 이동합니다.

2. Select Authentication Protocol 아래 드롭다운에서 OIDC를 선택합니다.

3. 표시된 redirect URL을 복사합니다(예: https://yourworkspace.app.n8n.cloud/rest/sso/oidc/callback).
   

   로드 밸런서 또는 프록시를 위한 추가 구성

   로드 밸런서 뒤에서 n8n을 실행하는 경우 N8N_EDITOR_BASE_URL 환경 변수를 반드시 설정하세요.

4. ID 공급자(IdP)에서 OIDC를 설정합니다. 다음 작업이 필요합니다:

   • IdP에서 새 OIDC 클라이언트/애플리케이션을 생성합니다.
   • 이전 단계에서 확인한 redirect URL을 구성합니다.
   • IdP에서 제공하는 Client ID와 Client Secret을 기록해 둡니다.

5. IdP에서 Discovery Endpoint(well-known 구성 엔드포인트라고도 함)를 찾습니다. 일반적으로 다음과 같은 형식입니다:

   https://your-idp-domain/.well-known/openid-configuration
   

6. n8n에서 OIDC 구성을 완료합니다:

   • Discovery Endpoint: IdP에서 확인한 discovery endpoint URL을 입력합니다.
   • Client ID: IdP에 애플리케이션을 등록할 때 받은 client ID를 입력합니다.
   • Client Secret: IdP에 애플리케이션을 등록할 때 받은 client secret을 입력합니다.

7. Save settings를 선택합니다.

8. OIDC를 Activated로 설정합니다.

인스턴스 및 프로젝트 접근 권한 프로비저닝#

n8n은 SSO를 통해 인스턴스 역할과 프로젝트 역할을 프로비저닝하는 것을 지원합니다. 사용자가 OIDC를 통해 로그인하면, n8n은 IdP 응답의 클레임(claim)을 기반으로 해당 사용자의 인스턴스 역할과 프로젝트 접근 권한을 자동으로 할당할 수 있습니다.

역할 프로비저닝 기능은 버전 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이 IdP 응답에서 n8n 전용 클레임(n8n_instance_role 및 n8n_projects)을 직접 읽어옵니다. IdP 관리자가 각 사용자 또는 그룹이 받을 n8n 역할이나 프로젝트를 구성합니다.
• Map rules inside n8n: n8n에서 표현식을 정의하여 사용자의 OIDC 클레임을 평가하고 역할을 반환합니다. IdP가 n8n 전용 역할 로직을 인코딩할 수 없거나, IT 거버넌스로 인해 IdP 측 변경이 느릴 때 이 옵션을 사용합니다.

IdP에서 규칙 매핑#

OIDC 인증 서버에 n8n이라는 추가 스코프를 추가하고 다음 두 클레임을 포함합니다:

두 클레임은 항상 인증 서버의 ID 토큰에 포함되어야 합니다. n8n에 접근 권한이 있는 IdP의 사용자 그룹에 이를 구성하세요.

n8n_instance_role 클레임 구성

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

지원되는 인스턴스 역할:

• 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 내부에서 그룹-역할 매핑을 정의할 수 있습니다. 각 규칙은 IdP 응답의 OIDC 클레임에 대해 n8n이 평가하는 표현식입니다.

표현식의 작동 방식

• 표현식은 $claims 객체를 통해 IdP 응답의 모든 OIDC 클레임에 접근합니다.
• 표현식이 true를 반환하면, n8n은 해당 규칙에서 선택한 역할을 할당합니다.
• 규칙은 위에서 아래로 평가됩니다. 처음 일치하는 규칙이 적용됩니다.
• 규칙은 로그인할 때마다 다시 평가되므로, 역할 변경 사항은 사용자의 다음 세션에서 적용됩니다.
• $claims는 IdP의 원본 응답을 그대로 노출합니다. n8n이 이를 정규화하지 않으므로, IdP가 실제로 전송하는 구조에 맞춰 표현식을 작성해야 합니다.

userinfo 응답 예시

인증 후 n8n은 IdP의 userinfo 엔드포인트를 호출하여 사용자의 클레임을 가져옵니다. 일반적인 응답은 다음과 같습니다:

{
  "sub": "00uwyqw9raWrKRJ0Q697",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "email_verified": true,
  "given_name": "Jane",
  "family_name": "Doe",
  "groups": [
    "Everyone",
    "n8n admins",
    "n8n members",
    "Operations"
  ]
}

$claims는 이 페이로드를 반영합니다. 따라서 $claims.email은 문자열이고, $claims.groups는 문자열 배열이며, 둘 다에 표준 JavaScript 메서드를 사용할 수 있습니다. 정확한 그룹 이름은 사용 중인 IdP에 따라 다릅니다. 일부 공급업체(예: Azure AD)는 표시 이름 대신 그룹 UUID를 전송하므로, 이 경우 표현식에서 UUID를 참조해야 합니다.

Okta에서 자신의 userinfo 응답을 확인하려면, 유효한 액세스 토큰으로 userinfo 엔드포인트를 직접 호출하세요. Security > API > Authorization Servers > 해당 서버 > Token Preview 탭에서 테스트용 액세스 토큰을 받은 다음 다음을 실행합니다:

curl -H "Authorization: Bearer <access-token>" https://<your-okta-domain>/oauth2/<auth-server-id>/v1/userinfo

인스턴스 역할 규칙

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 필드에서 대상 프로젝트를 선택합니다. 어떤 프로젝트 규칙에도 일치하지 않는 사용자는 프로젝트 접근 권한을 받지 못합니다.

공급업체별 OIDC 설정#

Okta#

Okta에서 OIDC를 설정하는 단계는 아래에 설명된 Auth0와 유사합니다.

Okta의 경우, 시각적 단계별 가이드를 PDF로 다운로드할 수 있습니다:

Okta로 OIDC를 설정하기 위한 시각적 단계별 가이드

Auth0#

1. Auth0에서 애플리케이션 생성:
   • Auth0 대시보드에 로그인합니다.
   • Applications > Applications로 이동합니다.
   • Create Application을 클릭합니다.
   • 이름을 입력하고(예: "n8n SSO") Regular Web Applications를 선택합니다.
   • Create를 클릭합니다.
2. 애플리케이션 구성:
   • 새 애플리케이션의 Settings 탭으로 이동합니다.
   • Allowed Callback URLs: Settings > SSO > OIDC에서 확인한 n8n redirect URL을 추가합니다.
   • Allowed Web Origins: n8n 기본 URL을 추가합니다(예: https://yourworkspace.app.n8n.cloud).
   • Save Changes를 클릭합니다.
3. 자격 증명 확인:
   • Client ID: Settings 탭에서 확인할 수 있습니다.
   • Client Secret: Settings 탭에서 확인할 수 있습니다.
   • Discovery Endpoint: https://{your-auth0-domain}.auth0.com/.well-known/openid-configuration.
4. n8n에서 OIDC 구성을 완료합니다:
   • Discovery Endpoint: Auth0에서 확인한 discovery endpoint URL을 입력합니다.
   • Client ID: Auth0 설정에서 확인한 client ID를 입력합니다.
   • Client Secret: Auth0 설정에서 확인한 client secret을 입력합니다.
5. Save settings를 선택합니다.
6. OIDC를 Activated로 설정합니다.

Discovery endpoint 참고 자료#

• Google discovery endpoint 예시:

https://accounts.google.com/.well-known/openid-configuration

• Microsoft Azure AD discovery endpoint 예시:

https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

• Auth0 discovery endpoint 예시:

https://{your-domain}.auth0.com/.well-known/openid-configuration

• Okta discovery endpoint 예시:

https://{your-domain}.okta.com/.well-known/openid-configuration

• Amazon Cognito discovery endpoint 예시:

https://cognito-idp.{region}.amazonaws.com/{user-pool-id}/.well-known/openid-configuration