احراز هویت با SAML در n8n

با اتصال n8n به Keycloak از طریق SAML ورود به n8n با همان حساب Keycloak (SSO) انجام می‌شود.

پیش‌نیازها

• یک سرویس فعال n8n با قابلیت Enterprise مربوط به SAML و دسترسی owner
• یک سرویس فعال Keycloak و دسترسی مدیریت Clientها در Realm موردنظر
• یک دامنه HTTPS پایدار برای n8n
• یک کاربر آزمایشی در Keycloak با ایمیل، نام و نام خانوادگی
• حفظ نشست owner تا پایان آزمون SSO برای جلوگیری از قفل‌شدن دسترسی مدیریتی

این راهنما یکی از روش‌های ممکن برای فعال‌سازی SAML در n8n را شرح می‌دهد و روش‌های جایگزین را پوشش نمی‌دهد.

این راهنما صرفاً برای راه‌اندازی SAML و ادغام n8n با Keycloak نوشته شده است. همه الزامات استفاده در محیط Production در آن پوشش داده نشده و پیش از به‌کارگیری عملیاتی باید متناسب با نیاز سازمان تکمیل و بررسی شود.

---

گام اول: دریافت اطلاعات از n8n

1. با کاربر owner وارد n8n می‌شود.
2. از مسیر Settings > SSO، مقادیر Redirect URL و Entity ID URL یادداشت می‌شوند؛ این دو مقدار در تنظیم Keycloak استفاده می‌شوند.

---

گام دوم: ساخت Client از نوع SAML در Keycloak

1. از مسیر Clients > Create client، یک Client جدید با پروتکل SAML ساخته می‌شود.
2. مقدار Client ID برابر با همان Entity ID که از n8n کپی شده وارد می‌شود.

مقدار Entity ID در n8n معمولاً یک URL کامل است، نه یک رشته ساده؛ طبق مستند رسمی کی‌کلاک، فیلد Client ID برای Clientهای SAML دقیقاً برای همین حالت طراحی شده و معمولاً یک URL می‌گیرد، پس همان مقدار کامل (با https:// و مسیر کامل) بدون تغییر در این فیلد قرار داده می‌شود.

3. آدرس Redirect URL کپی‌شده از n8n، در فیلد Valid redirect URIs (یا Master SAML Processing URL) قرار می‌گیرد.

فیلدهای Master SAML Processing URL، IDP-Initiated SSO URL name و IDP Initiated SSO Relay State برای این فلو خالی می‌مانند. طبق مستند رسمی کی‌کلاک، Master SAML Processing URL فقط زمانی استفاده می‌شود که درخواست SAML ورودی، آدرس ACS خودش را مشخص نکرده باشد؛ چون n8n این آدرس را در همان Valid redirect URIs مشخص کرده، نیازی به تکرار آن در این فیلد نیست. دو فیلد دیگر هم فقط برای IdP-Initiated SSO (شروع ورود از داخل Keycloak، نه از دکمه SSO در n8n) کاربرد دارند و خالی ماندن آن‌ها روی فلوی معرفی‌شده در این راهنما تأثیری ندارد.

4. پس از Save، از بخش Realm settings > Endpoints، لینک SAML 2.0 Identity Provider Metadata در دسترس است؛ همچنین این متادیتا مستقیماً از آدرس زیر هم قابل دریافت است:

https://your-keycloak-domain/realms/<realm-name>/protocol/saml/descriptor

جزئیات کامل هر فیلد این صفحه، در بخش «Creating a SAML client» از مستند رسمی کی‌کلاک آمده است.

5. برای اینکه n8n بتواند ایمیل، نام، نام‌خانوادگی و نام‌کاربری را از پاسخ SAML استخراج کند، باید چهار Mapper از نوع User Property به این Client اضافه شوند. از تب Client scopes، روی Scope اختصاصی همین Client کلیک می‌شود؛ از تب Mappers همان Scope، به‌ازای هر ردیف جدول زیر، روی Configure a new mapper و سپس User Property کلیک می‌شود. فیلد SAML Attribute NameFormat برای هر چهار Mapper روی URI Reference تنظیم می‌شود:

Property	Claim مربوطه در n8n	SAML Attribute Name
email	ایمیل	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
firstName	نام	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/firstname
lastName	نام‌خانوادگی	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/lastname
username	UPN	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

6. برای تعیین خودکار نقش کاربر (Admin یا Member) در n8n، مشابه روش Client Roles استفاده‌شده برای Grafana، این مراحل روی همین Client انجام می‌شود:

   1. از تب Roles همین Client، با دکمه Create role، دو Client Role با این نام‌های دقیق ساخته می‌شوند:

      global:admin
      global:member

   2. هر کاربر فقط به یکی از این دو Role اضافه می‌شود: از Users، کاربر موردنظر انتخاب و از تب Role mapping، روی Assign role کلیک می‌شود؛ در پنجره بازشده، با فعال کردن Filter by clients، نقش‌های همین Client قابل انتخاب‌اند.

   3. از تب Client scopes همین Client، روی Scope اختصاصی کلیک می‌شود؛ از تب Mappers، روی Configure a new mapper و سپس Role list کلیک می‌شود.

   4. تنظیمات این Mapper:

      فیلد	مقدار
      Name	یک نام دلخواه، مثلاً n8n-instance-role
      Role attribute name	n8n_instance_role (این فیلد همان نام attribute در پاسخ SAML است)
      Friendly Name	خالی می‌ماند
      SAML Attribute NameFormat	Basic (مقدار پیش‌فرض؛ نیازی به تغییر نیست)
      Single Role Attribute	روشن

طبق هشدار امنیتی رسمی n8n، Role یا Groupای با نام global:owner ساخته نشود؛ این مقدار می‌تواند به ارتقای غیرمجاز دسترسی کاربر SSO تا سطح مالک (Owner) کل instance منجر شود. همچنین طبق مستند رسمی n8n، این قابلیت فقط زمانی فعال است که متغیر محیطی N8N_SSO_USER_ROLE_PROVISIONING روی سرویس n8n برابر instance_role تنظیم شده باشد (مقدار پیش‌فرض آن disabled است). اگر از این Mapper صرف‌نظر شود، تعیین نقش Admin باید به‌صورت دستی در گام بعد انجام شود.

پس از تکمیل این گام، فهرست Mapperهای این Client باید شامل پنج مورد زیر باشد: چهار Mapper از نوع User Property (برای email، firstname، lastname و upn) و یک Mapper از نوع Role list (برای n8n_instance_role):

---

گام سوم: تکمیل تنظیمات SSO در n8n

1. در همان صفحه Settings > SSO گام اول، بخش Identity Provider Settings روی حالت URL قرار می‌گیرد و همان آدرس متادیتای Keycloak که در گام قبل از بخش Realm settings > Endpoints به‌دست آمد، در همین فیلد وارد می‌شود؛ معادل این آدرس:

https://your-keycloak-domain/realms/<realm-name>/protocol/saml/descriptor

در حالت XML، به‌جای این آدرس، محتوای همان متادیتا مستقیماً paste می‌شود. 2. با دکمه Save settings، تنظیمات ذخیره می‌شود. 3. با دکمه Test settings، صحت اتصال بررسی می‌شود؛ در همین مرحله، حساب SSO مربوط به شما هم در n8n ساخته می‌شود. تست موفق، claimهای دریافتی از Keycloak (ایمیل، نام، نام‌خانوادگی، UPN) را هم نمایش می‌دهد:

این مرحله ممکن است با خطای ERR_METADATA_CONFLICT_REQUEST_SIGNED_FLAG مواجه شود: Keycloak انتظار AuthnRequest امضاشده دارد (WantAuthnRequestsSigned="true")، اما n8n اصلاً امکان امضای AuthnRequest را ندارد (AuthnRequestsSigned="false") — این یک محدودیت شناخته‌شده در n8n است، نه یک تنظیم قابل‌فعال‌سازی؛ n8n در حال حاضر هیچ گزینه‌ای برای پیکربندی کلید امضا در سمت خودش ندارد. به همین دلیل نمی‌توان امضا را روی هر دو طرف فعال کرد؛ تنها راه، پایین آوردن انتظار Keycloak است. همچنین چون این تناقض از متادیتای عمومی سطح Realm می‌آید، نه از تنظیمات این Client، خاموش کردن Client Signature Required (تب Keys) آن را رفع نمی‌کند.

راه‌حل: در n8n، Identity Provider Settings به حالت XML تغییر داده می‌شود؛ محتوای متادیتا از آدرس زیر گرفته می‌شود:

https://your-keycloak-domain/realms/<realm-name>/protocol/saml/descriptor

مقدار WantAuthnRequestsSigned="true" در همان متن به WantAuthnRequestsSigned="false" تغییر داده می‌شود و XML ویرایش‌شده در n8n paste می‌شود.

Trade-off: این تغییر فقط تأیید امضای AuthnRequest ارسالی از n8n به Keycloak را غیرفعال می‌کند؛ جهت مهم‌تر امنیتی (امضای پاسخ SAML از Keycloak به n8n) دست‌نخورده باقی می‌ماند و همچنان توسط n8n بررسی می‌شود. از طرفی چون n8n هرگز امکان امضای درخواست را نداشته، این تغییر عملاً حفاظتی را که از قبل برقرار نبوده حذف نمی‌کند؛ فقط انتظار Keycloak را با واقعیت هماهنگ می‌کند.

4. نحوه تخصیص نقش کاربران تعیین می‌شود؛ در همین صفحه، دو گزینه وجود دارد:

   • Role assignment: برای استفاده از Mapper نقشی که در گام قبل ساخته شد، این مقدار روی Instance roles via SSO تنظیم می‌شود؛ اگر ترجیح داده شود نقش هرکاربر به‌صورت دستی مدیریت شود (بدون آن Mapper)، این مقدار روی Assigned manually in n8n باقی می‌ماند و نقش هرکاربر باید بعد از اولین ورودش، از مسیر Settings > Users، به‌صورت دستی به Admin تغییر داده شود.
   • Role mapping method: در صورت انتخاب Instance roles via SSO، این گزینه روی Map rules on your IdP تنظیم می‌شود؛ چون Mapper گام قبل، مقدار n8n_instance_role را مستقیماً به‌صورت global:admin یا global:member می‌فرستد، نیازی به تعریف قانون نگاشت اضافه در خود n8n نیست.

5. در نهایت، گزینه Single sign-on (SSO) روی حالت Enabled قرار می‌گیرد.

پس از این مرحله ورود به n8n از طریق Keycloak برای همه کاربران امکان‌پذیر می‌شود.

---

عیب‌یابی

طبق چک‌لیست رسمی عیب‌یابی SAML در n8n، در صورت ناموفق بودن ورود، این موارد بررسی شوند: