OIDC 설정 및 활성화#

1. n8n에서 Settings > SSO로 이동합니다.
2. Select Authentication Protocol 아래에서 드롭다운에서 OIDC를 선택합니다.
3. 표시된 redirect URL을 복사합니다(예: https://yourworkspace.app.n8n.cloud/rest/sso/oidc/callback).

1. 신원 제공자(IdP)에서 OIDC를 설정합니다. 다음이 필요합니다:
   • IdP에서 새 OIDC 클라이언트/애플리케이션을 만듭니다.
   • 이전 단계의 리다이렉트 URL을 설정합니다.
   • IdP에서 제공하는 Client ID와 Client Secret을 기록합니다.
2. IdP에서 Discovery Endpoint(well-known 구성 엔드포인트라고도 함)를 찾습니다. 일반적으로 다음 형식입니다:

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

3. n8n에서 OIDC 구성을 완료합니다:
   • Discovery Endpoint: IdP의 Discovery Endpoint URL을 입력합니다.
   • Client ID: IdP에 애플리케이션을 등록할 때 받은 Client ID를 입력합니다.
   • Client Secret: IdP에 애플리케이션을 등록할 때 받은 Client Secret을 입력합니다.
4. Save settings를 선택합니다.
5. OIDC를 Activated로 설정합니다.

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

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

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

역할 할당 방법 선택#

n8n에서 Settings > SSO로 이동합니다. Role assignment 드롭다운을 사용하여 n8n이 SSO를 통해 로그인하는 사용자에게 역할을 할당하는 방법을 선택합니다. 기본값은 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 Token에 포함되어야 합니다. n8n에 접근할 수 있는 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 내에서 규칙 매핑#

n8n 내에서 규칙 매핑은 버전 2.19.0 이상부터 사용 가능합니다.

IdP 대신 n8n 내에서 그룹-역할 매핑을 정의하려면 이 옵션을 사용합니다. 각 규칙은 n8n이 IdP 응답의 OIDC 클레임에 대해 평가하는 표현식입니다.

표현식 작동 방식

• 표현식은 $claims 객체를 통해 IdP 응답의 모든 OIDC 클레임에 접근합니다.
• 표현식이 true를 반환하면 해당 규칙에서 선택한 역할이 할당됩니다.
• 규칙은 위에서 아래로 평가됩니다. 첫 번째 일치 규칙이 적용됩니다.
• 규칙은 모든 로그인 시 재평가되므로 역할 변경 사항은 사용자의 다음 세션에서 적용됩니다.
• $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로 다운로드할 수 있습니다:

n8n-oidc-with-okta.pdf

Auth0#

1. Auth0에서 애플리케이션 만들기:
   • Auth0 대시보드에 로그인합니다.
   • Applications > Applications로 이동합니다.
   • Create Application을 클릭합니다.
   • 이름(예: "n8n SSO")을 입력하고 Regular Web Applications를 선택합니다.
   • Create를 클릭합니다.
2. 애플리케이션 구성:
   • 새 애플리케이션의 Settings 탭으로 이동합니다.
   • Allowed Callback URLs: Settings > SSO > OIDC의 n8n 리다이렉트 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