راه‌اندازی SAML 2.0 در سنتری با Keycloak

این راهنما مسیر گام‌به‌گام راه‌اندازی SSO سنتری با Keycloak است.

پیش‌نیازها

• یک Keycloak Realm و دسترسی مدیریتی به آن.
• یک حساب Owner در سازمان سنتری.
• slug سازمان سنتری شما؛ این مقدار در URL سازمان شما قرار دارد (https://sentry.hamravesh.com/organizations/<slug>/). در ادامه از آن با نام ORG استفاده شده است.
• آدرس Keycloak شما که در ادامه با نام KEYCLOAK_HOST و نام Realm که با نام REALM نوشته شده است.

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

۱. ساخت Client در Keycloak

1. Realm خود را در Keycloak باز کنید و به Clients > Create client بروید.
2. Client type: SAML
3. Client ID: https://sentry.hamravesh.com/saml/metadata/ORG/
4. Name: sentry
5. روی Next کلیک کنید.
6. Valid redirect URIs: https://sentry.hamravesh.com/*
7. روی Save کلیک کنید.

۲. پیکربندی تنظیمات Client

در تب Settings مربوط به Client، زیر بخش SAML capabilities:

1. مقدار Name ID format را روی email بگذارید.
2. مطمئن شوید Force POST binding فعال است.
3. روی Save کلیک کنید.

۳. غیرفعال‌کردن امضای Client

تب Keys را باز کنید و گزینه Client signature required را خاموش کنید. سنتری درخواست‌های خود را امضا نمی‌کند، بنابراین Keycloak آن‌ها را رد می‌کند.

۴. حذف Scope مربوط به role_list

1. تب Client scopes مربوط به خود Client را باز کنید. منظور تب روی خود Client است، نه گزینه «Client scopes» در منوی کناری.
2. role_list را پیدا کنید و از منوی ⋮ گزینه Remove را بزنید.

۵. ارسال ایمیل به‌صورت user_email

1. در همان تب Client scopes، روی https://sentry.hamravesh.com/saml/metadata/ORG/-dedicated کلیک کنید.
2. روی Add mapper > From predefined mappers > X500 email کلیک کنید.
3. X500 email را باز کنید و مقدار SAML Attribute Name را روی user_email بگذارید.
4. روی Save کلیک کنید.

۶. تنظیم Endpointهای سنتری

در تب Advanced مربوط به Client:

1. Assertion Consumer Service POST Binding URL: https://sentry.hamravesh.com/saml/acs/ORG/
2. Logout Service POST Binding URL: https://sentry.hamravesh.com/saml/sls/ORG/
3. روی Save کلیک کنید.

۷. اطمینان از وجود کاربر در Keycloak

اگر Realm شما هنوز کاربری ندارد، از Users > Create user یک کاربر بسازید و به او یک آدرس ایمیل بدهید. سنتری کاربران را با ایمیل شناسایی می‌کند، بنابراین هر فردی که وارد می‌شود به ایمیل نیاز دارد.

۸. پیکربندی سنتری

1. در سنتری به Settings > Auth > SAML2 بروید و روی Configure کلیک کنید.

2. Metadata URL: https://KEYCLOAK_HOST/realms/REALM/protocol/saml/descriptor

3. روی Get metadata کلیک کنید. سنتری شما را به Keycloak هدایت می‌کند؛ با کاربر Keycloak خود وارد شوید و به سنتری بازگردانده می‌شوید.

4. نگاشت Attributeها را تنظیم کنید:

   فیلد سنتری	مقدار
   IdP User ID	user_email
   User Email	user_email
   First Name	firstName
   Last Name	lastName

5. روی Save attributes کلیک کنید.

۹. الزام SSO

پیش از این مرحله، نشست فعلی Owner خود را باز نگه دارید و ورود را با یک حساب دوم در پنجره خصوصی تست کنید؛ در غیر این صورت ممکن است کل سازمان قفل شود.

در همان صفحه Auth، زیر بخش General settings، گزینه Require SSO را فعال کنید و روی Save settings کلیک کنید. از این پس SSO فعال است.

۱۰. تست

یک پنجره خصوصی باز کنید و به https://sentry.hamravesh.com/auth/login/ORG/ بروید. باید به Keycloak هدایت شوید، وارد شوید و به‌عنوان کاربر درست به سنتری بازگردید. ایمیل کاربر در سنتری باید با ایمیل Keycloak مطابقت داشته باشد.