نحوه اتصال سامانه‌ها به Keycloak با استفاده از پروتکل OAuth2/OpenID

هدف از این مستند ارائه راهنمایی یکپارچه سازی یک نرم افزار (که برای راحتی به آن SW گفته می شود) با ابزار لاگین مرکزی Keycloak مبتنی بر پروتکل OAuth/OpenID می باشد.

هدف نهایی این یکپارچه سازی، ارائه قابلیت لاگین مرکزی در آن  نرم افزار است به این صورت که در صورتی که کاربر در نرم افزار Keycloak لاگین کرده باشد،‌ دیگر احتیاج به لاگین در نرم افزار مورد نظر نداشته باشد . بدین ترتیب می‌توان صفحه لاگین را از نرم افزار مورد نظر حذف کرد و در صورت نیاز به لاگین، کاربر را به صفحه لاگین نرم افزار Keycloak منتقل نمود. البته در صورت نیاز می توان امکان لاگین در خود نرم‌افزار (بدون اتصال به سرور احراز هویت یا همان keycloak) را حفظ نمود و امکان لاگین از طریق Keycloak را به صورت همزمان فعال نمود. بدین منظور لازم است فرایند عمومی لاگین نرم افزار را تغییر ندهیم و در صفحه لاگین یک دکمه «لاگین با سرور احراز هویت مرکزی» اضافه نمود که کاربر با زدن آن به صفحه لاگین Keycloak منتقل شود.

به منظور اتصال یک سامانه به Keycloak، لازم است یک سرور Keycloak قابل دسترس داشته باشید که امکان لاگین در آن و تغییر تنظیمات آن برای شما فراهم باشد. همچنین لازم است امکان ایجاد تغییرات در نرم افزار مربوطه برای شما فراهم باشد.

لازم به ذکر است که مستند اصلی نحوه اتصال به سامانه keycloak‌ در این آدرس قابل مشاهده است و استفاده از آن توصیه می شود. در این مستند خلاصه ای از یک نمونه از اتصال نرم افزار با یک پروتکل و یک فریم ورک بررسی می شود و برای کسب اطلاعات از نحوه اتصال باقی پروتکل ها و باقی فریم‌ورک ها،‌ لازم است به آدرس اشاره شده مراجعه نمایید.

شرکت دانش بنیان پلتکو ، ارائه دهنده خدمات تخصصی یکپارچه سازی و مدیریت وب‌سرویس‌ها می‌باشد که خدماتی نظیر پیاده سازی sso ، گذرگاه سرویس‌های سازمانی (ESB) و مدیریت وب‌سرویس‌ها (API Manager)، مانیتورینگ، مدیریت لاگ‌ها، وب پرتال و ده‌ها سرویس تخصصی دیگر به سازمان‌ها ارائه می‌دهد.

فرایند لاگین مرکزی

به منظور درک بهتر نحوه انجام شدن لاگین مرکزی، فرایند کلی آن با استفاده از پروتکل گفته شده توضیح داده می شود.
عموما در فرایند لاگین مرکزی نرم افزارهای تحت وب (به عنوان مثال SW) این گام‌ها انجام می شود:

1.  کاربر در مرورگر در حالتی که هنوز لاگین نیست، به یکی از صفحه های SW می رود.
2. نرم افزار SW کاربر را به صفحه لاگین نرم افزار احراز هویت مرکزی (Keycloak) منتقل می‌کند.
3. کاربر در نرم افزار احراز هویت مرکزی لاگین می‌کند. بنابراین کلا نرم افزار SW با پسورد کاربر مواجه نخواهد شد.
4. پس از احراز هویت توسط Keycloak برای کاربر کلید هویت ایجاد شده و کاربر به نرم افزار SW منتقل شده و این کلید هویت طریق URL به نرم افزار SW منتقل می شود. این کلید هویت شامل اطلاعات هویتی کاربر مانند نام کاربری، آدرس ایمیل و دیگر اطلاعات پروفایل کاربر به صورت امضا شده می باشد.
5. سپس نرم افزار SW از طریق یک وب‌سرویس ارائه شده توسط سرور Keycloak از درست بودن این کلید هویت، اطمینان حاصل می نماید و کاربر را لاگین شده فرض می کند.

a. البته علاوه بر این روش که به آن احراز درست بودن کلید هویت آنلاین گفته می شود، روش آفلاین احراز هویت نیز وجود دارد که در آن نرم افزار SW بدون ارسال درخواست به سرور Keycloak و از طریق پروتکل های رمزنگاری از صحت این کلید هویت، اطمینان حاصل می کند.
 

در ادامه این مطلب پیشنهاد می‌شود مطلب keycloak  چیست را مطالعه نمایید.

روش اتصال یک نرم افزار به Keycloak

به منظور اتصال یک سامانه به Keycloak، به فرض استفاده از پروتکل OAuth/OpenID ، باید فرایند‌های زیر انجام گردد:

1.  باید این نرم افزار به عنوان یک client برای Keycloak‌ تعریف گردد و تنظیمات لازم برای آن در Keyclaok انجام شود. 
2. باید در فرایند احراز هویت نرم افزار تغییراتی ایجاد شود که با احراز هویت مرکزی هماهنگ شود.

در ادامه این مستند به توضیح هر یک از این دو مرحله می پردازیم. در هر قسمت از این بخش، در صورت لزوم اصطلاحات مورد استفاده در Keycloak توضیح داده خواهد شد.

تعریف تنظیمات در سرور Keycloak

1. برای این کار، ابتدا باید به کنسول مدیریتی Keycloak وارد شوید. بدین منظور باید به آدرس keycloak رفته و روی گزینه «Administration Console» کلیک کنید:

 

 

2. باید یک Realm جدید بسازید یا از Realm اصلی یا Master استفاده کنید.

 

 

هر Realm‌ در واقع مجموعه ای از نرم افزارهاست که قرار است با هم لاگین شوند. یعنی لاگین در یکی از آنها به معنی لاگین در باقی آنهاست. عموما استفاده از Master کافی می باشد.

a. در صورت نیاز به ساخت Realm جدید کافیست از کلید Create Realm استفاده کرده و یک نام برای Realm جدید انتخاب کنید و پس از ساخته شدن آن Realm را انتخاب کنید.
 

3. در این مرحله لازم است نرم افزار SW را به عنوان یک Client جدید برای Keycloak‌ معرفی کنید. بدین منظور کافی‌ست از منوی سمت چپ به بخش Clients رفته و روی دکمه ساخت Client‌ کلیک کنید:

 

 

در فرم باز شده لازم است مقدار فیلد Client Type را برابر OpenID Connect انتخاب کنید. فیلد Client ID را با یک عبارت مخصوص آن نرم افزار پر کنید.

از آنجا که این نام در url خواهد آمد، بهتر است از حروف انگلیسی و dash تشکیل شده باشد. نام و توضیحات را نیز به دلخواه پر کنید و سپس دکمه Next را بزنید.

 

 

بخش دوم از wizard را با مقادیر پیش فرض Save کنید. ( از تیک خورده بودن Standard flow‌ و Direct access grants اطمینان حاصل کنید)

 

4. در صفحه تنظیمات کلاینت که بلافاصله پس از ساخت آن فعال می شود، باید فیلد‌های زیر را پر کنید:
a. فیلد Root Url را با آدرس اصلی نرم افزار SW پر کنید.

به عنوان مثال این آدرس را مقدار http://SWDomain:8080/SW/ فرض می کنیم.

b. فیلد Home Url را با آدرسی که می‌خواهید کاربر پس از لاگین موفق به صورت پیش‌فرض به آن redirect شود مقدار دهی کنید. به عنوان مثال

http://SWDomain:8080/SW/home

c. فیلد Valid Redirect URIs را باید بر اساس آدرس های قرار دهید که ممکن است کاربر به آن redirect شود. به عنوان مثال

http://SWDomain:8080/SW/*

d. فیلد Web Origins را برابر دامین نرم افزار SW قرار دهید. به عنوان مثال http://SWDomain:8080
e. فیلد Admin Url را برابر آدرس صفحه ادمین نرم افزار SW قرار دهید. به عنوان مثال

http://SWDomain:8080/SW/Admin

 

f. سپس کلید save را بزنید.
g. در پایان طبق تصویر زیر کلید Download adapter config را بزنید.

 

 

h. از پاپاپ باز شده کلید دانلود را زده و فایل Json تنظیمات را در جایی ذخیره کنید که در مراحل بعدی از آن استفاده کنید. این فایل حاوی تنظیمات مورد نیاز برای اتصال به Keycloak از طریق چارچوب های مختلف نرم افزاری در نرم افزار SW می باشد.

جهت تکمیل اطلاعات خود در این زمینه پیشنهاد می‌شود مطلب oauth چیست را مطالعه نمایید.

 

هماهنگ کردن فرایند احراز هویت نرم افزار با احراز هویت مرکزی

نرم افزار Keycloak‌ برای عموم زبان ها و فریمورک های احراز هویت، بسته نرم افزاری تحت عنوان adapter داده است که در این آدرس لیست شده اند. 

همچنین در این پروژه نمونه اپلیکیشن ها مختلف با زبان ها و چارچوب های مختلف آمده و نحوه اتصال آنها به Keycloak شرح داده شده است. به عنوان مثال در این صفحه نمونه اتصال یک نرم افزار Single page با استفاده از javascript آورده شده است.  

همچنین در صورت نیاز به پیاده کردن مستقیم اتصال به Keycloak، می توانید از Endpoint های ارائه شده توسط Keycloak که منطبق بر استاندارد OpenID Connect می باشند استفاده کنید.

این Endpoint ها در این آدرس لیست شده و توضیح داده شده اند. به عنوان مثال از طریق مراجعه به آدرس زیر می توانید اطلاعات استاندارد تعریف شده در پروتکل OpenID Conncet برای استفاده از OpenID Connect Discovery را ببینید: 

 

https:// KEYCLOAK-DOMAIN/auth/realms/master/.well-known/openid-configuration

 

بدین ترتیب در کتابخانه هایی که از OpenID Connect Discovery پشتیبانی می‌کنند، به راحتی با ارائه آدرس https://KEYCLOAK-DOMAIN/auth/realms/master می توانید اتصال را انجام دهید.

به عنوان نمونه برای اتصال یک سامانه که با Spring Boot  نوشته شده به راحتی می توانید با تنظیم یک آدرس اتصال را فراهم کنید. در این مستند نحوه انجام این تنظیمات آمده است.