mirror of
https://github.com/remnawave/panel.git
synced 2026-03-29 16:44:03 +00:00
docs: add Keycloak authentication help articles (#307)
* docs: add Keycloak authentication help articles - Add AUTH_METHODS_KEYCLOAK.md for en, ru, zh, fa - Document client setup, role creation, and role mapper configuration - Include seamless authentication description and troubleshooting * docs: update Keycloak documentation to match refactored integration - Replace role-based access with claim-based (remnawaveAccess: true) - Add Allowed Emails as alternative access control method - Update field names: keycloakDomain, frontendDomain - Remove seamlessAuth documentation - Update troubleshooting section
This commit is contained in:
StylerHub
80
_panel-docs/help-articles/en/AUTH_METHODS_KEYCLOAK.md
Normal file
80
_panel-docs/help-articles/en/AUTH_METHODS_KEYCLOAK.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# Keycloak Authentication
|
||||
|
||||
Keycloak is an open-source Identity and Access Management solution that provides Single Sign-On (SSO) capabilities.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. A running Keycloak server
|
||||
2. Admin access to create clients
|
||||
|
||||
## Configuration Steps
|
||||
|
||||
### 1. Create a Client in Keycloak
|
||||
|
||||
1. Log in to Keycloak Admin Console
|
||||
2. Select your realm (or create a new one)
|
||||
3. Go to **Clients** → **Create client**
|
||||
4. Configure:
|
||||
- **Client ID**: `remnawave` (or your preferred name)
|
||||
- **Client Protocol**: `openid-connect`
|
||||
- **Client authentication**: `ON`
|
||||
5. Set **Valid redirect URIs**: `https://your-panel-domain.com/oauth2/callback/keycloak`
|
||||
6. Set **Web Origins**: `https://your-panel-domain.com`
|
||||
7. Save the client
|
||||
|
||||
### 2. Get Client Credentials
|
||||
|
||||
1. Go to **Clients** → your client → **Credentials** tab
|
||||
2. Copy the **Client secret**
|
||||
|
||||
### 3. Configure Access Control
|
||||
|
||||
You can control access using **one of two methods** (or both):
|
||||
|
||||
#### Option A: Using Claim (Recommended)
|
||||
|
||||
Add a custom claim `remnawaveAccess: true` to the token:
|
||||
|
||||
1. Go to **Clients** → your client → **Client scopes** tab
|
||||
2. Click on `<your-client-id>-dedicated`
|
||||
3. Go to **Mappers** tab → **Add mapper** → **By configuration**
|
||||
4. Select **Hardcoded claim**
|
||||
5. Configure:
|
||||
- **Name**: `remnawaveAccess`
|
||||
- **Token Claim Name**: `remnawaveAccess`
|
||||
- **Claim value**: `true`
|
||||
- **Claim JSON Type**: `boolean`
|
||||
- **Add to ID token**: `ON`
|
||||
- **Add to access token**: `ON`
|
||||
6. Save
|
||||
|
||||
#### Option B: Using Allowed Emails
|
||||
|
||||
Instead of configuring a claim, you can specify a list of allowed email addresses in the Remnawave settings. Only users with emails in this list will be able to log in.
|
||||
|
||||
## Remnawave Configuration
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| **Keycloak Domain** | Your Keycloak server domain without `https://` (e.g., `keycloak.example.com`) |
|
||||
| **Frontend Domain** | Your Remnawave panel domain without `https://` (e.g., `panel.example.com`) |
|
||||
| **Realm** | The Keycloak realm name (e.g., `master`) |
|
||||
| **Client ID** | The client ID you created |
|
||||
| **Client Secret** | The client secret from Credentials tab |
|
||||
| **Allowed Emails** | List of email addresses allowed to log in (optional if using claim) |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Email is not in the allowed list and remnawaveAccess claim is not present"
|
||||
Make sure either:
|
||||
- The user has the `remnawaveAccess: true` claim configured via mapper, OR
|
||||
- The user's email is added to the Allowed Emails list in Remnawave settings
|
||||
|
||||
### "Invalid redirect URI"
|
||||
Verify that the redirect URI in Keycloak matches exactly: `https://your-panel-domain.com/oauth2/callback/keycloak`
|
||||
|
||||
### "State mismatch"
|
||||
Clear browser cookies and try again. This can happen if the authentication flow was interrupted.
|
||||
|
||||
### "Invalid or missing email claim"
|
||||
Make sure the user has an email address set in Keycloak and email scope is enabled.
|
||||
80
_panel-docs/help-articles/fa/AUTH_METHODS_KEYCLOAK.md
Normal file
80
_panel-docs/help-articles/fa/AUTH_METHODS_KEYCLOAK.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# احراز هویت Keycloak
|
||||
|
||||
Keycloak یک راهحل متنباز مدیریت هویت و دسترسی است که قابلیتهای Single Sign-On (SSO) را فراهم میکند.
|
||||
|
||||
## پیشنیازها
|
||||
|
||||
1. سرور Keycloak در حال اجرا
|
||||
2. دسترسی مدیر برای ایجاد کلاینتها
|
||||
|
||||
## مراحل پیکربندی
|
||||
|
||||
### 1. ایجاد کلاینت در Keycloak
|
||||
|
||||
1. وارد کنسول مدیریت Keycloak شوید
|
||||
2. realm خود را انتخاب کنید (یا یک realm جدید ایجاد کنید)
|
||||
3. به **Clients** → **Create client** بروید
|
||||
4. پیکربندی کنید:
|
||||
- **Client ID**: `remnawave` (یا نام دلخواه شما)
|
||||
- **Client Protocol**: `openid-connect`
|
||||
- **Client authentication**: `ON`
|
||||
5. **Valid redirect URIs** را تنظیم کنید: `https://your-panel-domain.com/oauth2/callback/keycloak`
|
||||
6. **Web Origins** را تنظیم کنید: `https://your-panel-domain.com`
|
||||
7. کلاینت را ذخیره کنید
|
||||
|
||||
### 2. دریافت اعتبارنامه کلاینت
|
||||
|
||||
1. به **Clients** → کلاینت شما → تب **Credentials** بروید
|
||||
2. **Client secret** را کپی کنید
|
||||
|
||||
### 3. پیکربندی کنترل دسترسی
|
||||
|
||||
شما میتوانید با استفاده از **یکی از دو روش** (یا هر دو) دسترسی را کنترل کنید:
|
||||
|
||||
#### گزینه A: استفاده از Claim (توصیه شده)
|
||||
|
||||
یک claim سفارشی `remnawaveAccess: true` به توکن اضافه کنید:
|
||||
|
||||
1. به **Clients** → کلاینت شما → تب **Client scopes** بروید
|
||||
2. روی `<your-client-id>-dedicated` کلیک کنید
|
||||
3. به تب **Mappers** → **Add mapper** → **By configuration** بروید
|
||||
4. **Hardcoded claim** را انتخاب کنید
|
||||
5. پیکربندی کنید:
|
||||
- **Name**: `remnawaveAccess`
|
||||
- **Token Claim Name**: `remnawaveAccess`
|
||||
- **Claim value**: `true`
|
||||
- **Claim JSON Type**: `boolean`
|
||||
- **Add to ID token**: `ON`
|
||||
- **Add to access token**: `ON`
|
||||
6. ذخیره کنید
|
||||
|
||||
#### گزینه B: استفاده از ایمیلهای مجاز
|
||||
|
||||
به جای پیکربندی claim، میتوانید لیستی از آدرسهای ایمیل مجاز را در تنظیمات Remnawave مشخص کنید. فقط کاربرانی که ایمیل آنها در این لیست است میتوانند وارد شوند.
|
||||
|
||||
## پیکربندی Remnawave
|
||||
|
||||
| فیلد | توضیحات |
|
||||
|------|---------|
|
||||
| **Keycloak Domain** | دامنه سرور Keycloak بدون `https://` (مثلاً `keycloak.example.com`) |
|
||||
| **Frontend Domain** | دامنه پنل Remnawave بدون `https://` (مثلاً `panel.example.com`) |
|
||||
| **Realm** | نام realm در Keycloak (مثلاً `master`) |
|
||||
| **Client ID** | شناسه کلاینتی که ایجاد کردید |
|
||||
| **Client Secret** | رمز کلاینت از تب Credentials |
|
||||
| **Allowed Emails** | لیست آدرسهای ایمیل مجاز برای ورود (در صورت استفاده از claim اختیاری است) |
|
||||
|
||||
## عیبیابی
|
||||
|
||||
### "Email is not in the allowed list and remnawaveAccess claim is not present"
|
||||
مطمئن شوید که یکی از شرایط زیر برقرار است:
|
||||
- کاربر claim `remnawaveAccess: true` را از طریق mapper پیکربندی کرده است، یا
|
||||
- ایمیل کاربر به لیست Allowed Emails در تنظیمات Remnawave اضافه شده است
|
||||
|
||||
### "Invalid redirect URI"
|
||||
بررسی کنید که redirect URI در Keycloak دقیقاً مطابقت داشته باشد: `https://your-panel-domain.com/oauth2/callback/keycloak`
|
||||
|
||||
### "State mismatch"
|
||||
کوکیهای مرورگر را پاک کنید و دوباره امتحان کنید. این میتواند اتفاق بیفتد اگر جریان احراز هویت قطع شده باشد.
|
||||
|
||||
### "Invalid or missing email claim"
|
||||
مطمئن شوید که کاربر در Keycloak آدرس ایمیل دارد و email scope فعال است.
|
||||
80
_panel-docs/help-articles/ru/AUTH_METHODS_KEYCLOAK.md
Normal file
80
_panel-docs/help-articles/ru/AUTH_METHODS_KEYCLOAK.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# Аутентификация через Keycloak
|
||||
|
||||
Keycloak - это решение для управления идентификацией и доступом с поддержкой Single Sign-On (SSO).
|
||||
|
||||
## Требования
|
||||
|
||||
1. Работающий сервер Keycloak
|
||||
2. Доступ администратора для создания клиентов
|
||||
|
||||
## Шаги настройки
|
||||
|
||||
### 1. Создание клиента в Keycloak
|
||||
|
||||
1. Войдите в Keycloak Admin Console
|
||||
2. Выберите realm (или создайте новый)
|
||||
3. Перейдите в **Clients** → **Create client**
|
||||
4. Настройте:
|
||||
- **Client ID**: `remnawave` (или другое имя)
|
||||
- **Client Protocol**: `openid-connect`
|
||||
- **Client authentication**: `ON`
|
||||
5. **Valid redirect URIs**: `https://ваш-домен-панели.com/oauth2/callback/keycloak`
|
||||
6. **Web Origins**: `https://ваш-домен-панели.com`
|
||||
7. Сохраните клиент
|
||||
|
||||
### 2. Получение Client Secret
|
||||
|
||||
1. Перейдите в **Clients** → ваш клиент → вкладка **Credentials**
|
||||
2. Скопируйте **Client secret**
|
||||
|
||||
### 3. Настройка контроля доступа
|
||||
|
||||
Вы можете контролировать доступ **одним из двух способов** (или обоими):
|
||||
|
||||
#### Вариант A: Через Claim (Рекомендуется)
|
||||
|
||||
Добавьте claim `remnawaveAccess: true` в токен:
|
||||
|
||||
1. Перейдите в **Clients** → ваш клиент → вкладка **Client scopes**
|
||||
2. Нажмите на `<your-client-id>-dedicated`
|
||||
3. Вкладка **Mappers** → **Add mapper** → **By configuration**
|
||||
4. Выберите **Hardcoded claim**
|
||||
5. Настройте:
|
||||
- **Name**: `remnawaveAccess`
|
||||
- **Token Claim Name**: `remnawaveAccess`
|
||||
- **Claim value**: `true`
|
||||
- **Claim JSON Type**: `boolean`
|
||||
- **Add to ID token**: `ON`
|
||||
- **Add to access token**: `ON`
|
||||
6. Сохраните
|
||||
|
||||
#### Вариант B: Через список email-ов
|
||||
|
||||
Вместо настройки claim вы можете указать список разрешённых email-адресов в настройках Remnawave. Только пользователи с email из этого списка смогут войти.
|
||||
|
||||
## Настройки в Remnawave
|
||||
|
||||
| Поле | Описание |
|
||||
|------|----------|
|
||||
| **Keycloak Domain** | Домен сервера Keycloak без `https://` (например, `keycloak.example.com`) |
|
||||
| **Frontend Domain** | Домен панели Remnawave без `https://` (например, `panel.example.com`) |
|
||||
| **Realm** | Название realm в Keycloak (например, `master`) |
|
||||
| **Client ID** | ID созданного клиента |
|
||||
| **Client Secret** | Секрет из вкладки Credentials |
|
||||
| **Allowed Emails** | Список email-адресов с разрешённым входом (опционально при использовании claim) |
|
||||
|
||||
## Решение проблем
|
||||
|
||||
### "Email is not in the allowed list and remnawaveAccess claim is not present"
|
||||
Убедитесь что выполнено одно из условий:
|
||||
- У пользователя настроен claim `remnawaveAccess: true` через маппер, ИЛИ
|
||||
- Email пользователя добавлен в список Allowed Emails в настройках Remnawave
|
||||
|
||||
### "Invalid redirect URI"
|
||||
Проверьте, что redirect URI точно совпадает: `https://ваш-домен-панели.com/oauth2/callback/keycloak`
|
||||
|
||||
### "State mismatch"
|
||||
Очистите cookies браузера и попробуйте снова. Это может произойти если процесс аутентификации был прерван.
|
||||
|
||||
### "Invalid or missing email claim"
|
||||
Убедитесь, что у пользователя указан email в Keycloak и включён scope email.
|
||||
80
_panel-docs/help-articles/zh/AUTH_METHODS_KEYCLOAK.md
Normal file
80
_panel-docs/help-articles/zh/AUTH_METHODS_KEYCLOAK.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# Keycloak 身份验证
|
||||
|
||||
Keycloak 是一个开源的身份和访问管理解决方案，提供单点登录 (SSO) 功能。
|
||||
|
||||
## 先决条件
|
||||
|
||||
1. 运行中的 Keycloak 服务器
|
||||
2. 创建客户端的管理员权限
|
||||
|
||||
## 配置步骤
|
||||
|
||||
### 1. 在 Keycloak 中创建客户端
|
||||
|
||||
1. 登录 Keycloak 管理控制台
|
||||
2. 选择您的 realm（或创建新的）
|
||||
3. 进入 **Clients** → **Create client**
|
||||
4. 配置：
|
||||
- **Client ID**: `remnawave`（或您喜欢的名称）
|
||||
- **Client Protocol**: `openid-connect`
|
||||
- **Client authentication**: `ON`
|
||||
5. 设置 **Valid redirect URIs**: `https://your-panel-domain.com/oauth2/callback/keycloak`
|
||||
6. 设置 **Web Origins**: `https://your-panel-domain.com`
|
||||
7. 保存客户端
|
||||
|
||||
### 2. 获取客户端凭据
|
||||
|
||||
1. 进入 **Clients** → 您的客户端 → **Credentials** 选项卡
|
||||
2. 复制 **Client secret**
|
||||
|
||||
### 3. 配置访问控制
|
||||
|
||||
您可以使用**以下两种方法之一**（或同时使用）控制访问：
|
||||
|
||||
#### 选项 A：使用 Claim（推荐）
|
||||
|
||||
在令牌中添加自定义 claim `remnawaveAccess: true`：
|
||||
|
||||
1. 进入 **Clients** → 您的客户端 → **Client scopes** 选项卡
|
||||
2. 点击 `<your-client-id>-dedicated`
|
||||
3. 进入 **Mappers** 选项卡 → **Add mapper** → **By configuration**
|
||||
4. 选择 **Hardcoded claim**
|
||||
5. 配置：
|
||||
- **Name**: `remnawaveAccess`
|
||||
- **Token Claim Name**: `remnawaveAccess`
|
||||
- **Claim value**: `true`
|
||||
- **Claim JSON Type**: `boolean`
|
||||
- **Add to ID token**: `ON`
|
||||
- **Add to access token**: `ON`
|
||||
6. 保存
|
||||
|
||||
#### 选项 B：使用允许的邮箱列表
|
||||
|
||||
您可以在 Remnawave 设置中指定允许的邮箱地址列表，而不是配置 claim。只有邮箱在此列表中的用户才能登录。
|
||||
|
||||
## Remnawave 配置
|
||||
|
||||
| 字段 | 描述 |
|
||||
|------|------|
|
||||
| **Keycloak Domain** | Keycloak 服务器域名，不含 `https://`（例如 `keycloak.example.com`）|
|
||||
| **Frontend Domain** | Remnawave 面板域名，不含 `https://`（例如 `panel.example.com`）|
|
||||
| **Realm** | Keycloak realm 名称（例如 `master`）|
|
||||
| **Client ID** | 您创建的客户端 ID |
|
||||
| **Client Secret** | Credentials 选项卡中的客户端密钥 |
|
||||
| **Allowed Emails** | 允许登录的邮箱地址列表（使用 claim 时可选）|
|
||||
|
||||
## 故障排除
|
||||
|
||||
### "Email is not in the allowed list and remnawaveAccess claim is not present"
|
||||
请确保满足以下条件之一：
|
||||
- 用户通过 mapper 配置了 `remnawaveAccess: true` claim，或
|
||||
- 用户的邮箱已添加到 Remnawave 设置的 Allowed Emails 列表中
|
||||
|
||||
### "Invalid redirect URI"
|
||||
验证 Keycloak 中的重定向 URI 完全匹配：`https://your-panel-domain.com/oauth2/callback/keycloak`
|
||||
|
||||
### "State mismatch"
|
||||
清除浏览器 cookies 并重试。如果身份验证流程被中断，可能会发生这种情况。
|
||||
|
||||
### "Invalid or missing email claim"
|
||||
确保用户在 Keycloak 中设置了邮箱地址，并启用了 email scope。
|
||||
Reference in New Issue
Block a user