پرش به مطلب اصلی
ادغام Keycloak با LDAP (User Federation)

ادغام Keycloak با LDAP (User Federation)

بازارچه ابریخواندن 10 دقیقه

Keycloak به‌جای این‌که فقط یک بار کاربران را از یک دایرکتوری LDAP وارد (Import) کند، آن دایرکتوری را به‌عنوان یک منبع ذخیره‌سازی کاربر زنده و پیوسته می‌شناسد؛ به این معماری، User Federation گفته می‌شود. در این حالت، خود فرایند احراز هویت (بررسی رمز عبور) هم می‌تواند مستقیماً به LDAP واگذار شود، بدون این‌که رمزها در دیتابیس Keycloak کپی شوند.

پیش‌نیازها​

  • یک سرویس فعال Keycloak و دسترسی مدیریتی به Realm موردنظر
  • یک سرور LDAP یا Active Directory در دسترس از شبکه Keycloak

توضیحات کامل این قابلیت در مستند رسمی User Federation کی‌کلاک آمده است.

گام اول: افزودن Provider​

  1. از منوی سمت چپ، User Federation انتخاب می‌شود.
  2. روی Add provider کلیک شده و گزینه ldap انتخاب می‌شود.

گام دوم: تنظیمات اتصال​

  1. یک نام در فیلد Console Display Name وارد می‌شود.
  2. نوع سرور در فیلد Vendor انتخاب می‌شود (Active Directory یا Other).
  3. آدرس سرور در فیلد Connection URL وارد می‌شود؛ برای مثال ldaps://ldap.example.com:636.
  4. Bind Type روی simple تنظیم می‌شود.
  5. مشخصات حساب سرویس در فیلدهای Bind DN و Bind Credential وارد می‌شود.
فیلدمقدار نمونه
Bind typesimple
Bind DNcn=keycloak-reader,dc=example,dc=org
Bind credentials<LDAP_BIND_PASSWORD>

با دکمه Test Connection، برقراری اتصال شبکه‌ای به سرور و با Test Authentication، صحت همین Bind بررسی می‌شود.

گام سوم: تنظیمات جست‌وجوی کاربر​

  1. مسیر ریشه کاربران در فیلد Users DN وارد می‌شود؛ برای مثال ou=people,dc=example,dc=org.
  2. attribute نام‌کاربری در فیلد Username LDAP attribute مشخص می‌شود (معمولاً uid یا sAMAccountName).
  3. RDN LDAP attribute و UUID LDAP attribute متناسب با ساختار دایرکتوری تنظیم می‌شوند.
  4. کلاس آبجکت کاربران در فیلد User Object Classes و محدوده جست‌وجو در فیلد Search Scope مشخص می‌شود.
فیلدمقدار نمونهتوضیحات
Edit modeREAD_ONLYحالت تعامل Keycloak با LDAP؛ READ_ONLY یعنی هیچ تغییری از Keycloak به دایرکتوری نوشته نمی‌شود
Users DNou=people,dc=example,dc=orgمسیر کامل OU‌ای که کاربران در آن قرار دارند
Relative user creation DN—فقط در حالت WRITABLE و برای ساخت کاربر در یک زیرشاخه Users DN لازم است؛ برای مثال ou=engineering
Username LDAP attributeuidattribute‌ای که به‌عنوان نام کاربری (username) در Keycloak استفاده می‌شود
RDN LDAP attributeuidبخش اول DN هر رکورد؛ مثلاً uid یعنی DN کاربر به شکل uid=alice,ou=people,... است
UUID LDAP attributeentryUUIDشناسه یکتا و تغییرناپذیر هر رکورد که Keycloak برای tracking داخلی استفاده می‌کند؛ مقدار استاندارد OpenLDAP همین است
User object classesinetOrgPerson, posixAccount, shadowAccountKeycloak فقط رکوردهایی را کاربر می‌شناسد که همه این objectClass‌ها را داشته باشند
Search scopeSubtreeUsers DN و همه زیرشاخه‌های آن جست‌وجو می‌شوند؛ اگر همه کاربران مستقیماً زیر Users DN هستند، One Level هم قابل استفاده است

در همین صفحه، دو گزینه تعیین می‌کنند که Keycloak چه رابطه‌ای با داده‌های LDAP داشته باشد:

Import Users مشخص می‌کند که آیا Keycloak پس از اولین ورود موفق یا پیدا شدن کاربر در یک جست‌وجو، یک نسخه محلی (Shadow Copy) از او را در دیتابیس خودش نگه می‌دارد یا نه. منبع هر attribute و نحوه به‌روزرسانی آن به تنظیم Mapper مربوط بستگی دارد؛ برخی attributeها هنگام خواندن از LDAP دریافت می‌شوند و برخی در نسخه محلی نگه‌داری می‌شوند. همگام‌سازی دوره‌ای برای واردکردن و به‌روزرسانی گروهی کاربران استفاده می‌شود.

Edit Mode مشخص می‌کند تغییرات پروفایل یا رمز عبور از داخل Keycloak (چه توسط ادمین، چه توسط خود کاربر) چه سرنوشتی پیدا می‌کنند:

Edit Modeرفتارکاربرد پیشنهادی
READ_ONLYتغییر پروفایل/رمز از Keycloak امکان‌پذیر نیست؛ فقط خواندن از LDAP انجام می‌شودوقتی LDAP تنها منبع حقیقت است و نباید از کنسول Keycloak دست‌کاری شود
WRITABLEتغییرات از Keycloak مستقیماً روی همان رکورد در LDAP نوشته می‌شودوقتی باید بتوان پروفایل یا رمز را از کنسول Keycloak هم به‌روزرسانی کرد
UNSYNCEDتغییرات فقط در دیتابیس Keycloak ذخیره می‌شود و به LDAP نوشته نمی‌شودبرای نگه‌داری تغییرات محلی روی LDAP فقط‌خواندنی یا در دوره مهاجرت

گام چهارم: همگام‌سازی (Synchronization)​

با فعال بودن Import Users، Keycloak یک نسخه محلی از کاربران LDAP در دیتابیس خودش نگه می‌دارد. برای واردکردن اولیه همه کاربران و به‌روزرسانی گروهی رکوردهای محلی، همگام‌سازی به یکی از دو شکل زیر تنظیم می‌شود:

نوع Syncکاربردهزینه
Periodic Full Syncتمام کاربران دایرکتوری را از ابتدا همگام می‌کندبالا؛ بازه طولانی‌تر (مثلاً روزانه) مناسب‌تر است
Periodic Changed Users Syncفقط کاربرانی را همگام می‌کند که از آخرین اجرا تغییر کرده‌اندپایین؛ می‌تواند با بازه کوتاه‌تر اجرا شود
  1. گزینه Import Users فعال می‌شود.
  2. بسته به نیاز، هرکدام از دو نوع Sync بالا فعال و بازه زمانی‌شان تنظیم می‌شود.
  3. با کلیک روی Save، تنظیمات ذخیره می‌شود.
  4. برای اجرای فوری sync، از دکمه Action در بالای همان صفحه، گزینه Synchronize all users انتخاب می‌شود.

جزئیات این بخش در مستند رسمی همگام‌سازی LDAP آمده است.

برای بررسی نتیجه، از منوی سمت چپ به بخش Users مراجعه و نام یکی از کاربران LDAP جست‌وجو می‌شود. در نسخه‌هایی که فهرست اولیه خالی نمایش داده می‌شود، با واردکردن * می‌توان جست‌وجوی صریح همه کاربران را اجرا کرد. در دایرکتوری‌های بزرگ، جست‌وجوی یک نام مشخص به‌جای * از بار غیرضروری روی LDAP جلوگیری می‌کند.

مپینگ گروه‌ها و نقش‌ها​

پس از همگام‌سازی کاربران، گروه‌ها و نقش‌های دایرکتوری از طریق تب Mappers همین Provider به Keycloak نگاشت می‌شوند. جزئیات کامل در مستند رسمی LDAP Mapperها آمده است.

وارد کردن گروه‌ها از LDAP​

مقادیر این بخش با ConfigMap راهنمای ساخت اپ دارکوبی LDAP هماهنگ‌اند. در آن ساختار، کاربران زیر ou=people، گروه‌ها زیر ou=groups و عضویت گروه‌های posixGroup از طریق memberUid نگه‌داری می‌شود.

  1. در صفحه Provider، تب Mappers انتخاب می‌شود.
  2. روی Add Mapper کلیک شده و نوع group-ldap-mapper انتخاب می‌شود.
  3. تنظیمات زیر وارد می‌شود:
فیلدمقدارتوضیحات
Nameldap-groupsنام دلخواه برای این Mapper
LDAP Groups DNou=groups,dc=example,dc=orgمسیر OU‌ای که گروه‌ها در آن قرار دارند
Group Name LDAP Attributecnattribute‌ای که نام گروه از آن خوانده می‌شود
Group Object ClassesposixGroupکلاس آبجکت گروه‌ها در دایرکتوری
Preserve Group InheritanceOffدر ساختار تخت posixGroup و عضویت مبتنی بر UID خاموش می‌ماند
Membership LDAP AttributememberUidattribute‌ای که لیست اعضا در گروه با آن ذخیره شده
Membership Attribute TypeUIDنوع مقدار attribute عضویت؛ UID یعنی مقدار خام uid است، نه DN کامل
Membership User LDAP Attributeuidattribute متناظر در رکورد کاربر که با memberUid مقایسه می‌شود
ModeIMPORTگروه‌ها را در Keycloak می‌سازد و در sync نگه می‌دارد
User Groups Retrieve StrategyLOAD_GROUPS_BY_MEMBER_ATTRIBUTEروش پیدا کردن گروه‌های هر کاربر؛ مناسب برای posixGroup
Member-Of LDAP AttributememberOfمقدار پیش‌فرض؛ در ساختار posixGroup عملاً استفاده نمی‌شود
Drop non-existing groups during syncOffگروه‌هایی که در LDAP نیستند را در Keycloak حذف نمی‌کند
Groups Path/مسیر ریشه برای ساخت گروه‌ها در Keycloak
  1. با کلیک روی Save ذخیره می‌شود.
  2. از دکمه Action در بالای صفحه، گزینه Sync LDAP Groups To Keycloak انتخاب می‌شود تا گروه‌های دایرکتوری (برای مثال developers و admins) فوری وارد Keycloak شوند.

پس از sync، گروه‌ها از منوی Groups در کنسول ادمین قابل مشاهده هستند.

نگاشت گروه‌های LDAP به نقش‌های Keycloak​

پس از sync گروه‌ها، می‌توان به هر گروه یک یا چند Realm Role اختصاص داد. ابتدا اگر نقش‌های موردنیاز هنوز ساخته نشده‌اند، از منوی Realm roles (سمت چپ) ساخته می‌شوند.

سپس برای هر گروه:

  1. از منوی Groups، گروه موردنظر (برای مثال admins) انتخاب می‌شود.
  2. تب Role mapping انتخاب می‌شود.
  3. دکمه Assign role زده شده و از منوی کشویی آن، Realm roles انتخاب می‌شود.
  4. نقش موردنظر از لیست انتخاب و تأیید می‌شود.

برای مدیریت متمرکز دسترسی‌ها، نقش‌ها روی گروه تنظیم می‌شوند تا همه اعضای گروه آن‌ها را به ارث ببرند. نقش‌های مستقیمی که در Keycloak به یک کاربر اختصاص داده می‌شوند محلی هستند و همگام‌سازی معمول LDAP آن‌ها را حذف نمی‌کند؛ بااین‌حال مدیریت گروه‌محور از ایجاد دسترسی‌های پراکنده جلوگیری می‌کند.

از این پس، هر کاربری که عضو آن گروه در LDAP باشد، نقش اختصاص‌داده‌شده را در Keycloak به ارث می‌برد. قرارگرفتن نقش در توکن به تنظیمات Role scope mapping و Mapperهای Client یا Client Scope نیز وابسته است.

قدم بعدی​

پس از federate شدن کاربران از LDAP، برای این‌که یک اپ با همین کاربران SSO انجام دهد، باید Keycloak به‌عنوان provider به آن اپ متصل شود:

راهنمایی‌های مرتبط

KeycloakLDAPبازارچهاپ‌های آماده بازارچه
این راهنمایی کاربردی بود؟

با ثبت بازخوردتان در بهبود کیفیت مستندات مشارکت داشته باشید.