</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 run может выглядеть так:```
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 и секрет можно легко получить, следуя инструкциям Google здесь:
https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid

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

После установки этих переменных окружения каждый в вашей организации сможет войти, используя кнопку входа через 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 на https://github.com/settings/developers и настройте:

- URL обратного вызова авторизации: `https://[kviklet_host]/api/login/oauth2/code/github`
- URL домашней страницы: URL вашего размещенного Kviklet

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

Чтобы проверка организации видела членство пользователя, пользователь должен нажать **Grant** (или **Request**) рядом с каждой разрешенной организацией на экране согласия OAuth. Если в организации включена опция «Ограничить сторонние приложения OAuth», владелец организации также должен один раз одобрить приложение 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 службы единого входа вашего поставщика удостоверений
- `SAML_VERIFICATIONCERTIFICATE`: Сертификат X.509, используемый для проверки ответов SAML (включите строки BEGIN/END CERTIFICATE)

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

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

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

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

![Добавить подключение](https://assets.kitploit.com/production/public/readmes/7140/3ded2a0b23e5d2f02feb21a854263c91dedea25a789fb75ab8342384c4e39b52.png)
![Добавить подключение](https://assets.kitploit.com/production/public/readmes/7140/585238c9eddad8ed4e2440096ce0616445a6696e1042f58676a1d0b038edde7f.png)

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

#### AWS IAM AUTH

Kviklet поддерживает использование IAM Auth для подключений к базам данных Postgres и MySQL. Для этого выберите 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 генерировать токены для этого пользователя.

### Шлюзы рецензирования

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

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

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

#### Ролевые требования к рецензированию (Enterprise)

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

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

Для каждого подключения задаётся **общее количество требуемых рецензий** (`numTotalRequired`), которое действует как нижняя граница — минимальное количество различных одобрений, необходимое независимо от ролей. Поверх этого можно добавить **ролевые требования**, которые указывают, сколько одобрений должно поступать от пользователей с определённой ролью (например, "1 от администратора БД, 1 от отдела безопасности").

Запрос считается одобренным только тогда, когда **оба** условия выполнены:
- Общее количество различных одобрений достигает `numTotalRequired`
- Каждое ролевое требование удовлетворено индивидуально

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

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

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

### Роли

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

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

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

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

Создание новой роли происходит следующим образом. Перейдите в Настройки -> Роли -> Добавить роль.

![Добавить роль](https://assets.kitploit.com/production/public/readmes/7140/a91b79287c0b3130b83bdde1c059f49b89c5d43a1c0deae33b211ea427956f8e.png)
![Добавить роль](https://assets.kitploit.com/production/public/readmes/7140/c535ac152759bb21bea04a0968ce43fa7bf946c7699feca23c71f9eaba41ceaf.png)

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

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

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

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

**Настройка** производится в меню Настройки > Синхронизация ролей:

- **Включить синхронизацию ролей**: Включить/выключить синхронизацию
- **Режим синхронизации**:
  - **Полная синхронизация** — Роли пользователей точно соответствуют сопоставлениям групп IdP (плюс роль по умолчанию)
  - **Аддитивная** — Группы IdP добавляют роли, но не удаляют существующие
  - **Только при первом входе** — Роли синхронизируются только при первом входе, ручные изменения сохраняются в дальнейшем
- **Атрибут групп**: Атрибут IdP, содержащий членство в группах (по умолчанию: `groups`)
- **Сопоставления ролей**: Сопоставьте имена групп IdP (например, `engineering`) с ролями Kviklet

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

Настройте своего OIDC-провайдера на включение утверждения `groups` в ID-токен:

- **Keycloak**:

  Keycloak по умолчанию не включает группы в токены, поэтому вам нужно добавить маппер для клиента.

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

  | Параметр | Значение |
  |----------|----------|
  | Name | `groups` |
  | Token Claim Name | `groups` |
  | Full group path | **ВЫКЛ** |
  | Add to ID token | **ВКЛ** |
  | Add to access token | **ВКЛ** |
  | Add to userinfo | **ВКЛ** |

  9. Нажмите **Save**

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

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

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

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

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

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

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

Настройте вашего SAML-IdP на включение групп в утверждение:

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

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

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

#### Slack

Для настройки уведомлений Slack вам нужно создать приложение Slack и включить для него вебхуки. Следуйте инструкциям здесь: https://api.slack.com/messaging/webhooks

#### Teams

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

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

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

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

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

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

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

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

#### Настройка базового URL

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

## Шифрование

Если вы не хотите, чтобы учетные данные хранились в открытом виде в базе данных, рекомендуется включить шифрование базы данных на самой БД Kviklet Postgres. Для большинства хостинг-провайдеров это просто флажок для установки. Тем не менее, если база данных Kviklet будет каким-либо образом скомпрометирована, это представляет огромный риск для безопасности. Поскольку она содержит учетные данные базы данных для потенциально всех ваших рабочих хранилищ данных. Поэтому вы можете включить шифрование учетных данных в состоянии покоя.

Для этого просто установите две переменные окружения.```
ENCRYPTION_ENABLED=true
ENCRYPTION_KEY_CURRENT=some-secret

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

## Ключи API

Kviklet поддерживает ключи API для программного доступа к системе. Это функция, доступная только в корпоративной версии, и требует действующей лицензии. Вы можете создавать ключи API в разделе Настройки -> Ключи API.

![Ключи API](https://assets.kitploit.com/production/public/readmes/7140/a11d80c93ef29ead3b8b3bf3b435a782208d10bd2978d80cd2c4edc1fc7bc506.png)
![Ключи API](https://assets.kitploit.com/production/public/readmes/7140/21948bc6a43dbdd88be563befbfc9052a1dd4a99735817c2ff99680c9c32cbd0.png)

Используйте это следующим образом:```bash
curl --location '[kviklet_host]/api/connections/' \
--header 'Authorization: Bearer your-api-key'

альтернативно вы можете использовать файлы:```
PROXY_TLS_CERTIFICATE_SOURCE=file
PROXY_TLS_CERTIFICATE_CERT_FILE=path/to/cert.pem
PROXY_TLS_CERTIFICATE_KEY_FILE=path/to/key.pem