احراز هویت با SSO در راکت‌چت

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

پیش‌نیازها

• یک سرویس فعال RocketChat و دسترسی ادمین
• یک سرویس فعال Keycloak

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

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

---

گام اول: ساخت Client در Keycloak

Client مربوط به RocketChat باید در یک Realm اختصاصی ساخته شود، نه در Realm پیش‌فرض master. Realm master مخصوص مدیریت خود Keycloak (کنسول ادمین) است و استفاده از آن برای اپلیکیشن‌های دیگر توسط خود Keycloak هم توصیه نمی‌شود. در صورت نیاز، یک Realm جدید از مسیر Manage realms > Create realm ساخته و پیش از ادامه این راهنما انتخاب می‌شود.

1. از مسیر Clients > Create client، یک Client جدید ساخته می‌شود؛ برای مثال با Client ID rocketchat.
2. Client authentication روی حالت فعال (Confidential) قرار می‌گیرد و Standard flow فعال باقی می‌ماند.
3. در Valid redirect URIs، آدرس زیر اضافه می‌شود:

https://your-rocketchat-domain.xyz/_oauth/keycloak

4. پس از Save، از تب Credentials، مقدار Client secret کپی می‌شود.

---

گام دوم: ساخت نقش‌ها و تخصیص به کاربران

نقش‌های RocketChat (مثلاً admin) در Keycloak به‌صورت Client Roles روی همین Client ساخته می‌شوند؛ مشابه روشی که برای Grafana استفاده شد:

1. از تب Roles همین Client، با دکمه Create role، نقشی با همان نام دقیق نقش موردنظر در RocketChat ساخته می‌شود؛ برای مثال admin.

طبق مستند رسمی RocketChat برای Keycloak، نام این Role باید دقیقاً (با حروف بزرگ و کوچک یکسان) با نام یک نقش موجود در RocketChat یکی باشد تا همگام‌سازی نقش انجام شود.

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

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

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

   فیلد	مقدار
   Name	یک نام دلخواه، مثلاً rocketchat-roles
   Client ID	همین Client (rocketchat)
   Token Claim Name	یک نام دلخواه، مثلاً roles
   Multivalued	روشن
   Add to ID token / Add to access token / Add to userinfo	روشن

برخلاف Grafana که از Mapper آماده client roles (با claim تودرتوی resource_access.<client-id>.roles) استفاده شد، اینجا طبق مستند رسمی RocketChat یک Mapper دستی با claim مسطح (بدون تودرتو بودن) ساخته می‌شود؛ چون RocketChat مقدار Roles/Groups field name (گام بعد) را به همین شکل ساده می‌خواند.

---

گام سوم: افزودن Custom OAuth در RocketChat

1. از مسیر Administration > Settings > OAuth، روی Add custom OAuth کلیک شده و یک نام (مثلاً keycloak) وارد می‌شود.
2. Enable فعال می‌شود و مقادیر زیر بر اساس آدرس Keycloak و realm مربوطه تکمیل می‌شوند:

فیلد	مقدار
URL	https://your-keycloak-domain/realms/<realm-name>/protocol
Token Path	/openid-connect/token
Token Sent Via	Header
Identity Path	/openid-connect/userinfo
Authorize Path	/openid-connect/auth
Scope	openid
Id	همان Client ID ساخته‌شده در Keycloak (مثلاً rocketchat)
Secret	Client Secret کپی‌شده از Keycloak

توضیح کامل هرکدام از این فیلدها در مستند رسمی «Custom OAuth Setup» آمده است.

مقادیر Token Path و Authorize Path در RocketChat به‌صورت پیش‌فرض با مقادیر عمومی /oauth/token و /oauth/authorize پر شده‌اند؛ این مقادیر مخصوص Keycloak نیستند و باید با مقادیر جدول بالا (/openid-connect/token و /openid-connect/auth) جایگزین شوند، در غیر این صورت اتصال برقرار نمی‌شود.

3. برای همگام‌سازی نقش‌ها، طبق مستند رسمی RocketChat، سه فیلد زیر هم در همین صفحه تکمیل می‌شوند:

فیلد	مقدار
Roles/Groups field name	همان مقدار Token Claim Name از گام قبل، مثلاً roles
Merge Roles from SSO	روشن
Roles to Sync	نام نقش‌هایی که باید همگام شوند، مثلاً admin

4. برای نگاشت اطلاعات پروفایل کاربر، فیلدهای زیر تکمیل می‌شوند:

   فیلد	مقدار
   Key Field	Username
   Username field	preferred_username
   Email field	email
   Name field	name
   Avatar field	خالی می‌ماند

فیلد Avatar field خالی می‌ماند، چون Keycloak به‌صورت پیش‌فرض claimای برای آواتار کاربر برنمی‌گرداند؛ افزودن این قابلیت نیازمند یک Mapper سفارشی برای claim مربوطه (picture) در Keycloak است که در این راهنما پوشش داده نمی‌شود.

5. سایر گزینه‌های همین صفحه:

   فیلد	مقدار
   Merge users	روشن
   Merge users from distinct services	خاموش
   Map Roles/Groups to channels	خاموش
   Show Button on Login Page	روشن

با روشن بودن Merge users، اگر کاربری از قبل با همان Username به‌صورت محلی در RocketChat ثبت‌نام کرده باشد، به‌جای ساخت حساب تکراری، همان حساب به ورود با SSO متصل می‌شود.

دو فیلد Roles/Groups field for channel mapping و User Data Group Map فقط زمانی کاربرد دارند که Map Roles/Groups to channels فعال باشد؛ این قابلیت (عضویت خودکار در کانال بر اساس گروه) در این راهنما پوشش داده نمی‌شود و می‌توان مقدار پیش‌فرض آن‌ها را دست‌نخورده گذاشت.

6. با Save changes تنظیمات ذخیره و با Refresh OAuth Services provider فعال می‌شود.

---

گام چهارم: ورود با SSO

پس از این مرحله، دکمه ورود با Keycloak در صفحه لاگین RocketChat نمایش داده می‌شود.

اگر پس از ورود موفق با Keycloak، پیام «Enter authentication code» در RocketChat نمایش داده شود، این پیام مربوط به Keycloak نیست؛ لایه Two Factor Authentication خود RocketChat است که مستقل از SSO عمل می‌کند و حتی پس از ورود موفق با Keycloak هم می‌تواند فعال بماند. برای غیرفعال کردن آن، در صورتی که نیازی به این قابلیت نیست، از مسیر زیر گزینه Enable Two Factor Authentication خاموش می‌شود:

Administration > Settings > Accounts > Two Factor Authentication