احراز هویت با SSO در Grafana
بازارچه ابریخواندن 6 دقیقه
با اتصال Grafana به Keycloak از طریق Generic OAuth ورود به Grafana با همان حساب Keycloak (SSO) انجام میشود؛ نقش کاربر در Grafana (Viewer، Editor یا Admin) هم میتواند از روی نقشهای تعریفشده در Keycloak تعیین شود.
پیشنیازها
- یک سرویس فعال Grafana و دسترسی ادمین
- یک سرویس فعال Keycloak
این راهنما یکی از روشهای ممکن برای فعالسازی SSO در Grafana را شرح میدهد و روشهای جایگزین را پوشش نمیدهد.
این راهنما صرفاً برای راهاندازی SSO و ادغام Grafana با Keycloak نوشته شده است. همه الزامات استفاده در محیط Production در آن پوشش داده نشده و پیش از بهکارگیری عملیاتی باید متناسب با نیاز سازمان تکمیل و بررسی شود.
گا م اول: ساخت Client در Keycloak
- در همان realm اختصاصی، از مسیر Clients > Create client، یک Client جدید ساخته میشود؛ برای مثال با Client ID
grafana. - Client authentication روی حالت فعال (Confidential) قرار میگیرد و Standard flow فعال باقی میماند.
- در Valid redirect URIs، آدرس زیر اضافه میشود:
https://your-grafana-domain.xyz/login/generic_oauth
- با کلیک روی Save، Client ذخیره میشود.
پس از ذخیرهشدن Client، دو تب دیگر هم روی همین Client بررسی میشوند:
- از تب Client scopes، اطمینان حاصل میشود که scopeهای
emailوprofileجزو scopeهای Default باشند (این دو معمولاً بهصورت پیشفرض Default هستند). - از تب Credentials، مقدار Client secret کپی میشود.
همزمان با ساخت این Client، یک Client Scope اختصاصی هم بهصورت خودکار ساخته میشود (برای نمونه grafana-dedicated)؛ اما این Scope در ابتدا خالی است و هیچ Mapperای ندارد. ساخت Mapper موردنیاز برای قرار گرفتن نقشها در توکن، در بخش بعد انجام میشود.
گام دوم: ساخت نقشها و تخصیص به کاربران
نقشهای Grafana (admin، editor، viewer) در Keycloak بهصورت Client Roles روی همین Client (نه Realm Roles) ساخته میشوند:
- از تب Roles همین Client، با دکمه Create role، سه نقش با نامهای
admin،editorوviewerساخته میشوند. - از تب Client scopes، روی Scope ا ختصاصی همین Client (برای نمونه
grafana-dedicated) کلیک میشود. - از تب Mappers همان Scope، روی Add predefined mapper کلیک میشود؛ از فهرست بازشده، گزینه client roles انتخاب و اضافه میشود.
همین Mapper مسئول قرار دادن نقشهای Client در claim بهنام resource_access.grafana.roles داخل توکن است؛ بدون این مرحله، نقشها هرگز به توکن Grafana نمیرسند و role_attribute_path در بخش بعد همیشه مقدار پیشفرض (Viewer) را برمیگرداند.
- برای تخصیص نقش به هرکاربر، از مسیر Users، کاربر موردنظر انتخاب و از تب Role mapping، روی Assign role کلیک میشود.
- در پنجره بازشده، با فعال کردن گزینه Filter by clients، نقشهای ساختهشده روی Client
grafana(admin،editorیاviewer) قابل انتخاب و تخصیص هستند.
اگر بهجای Client Roles، از Realm Roles استفاده شود، مسیر claim در توکن و درنتیجه مقدار GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH در بخش بعد باید متناسب با آن (realm_access.roles) تغییر کند.
گام سوم: تنظیم متغیرهای محیطی Grafana
از مسیر کنسول همروش > سرویس Grafana > تنظیمات > متغیرهای محیطی، متغیرهای زیر اضافه میشوند. توضیح کامل هرکدام در مستند رسمی Generic OAuth گرافانا آمده است.
| متغیر | توضیحات |
|---|---|
GF_AUTH_GENERIC_OAUTH_ENABLED | فعالسازی OAuth |
GF_AUTH_GENERIC_OAUTH_NAME | نام نمایشدادهشده روی دکمه ورود |
GF_AUTH_GENERIC_OAUTH_CLIENT_ID | Client ID ساختهشده در Keycloak |
GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET | Client Secret همان Client |
GF_AUTH_GENERIC_OAUTH_SCOPES | Scopeهای درخواستی از Keycloak |
GF_AUTH_GENERIC_OAUTH_AUTH_URL | آدرس Authorization در Keycloak |
GF_AUTH_GENERIC_OAUTH_TOKEN_URL | آدرس Token در Keycloak |
GF_AUTH_GENERIC_OAUTH_API_URL | آدرس User Info در Keycloak |
GF_AUTH_GENERIC_OAUTH_EMAIL_ATTRIBUTE_PATH | مسیر JMESPath برای استخراج ایمیل، در مواردی که تشخیص خودکار ایمیل با مشکل مواجه شود |
GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH | عبارت JMESPath که نقشهای Client ساختهشده در بخش قبل را به نقش Grafana (Admin، Editor یا Viewer) نگاشت میکند |
GF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP | ساخت خودکار کاربر جدید در Grafana در اولین ورود موفق با SSO |
GF_AUTH_GENERIC_OAUTH_ENABLED=true
GF_AUTH_GENERIC_OAUTH_NAME=Keycloak
GF_AUTH_GENERIC_OAUTH_CLIENT_ID=grafana
GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET=<client-secret>
GF_AUTH_GENERIC_OAUTH_SCOPES=openid email profile
GF_AUTH_GENERIC_OAUTH_AUTH_URL=https://your-keycloak-domain/realms/<realm-name>/protocol/openid-connect/auth
GF_AUTH_GENERIC_OAUTH_TOKEN_URL=https://your-keycloak-domain/realms/<realm-name>/protocol/openid-connect/token
GF_AUTH_GENERIC_OAUTH_API_URL=https://your-keycloak-domain/realms/<realm-name>/protocol/openid-connect/userinfo
GF_AUTH_GENERIC_OAUTH_EMAIL_ATTRIBUTE_PATH=email
GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH=contains(resource_access.grafana.roles[*], 'admin') && 'Admin' || contains(resource_access.grafana.roles[*], 'editor') && 'Editor' || 'Viewer'
GF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP=true
پس از افزودن متغیرها، با کلیک روی «اعمال تغییرات»، سر ویس با تنظیمات جدید ریاستارت میشود.
مقدار claim مربوط به ایمیل و نقش، هم در ID Token و هم در پاسخ آدرس User Info بررسی میشود؛ به همین دلیل باید هر دو URL (AUTH_URL/TOKEN_URL و API_URL) درست تنظیم شده باشند.
اگر Client مربوط به Grafana در همان Realmای ساخته شده که کاربران دیگری (مثلاً ادمین کنسول Keycloak) هم در آن نشست فعال دارند، برای اجبار Keycloak به نمایش صفحه ورود در هر بار کلیک روی دکمه SSO (بهجای استفاده خودکار از نشست موجود)، میتوان مقدار ?prompt=login را به انتهای GF_AUTH_GENERIC_OAUTH_AUTH_URL اضافه کرد.
مطابق مستند رسمی، GF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP مختص همین provider است و مستقل از تنظیم عمومی GF_USERS_ALLOW_SIGN_UP عمل میکند. اگر GF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP روی true باشد، هر کاربری که بتواند با موفقیت وارد Keycloak شود، بهصورت خودکار در Grafana هم حساب میسازد؛ اگر لازم است فقط کاربرانی که از قبل در Grafana ساخته شدهاند اجازه ورود با SSO داشته باشند، این متغیر باید روی false تنظیم شود.
گام چهارم: ورود با SSO
پس از اعمال تغییرات، در صفحه ورود Grafana، دکمهای با عنوان مقدار GF_AUTH_GENERIC_OAUTH_NAME (مثلاً «Keycloak») نمایش داده می شود. با کلیک روی این دکمه، کاربر به Keycloak ریدایرکت و پس از ورود موفق وارد Grafana میشود.
اگر Keycloak کاربران را از طریق ادغام با LDAP از یک دایرکتوری سازمانی federate کرده باشد، همان کاربران بدون هیچ تنظیم اضافهای در Grafana، از همین دکمه SSO وارد میشوند.
عیبیابی
ایمیل کاربر در Keycloak خالی نباشد. طبق مستند رسمی Generic OAuth وجود مقدار ایمیل برای ساخت یا ورود کاربر در Grafana الزامی است؛ اگر فیلد Email در پروفایل کاربر Keycloak خالی باشد ورود با خطای مربوط به ایمیل شکست میخورد. تیک Email verified روی پروفایل کاربر توسط خود Grafana بررسی نمیشود، اما روشن نگهداشتن آن در Keycloak توصیه میشود تا فرایندهای الزام به تأیید ایمیل (Required Actions) در میانه مسیر SSO ظاهر نشوند.
بررسی توکن از تب Evaluate. پیش از تست ورود واقعی، میتوان از مسیر Client scopes > Evaluate (روی همان Client grafana) یک کاربر مشخص را انتخاب کرد و ID Token، Access Token و پاسخ User Info تولیدشده برای آن کاربر را مشاهده کرد. این کار برای بررسی وجود claimهای email و resource_access.grafana.roles پیش از هر تست SSO مفید است.
تست عبارت role_attribute_path. برای اطمینان از درستی عبارت JMESPath استفادهشده در GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH، میتوان مقدار خروجی تب Evaluate را در ابزار رسمی jmespath.org بهعنوان payload وارد و عبارت را روی آن آزمایش کرد.
راهنماییهای مرتبط
این راهنمایی کاربردی بود؟
با ثبت بازخوردتان در بهبود کیفیت مستندات مشارکت داشته باشید.