</details>

### Настройка базы данных

Kviklet нуждается в собственной базе данных postgres (или как минимум схеме) для хранения метаданных о запросах, подключениях, одобрениях и т. д.
Официальный образ можно найти здесь: https://hub.docker.com/_/postgres, или использовать облачную версию, предоставляемую вашим облачным провайдером.

При запуске контейнера kviklet вам нужно будет соответствующим образом задать эти три переменные окружения:```
SPRING_DATASOURCE_PASSWORD = password
SPRING_DATASOURCE_USERNAME = username
SPRING_DATASOURCE_URL = jdbc:postgresql://[host]:[port]/[database]?currentSchema=[schema]

Мы публикуем наши контейнеры в GitHub packages на данный момент, так что со всеми этими настройками вы можете запустить `ghcr.io/kviklet/kviklet:main`, не забудьте сопоставить порт `8080`, который является портом по умолчанию, на котором запускается Kviklet.

Пример запуска docker может выглядеть так:```
docker run \
-e SPRING_DATASOURCE_PASSWORD=postgres \
-e SPRING_DATASOURCE_USERNAME=postgres \
-e SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/Kviklet \
-e [email protected] \
-e INITIAL_USER_PASSWORD=someverysecurepassword \
--network host \
ghcr.io/kviklet/kviklet:main

Google client id и secret можно легко получить, следуя инструкциям Google здесь:
https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid

Для допустимых redirect URI следует настроить: https://[kviklet_host]/api/login/oauth2/code/google
Для Allowed Origins — просто URL вашего размещённого kviklet.

После настройки этих переменных окружения все в вашей организации смогут войти с помощью кнопки sign in with google. Но по умолчанию у них не будет никаких разрешений — вам нужно будет назначить им роль после того, как они войдут один раз.

#### Keycloak

Если вы хотите настроить SSO с Keycloak вместо этого, вам нужно задать эти 4 переменные окружения:```
KVIKLET_IDENTITYPROVIDER_CLIENTID
KVIKLET_IDENTITYPROVIDER_CLIENTSECRET
KVIKLET_IDENTITYPROVIDER_TYPE=keycloak
KVIKLET_IDENTITYPROVIDER_ISSUERURI=http://[host]:[port]/realms/[realm]

Создайте GitHub OAuth App на https://github.com/settings/developers и настройте:

- Authorization callback URL: `https://[kviklet_host]/api/login/oauth2/code/github`
- Homepage URL: URL вашего размещённого Kviklet

`KVIKLET_IDENTITYPROVIDER_GITHUB_ALLOWEDORGS` **обязателен** (Kviklet отказывается запускаться без него). GitHub OAuth Apps не могут ограничить, кто завершает OAuth-поток, поэтому Kviklet вызывает `/user/orgs` после аутентификации и отклоняет пользователей, которые не являются членами хотя бы одной организации из списка разрешённых (без учёта регистра, проверяются первые 100 организаций).

Чтобы проверка организаций увидела членство пользователя, пользователь должен нажать **Grant** (или **Request**) рядом с каждой организацией из списка разрешённых на экране согласия OAuth. Если в организации включено "Restrict third-party OAuth applications", владелец организации также должен один раз одобрить OAuth-приложение, прежде чем членство любого участника станет видимым.

Kviklet запрашивает области `read:user`, `user:email` и `read:org`. Адреса электронной почты всегда читаются из `/user/emails`, и принимается только запись `primary && verified`, поэтому пользователи с приватными адресами электронной почты всё равно успешно входят в систему.

#### Другие OIDC-провайдеры

Другие OIDC-совместимые провайдеры (GitLab, Auth0, Okta и т. д.) должны работать аналогично Keycloak. Обратите внимание, что `redirect URI` будет меняться в зависимости от выбранного типа, поэтому если вы выберете `gitlab`, он будет `https://[kviklet_host]/api/login/oauth2/code/gitlab`.
Если вы столкнётесь с проблемами, не стесняйтесь создать issue — мы ещё не пробовали все существующие OIDC-провайдеры (пока что), и могут быть небольшие различия в реализации, которые могут потребовать обновлений на стороне Kviklet.

### LDAP

Kviklet поддерживает LDAP-аутентификацию. Чтобы включить и настроить LDAP, вы можете переопределить следующие переменные окружения:```
LDAP_ENABLED=true
LDAP_URL=ldap://your-ldap-server:389
LDAP_BASE=dc=your,dc=domain,dc=com
LDAP_PRINCIPAL=cn=admin,dc=your,dc=domain,dc=com
LDAP_PASSWORD=your-admin-password
LDAP_UNIQUE_IDENTIFIER_ATTRIBUTE=uid
LDAP_EMAIL_ATTRIBUTE=mail
LDAP_FULL_NAME_ATTRIBUTE=cn
LDAP_USER_OU=people
LDAP_SEARCH_BASE=ou=people

Детали конфигурации:

- `SAML_ENABLED`: Установите `true`, чтобы включить аутентификацию SAML
- `SAML_ENTITYID`: Идентификатор сущности вашего поставщика удостоверений SAML
- `SAML_SSOSERVICELOCATION`: URL-адрес службы SSO вашего поставщика удостоверений
- `SAML_VERIFICATIONCERTIFICATE`: Сертификат X.509, используемый для проверки ответов SAML (включите строки BEGIN/END CERTIFICATE)

При необходимости вы можете настроить сопоставления атрибутов SAML:```
SAML_USERATTRIBUTES_EMAILATTRIBUTE=email
SAML_USERATTRIBUTES_NAMEATTRIBUTE=name
SAML_USERATTRIBUTES_IDATTRIBUTE=nameID

## Конфигурация

### Подключения

После запуска Kviklet сначала необходимо настроить подключение к базе данных. Перейдите в Settings -> Databases -> Add Connection.

![Add Connection](https://assets.kitploit.com/production/public/readmes/7140/3ded2a0b23e5d2f02feb21a854263c91dedea25a789fb75ab8342384c4e39b52.png)
![Add Connection](https://assets.kitploit.com/production/public/readmes/7140/585238c9eddad8ed4e2440096ce0616445a6696e1042f58676a1d0b038edde7f.png)

Здесь вы можете настроить требования к проверке и лимиты выполнения для каждого подключения. Подробности см. в разделе [Review Gates](#review-gates).

#### AWS IAM AUTH

Kviklet поддерживает использование IAM Auth для подключений к базам данных Postgres, MySQL и MariaDB. Для этого выберите IAM Auth при создании нового подключения.

![IAM Auth](https://assets.kitploit.com/production/public/readmes/7140/14ed42bd639eb9b0ba81b22850e277703f2da9495dd101f68066f95fc51f291c.png)
![IAM Auth](https://assets.kitploit.com/production/public/readmes/7140/5a60a3a9ae527e11679f3c33c787caba4c80b379ddc463db1f871288408517e1.png)

Это уберёт возможность задать пароль и вместо этого будет использовать учётные данные AWS для подключения к базе данных.

Kviklet использует `DefaultCredentialsProvider` от AWS для поиска учётных данных и генерации токена для подключения. Это означает, что все типичные места должны работать (переменные окружения или связанные роли экземпляра). Точный порядок задокументирован здесь: https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/DefaultCredentialsProvider.html

Дополнительно вы можете указать ARN роли AWS, которую Kviklet будет принимать, и использовать эти учётные данные для создания временного токена БД. Это особенно полезно для подключения к базам данных, которые находятся не в том же аккаунте AWS, что и Kviklet. Чтобы использовать эту функцию, просто введите ARN роли в соответствующее поле при создании или редактировании подключения IAM Auth. Если оставить поле пустым, будет использоваться провайдер учётных данных по умолчанию (без принятия роли).

Регион AWS, используемый при генерации токена, определяется из URL вашего подключения, поэтому возможности задать его вручную нет.

Чтобы узнать, как настроить IAM Auth для вашей базы данных, обратитесь к официальной документации AWS: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html
Основные два момента:

- Создайте пользователя БД с опцией IAM auth и правильными разрешениями
- Создайте политику IAM, которая позволяет сущности AWS генерировать токены для этого пользователя

### Review Gates

По умолчанию Kviklet позволяет использовать простую конфигурацию количества проверок. Вы можете настроить, сколько одобрений требуется для запросов на конкретном подключении, прежде чем они могут быть выполнены.

Статус одобрения запроса рассчитывается на основе последнего действия каждого проверяющего. Если проверяющий одобряет, а затем запрашивает изменения, учитывается только запрос на изменение — его предыдущее одобрение удаляется. Редактирование запроса всегда сбрасывает все предыдущие одобрения, гарантируя, что никакие изменения не могут быть выполнены без предварительной проверки. Аналогично, если выполнение завершается неудачей (например, из-за синтаксической ошибки SQL), одобрения сбрасываются, чтобы запрос можно было исправить и повторно одобрить без необходимости создавать новый.

Вы также можете настроить лимит **max executions** для каждого подключения, чтобы контролировать, как часто один одобренный запрос может быть выполнен. По умолчанию — 1. Установка значения 0 разрешает неограниченное количество выполнений. Неудачные выполнения не учитываются в этом лимите.

#### Требования к проверке на основе ролей (Enterprise)

С лицензией Kviklet Enterprise вы можете настроить отдельные подключения так, чтобы они требовали одобрения от пользователей с определёнными ролями. Это позволяет, например, требовать одобрения от команды, которая обслуживает данную базу данных, или ограничивать доступ к чувствительным подключениям одобрением DBA или руководства.

**Как это работает:**

Каждое подключение имеет **общее количество требуемых проверок** (`numTotalRequired`), которое действует как минимум — минимальное количество различных одобрений, необходимых независимо от ролей. В дополнение к этому вы можете добавить **требования к ролям**, которые указывают, сколько одобрений должно поступить от пользователей с определённой ролью (например, «1 от DBA, 1 от Security»).

Запрос одобряется только тогда, когда выполнены **оба** условия:

- Общее количество различных одобрений соответствует `numTotalRequired`
- Каждое требование к роли удовлетворено отдельно

Если пользователь принадлежит к нескольким ролям, одно одобрение от этого пользователя учитывается для всех соответствующих требований к ролям. Однако оно всё равно считается только одним одобрением в общем количестве.

**Пример:** Для подключения требуется 3 общих одобрения, включая 1 от DBA и 1 от Security. Пользователь, имеющий одновременно роли DBA и Security, одобряет — это удовлетворяет оба требования к ролям, но считается только как 1 из 3 необходимых общих одобрений. Всё ещё требуются два дополнительных одобрения от любых пользователей.

Если срок действия вашей корпоративной лицензии истекает, существующие требования к проверке на основе ролей продолжают применяться, но их больше нельзя изменять. Вы можете только удалить их, чтобы вернуться к простой конфигурации общего количества проверок.

### Роли

Kviklet поставляется с 3 ролями: Default, Admins и Developers.

- Роль по умолчанию предоставляет доступ на чтение ко всем подключениям и запросам. Эта роль назначается каждому пользователю и не может быть удалена. Однако вы можете изменять разрешения этой роли по своему усмотрению.
- Admins имеют разрешение создавать и редактировать подключения, а также добавлять новых пользователей и настраивать их разрешения.
- Developers могут создавать запросы, а также одобрять их и комментировать, и, конечно же, выполнять сами операторы.

Вы можете настраивать роли и, например, дать роли доступ только к конкретному подключению или группе подключений к БД.
Это полезно, например, если у вас есть разные команды с разными базами данных и вы хотите более гранулярно контролировать доступ к ним.

#### Создание новой роли

Создание новой роли работает следующим образом. Перейдите в Settings -> Roles -> Add Role.

![Add Role](https://assets.kitploit.com/production/public/readmes/7140/a91b79287c0b3130b83bdde1c059f49b89c5d43a1c0deae33b211ea427956f8e.png)
![Add Role](https://assets.kitploit.com/production/public/readmes/7140/c535ac152759bb21bea04a0968ce43fa7bf946c7699feca23c71f9eaba41ceaf.png)

Настройки по умолчанию не так важны для большинства ролей, и вы можете просто дать User Read и RoleView Access и на этом остановиться.
Более интересно добавление отдельных разрешений для подключений. Здесь вы сначала добавляете селектор для выбора конкретных подключений. Это может быть либо конкретный id, либо вы используете подстановочные знаки с `*` для сопоставления нескольких подключений. Например, если вы хотите иметь роль с доступом ко всем dev-базам данных (в случае, если вы также управляете доступом к ним с помощью kviklet), вы бы использовали селектор вроде `dev-*` и убедились, что id подключений заданы правильно.

Вы, конечно, также можете придумать систему, которую используете для своих разных команд внутри вашей организации.

### Синхронизация ролей (Enterprise)

Автоматически синхронизируйте роли пользователей из групп вашего провайдера идентификации. Эта функция требует корпоративной лицензии.

**Конфигурация** выполняется в Settings > Role Sync:

- **Enable Role Sync**: Включение/выключение синхронизации
- **Sync Mode**:
  - **Full Sync** — роли пользователей точно соответствуют их сопоставлениям групп IdP (плюс роль по умолчанию)
  - **Additive** — группы IdP добавляют роли, но не удаляют существующие
  - **First Login Only** — роли синхронизируются только при первом входе, ручные изменения сохраняются впоследствии
- **Groups Attribute**: Атрибут IdP, содержащий членство в группах (по умолчанию: `groups`)
- **Role Mappings**: Сопоставление имён групп IdP (например, `engineering`) с ролями Kviklet

#### Настройка OIDC

Настройте вашего провайдера OIDC так, чтобы он включал claim `groups` в ID-токен:

- **Keycloak**:

  Keycloak по умолчанию не включает группы в токены, поэтому вам нужно добавить mapper к клиенту.
  1. Перейдите в **Clients** в левом меню
  2. Выберите ваш клиент Kviklet
  3. Перейдите на вкладку **Client scopes**
  4. Нажмите на выделенный scope (например, `kviklet-dedicated`)
  5. Перейдите на вкладку **Mappers**
  6. Нажмите **Add mapper** → **By configuration**
  7. Выберите **Group Membership**
  8. Настройте mapper:

  | Setting             | Value    |
  | ------------------- | -------- |
  | Name                | `groups` |
  | Token Claim Name    | `groups` |
  | Full group path     | **OFF**  |
  | Add to ID token     | **ON**   |
  | Add to access token | **ON**   |
  | Add to userinfo     | **ON**   |
  9. Нажмите **Save**

  > **Важно:** «Token Claim Name» должен совпадать с «Groups Attribute», настроенным в настройках Role Sync Kviklet (по умолчанию: `groups`).

- **Другие провайдеры OIDC**: Добавьте mapper/claim групп, который включает членство пользователя в группах в ID-токен. Обычно это делается в административном интерфейсе провайдера.

  Если вы столкнётесь с проблемами, не стесняйтесь создать issue — мы ещё не пробовали каждый существующий провайдер OIDC (пока), и могут быть небольшие различия в реализации, которые могут потребовать обновлений на стороне Kviklet.

#### Настройка LDAP

Синхронизация ролей LDAP использует атрибут `memberOf`:

1. Убедитесь, что на вашем сервере LDAP включён overlay `memberOf`
2. Установите **Groups Attribute** в `memberOf` в Kviklet
3. Имена групп затем извлекаются из атрибута `memberOf` в атрибутах пользователей.

#### Настройка SAML

Настройте вашего провайдера SAML IdP так, чтобы он включал группы в assertion:

1. Добавьте attribute statement, который сопоставляет членство пользователя в группах
2. Установите **Groups Attribute** в Kviklet в соответствии с именем вашего атрибута SAML
3. Имена групп затем извлекаются из атрибута SAML в атрибутах пользователей.

### Уведомления

Вы можете настроить Kviklet для отправки уведомлений в канал в Slack или Teams. Это полезно для уведомления вашей команды о новых запросах, требующих проверки. Вы можете настроить это в Settings -> General -> Notification Settings.

#### Slack

Чтобы настроить уведомления Slack, вам нужно создать Slack App и включить для него webhooks. Вы можете следовать инструкциям здесь: https://api.slack.com/messaging/webhooks

#### Teams

Уведомления Teams используют webhook **Workflow** Power Automate. Kviklet отправляет Adaptive Card, которую шаблон webhook публикует в вашем канале.

**Рекомендуется: использовать шаблон workflow**

1. В Teams откройте канал, в который хотите получать уведомления, нажмите **...** рядом с именем канала и выберите **Workflows** (или добавьте приложение **Workflows**).
2. Найдите и создайте шаблон **«Send webhook alerts to a channel»**.
3. Войдите в систему, когда будет предложено, затем выберите целевые Team и Channel и создайте workflow.
4. Откройте шаг trigger и скопируйте сгенерированный **HTTP POST URL**.
5. Вставьте URL в Kviklet в разделе Settings -> General -> Notification Settings и нажмите save.

**Альтернатива: создать workflow вручную**

Если вы предпочитаете создать flow самостоятельно (или шаблон недоступен):

1. Channel **...** -> **Workflows** -> создайте flow с триггером **«When a Teams webhook request is received»**.
2. Добавьте действие **Microsoft Teams -> «Post card in a chat or channel»**.
3. Установите поле **Adaptive Card** действия в выражение `string(triggerBody())`, чтобы оно публиковало карточку, которую отправляет Kviklet.
4. Выберите целевые Team и Channel, **Save**, затем скопируйте **HTTP POST URL** из шага trigger.

В настоящее время есть уведомления для:

- Новых запросов, требующих одобрения
- Новых одобрений запросов

#### Настройка Base URL

При запуске Kviklet за обратным прокси или Kubernetes Ingress ссылки в уведомлениях могут использовать внутренний IP-адрес вместо вашего публичного домена. Kviklet пытается отслеживать правильный URL, анализируя входящие запросы, но некоторые обратные прокси не устанавливают заголовки Forwarded корректно. Чтобы исправить это, задайте base URL явно:```
KVIKLET_BASE_URL=https://kviklet.example.com

Kviklet записывает одну строку при запуске, сообщая, включена ли телеметрия.

**Что отправляется.** Каждое событие содержит случайный идентификатор экземпляра (генерируется один раз и хранится в базе данных Kviklet), базовый URL, по которому доступен Kviklet (см. выше; часто это внутреннее имя хоста), и версию Kviklet. Пользователи идентифицируются только по непрозрачному идентификатору в пределах экземпляра, что позволяет подсчитывать уникальных пользователей, но адреса электронной почты или имена никогда не отправляются. Точные события и их свойства определены в `backend/src/main/kotlin/dev/kviklet/kviklet/telemetry/TelemetryEvent.kt`.

**Что никогда не отправляется.** Запросы, инструкции, результаты, вывод команд, сообщения об ошибках, имена подключений, имена хостов, учётные данные, заголовки или описания запросов, комментарии, а также имена пользователей или ролей.

### Логирование

По умолчанию Kviklet записывает удобочитаемые (pretty) логи в stdout, что удобно
при чтении их напрямую или через `docker logs`.

Если вы отправляете логи в централизованную систему (Elasticsearch, Loki, Datadog, CloudWatch, …), вы
можете переключиться на структурированные **JSON-логи**, которые проще индексировать и запрашивать. Задайте
формат через переменную окружения:```
# One of: ecs (Elastic Common Schema), logstash, gelf (Graylog)
LOGGING_STRUCTURED_FORMAT_CONSOLE=ecs

Kviklet зашифрует все ваши существующие учётные данные при запуске и будет использовать секрет для будущих подключений, которые вы создаёте.

### Ротация ключей

Если вы хотите выполнить ротацию ключа, вы можете просто добавить ещё одну переменную для предыдущего ключа и изменить текущий:```
ENCRYPTION_KEY_PREVIOUS=some-secret
ENCRYPTION_KEY_CURRENT=another-secret

API-ключи наследуют разрешения пользователя, который их создаёт. В настоящее время только администраторы могут управлять API-ключами, и все действия, выполняемые с помощью API-ключа, приписываются пользователю, создавшему этот ключ.

Некоторую базовую документацию по API можно найти по адресу `[kviklet_host]/api/swagger-ui/index.html`. Но имейте в виду, что это находится в разработке, и API может измениться в будущих версиях.

В конечном счёте истина — в коде, поэтому вы всегда можете посмотреть на контроллер, чтобы увидеть, как определён API. Если у вас есть вопросы, не стесняйтесь открыть issue.

## Экспериментальные функции

В настоящее время существует две экспериментальные функции. Они были созданы в основном на основе отзывов сообщества. Не стесняйтесь попробовать их и оставить любые свои замечания. Мы надеемся развивать их дальше в будущем и обеспечить хорошую совместимость с основным процессом одобрения.

### Kubernetes Exec

Если вы хотите использовать функцию Kubernetes Exec, вам необходимо создать отдельное подключение к Kubernetes. Kviklet будет использовать пользователя развёрнутого пода для выполнения команды. Поэтому убедитесь, что у этого пользователя есть необходимые разрешения для выполнения команд на подах, к которым вы хотите получить доступ.

Kviklet также использует /bin/sh для выполнения команды, поэтому вам нужно убедиться, что в ваших подах есть оболочка или хотя бы символическая ссылка в /bin/sh. Если это вас не устраивает, не стесняйтесь открыть issue — мы потенциально можем сделать это настраиваемым или найти другое решение.

Команды Kubernetes ожидают вывода только 5 секунд; если команда выполняется дольше, Kviklet будет ждать до часа, прежде чем прервать команду по тайм-ауту. Это временное решение; мы изучаем возможность использования websockets, чтобы сделать это более отзывчивым и потенциально включить терминальные сессии.

### Прокси — Postgres, MariaDB, MySQL (Enterprise)

Если вы создаёте запросы на временный доступ, вы можете — вместо использования веб-интерфейса — выполнять свои запросы через управляемый kviklet прокси и использовать DB-клиент на ваш выбор.
Прокси является функцией уровня enterprise: для него требуется действующая лицензия, и администратор дополнительно должен включить его в разделе Settings -> General -> Database Proxy.
Для этого контейнер прослушивает стабильные порты (по умолчанию 5432 и 3306, настраиваются через `kviklet.proxy.postgres.port` и `kviklet.proxy.mysql.port`), поэтому вам нужно открыть эти порты.
Затем пользователи могут создать запрос на временный доступ и нажать «Start Proxy» после его одобрения. Каждый запрос получает временное имя пользователя и пароль; Kviklet направляет каждое подключение к его запросу по имени пользователя. С ними они могут подключиться к базе данных. Kviklet проверяет временного пользователя и пароль и проксирует все запросы к нижележащему пользователю в базе данных. Любые выполненные операторы регистрируются в журнале аудита так, как если бы они были выполнены через веб-интерфейс.

Примечание: в настоящее время прокси не поддерживает отслеживание результатов. Поэтому выполненные операторы регистрируются, но не результаты и не то, успешно ли выполнен оператор или нет.

![Postgres Proxy](https://assets.kitploit.com/production/public/readmes/7140/153b5b3e85c492079f01f1ffda490a53df2be01cfd808553abc511eb90fc1731.png)
![Postgres Proxy](https://assets.kitploit.com/production/public/readmes/7140/2c886b3cb184b13bbee9120ca5f1cdd9f45dd7743c5cf7a01fe8d5f7474d507a.png)

#### Прокси — TLS

Kviklet завершает TLS-соединение с базой данных. Это означает, что по умолчанию любой трафик от прокси и к нему не шифруется.  
Если вы хотите, чтобы kviklet повторно шифровал трафик, вы можете передать Kviklet TLS-сертификат и ключ для прокси, задав следующие переменные окружения:```
PROXY_TLS_CERTIFICATE_SOURCE=env
PROXY_TLS_CERTIFICATE_CERT=your-certificate
PROXY_TLS_CERTIFICATE_KEY=your-key

В любом случае сертификат и ключ должны быть сохранены в [формате pem](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail).

## Вопросы? Вклад?

Если у вас есть вопросы, вы хотите оставить отзыв или вам нужна помощь с настройкой, присоединяйтесь к нашему [сообществу в Discord](https://discord.gg/7SmPJfeP6e). Вы также можете создать [issue на GitHub](https://github.com/kviklet/kviklet/issues) для сообщений об ошибках и запросов новых функций.

Если вы хотите внести свой вклад, не стесняйтесь форкать и создавать PR для небольших изменений. Если вы планируете более крупные функции, я буду признателен за предварительное обсуждение в issue на GitHub или в Discord.

Вы также можете связаться со мной по адресу [email protected].