</details>

### DBのセットアップ

Kvikletは、クエリ、接続、承認などに関するメタデータを保存するために、独自のPostgreSQLデータベース（または少なくともスキーマ）を必要とします。
公式イメージはこちらで入手できます：https://hub.docker.com/_/postgres、またはお好みのクラウドプロバイダーが提供するクラウドホスティング版をご利用ください。

kvikletコンテナを起動する際には、以下の3つの環境変数を適切に設定する必要があります。```
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のクライアントIDとシークレットは、以下のGoogleの手順に従って簡単に取得できます：
https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid

有効なリダイレクトURIには、以下を設定する必要があります：https://[kviklet_host]/api/login/oauth2/code/google
許可されたオリジンには、あなたがホストしているkvikletのURLを設定します。

これらの環境変数を設定すると、組織内の全員が「Googleでサインイン」ボタンを使ってログインできるようになります。ただし、デフォルトでは権限が付与されていないため、ユーザーが一度ログインした後にロールを割り当てる必要があります。

#### Keycloak

代わりにKeycloakを使用してSSOを設定したい場合は、以下の4つの環境変数を設定する必要があります：```
KVIKLET_IDENTITYPROVIDER_CLIENTID
KVIKLET_IDENTITYPROVIDER_CLIENTSECRET
KVIKLET_IDENTITYPROVIDER_TYPE=keycloak
KVIKLET_IDENTITYPROVIDER_ISSUERURI=http://[host]:[port]/realms/[realm]

Create a GitHub OAuth App at https://github.com/settings/developers and configure:

- Authorization callback URL: `https://[kviklet_host]/api/login/oauth2/code/github`
- Homepage URL: your hosted Kviklet URL

`KVIKLET_IDENTITYPROVIDER_GITHUB_ALLOWEDORGS` は **必須** です（Kviklet はこれがないと起動しません）。GitHub OAuth Apps は OAuth フローを完了できるユーザーを制限できないため、Kviklet は認証後に `/user/orgs` を呼び出し、許可リストに登録された組織の少なくとも 1 つのメンバーではないユーザーを拒否します（大文字小文字を区別せず、最初の 100 組織がチェックされます）。

組織のチェックでユーザーのメンバーシップを確認するには、ユーザーは OAuth 同意画面で各許可リスト登録組織の横にある **Grant**（または **Request**）をクリックする必要があります。組織で「Restrict third-party OAuth applications」が有効になっている場合、組織の所有者は事前に OAuth アプリを 1 回承認する必要があり、その後でメンバーのメンバーシップが表示されるようになります。

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 IDプロバイダのエンティティID
- `SAML_SSOSERVICELOCATION`: IDプロバイダのSSOサービスURL
- `SAML_VERIFICATIONCERTIFICATE`: SAML応答の検証に使用するX.509証明書（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 は Postgres および MySQL データベース接続に IAM Auth をサポートしています。新しい接続を作成する際は 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 は AWS の `DefaultCredentialsProvider` を使用して認証情報を取得し、接続用のトークンを生成します。つまり、通常の全ての場所（環境変数や関連付けられたインスタンスロール）が機能するはずです。正確な順序はこちら：https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/DefaultCredentialsProvider.html

さらに、Kviklet が引き受ける AWS ロール ARN を指定することもできます。これにより、その認証情報を使用して一時的な DB トークンを作成します。これは特に、Kviklet と同じ AWS アカウントにないデータベースに接続する場合に便利です。この機能を使用するには、IAM Auth 接続の作成または編集時に、指定されたフィールドにロール ARN を入力するだけです。フィールドを空のままにすると、デフォルトの認証情報プロバイダーが使用されます（ロール引き受けなし）。

トークン生成時に使用する AWS リージョンは、接続 URL から推測されるため、設定オプションはありません。

データベースの IAM Auth を設定する方法については、公式の AWS ドキュメントに従ってください：https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html
主な2つのポイントは次のとおりです：

- IAM 認証オプションと適切な権限を持つ DB ユーザーを作成する
- AWS エンティティがこのユーザーにトークンを生成できるようにする IAM ポリシーを作成する

### レビューゲート

デフォルトでは、Kviklet はシンプルなレビュー回数設定を許可しています。特定の接続に対して、承認リクエストが何件必要かを設定できます。

リクエストの承認ステータスは、各レビュアーの最新アクションに基づいて計算されます。レビュアーが承認した後、変更をリクエストした場合、変更リクエストのみがカウントされ、以前の承認は削除されます。リクエストを編集すると、常に以前のすべての承認がリセットされ、変更はレビューなしでは実行できなくなります。同様に、実行が失敗した場合（例：SQL 構文エラー）、承認がリセットされるため、新しいリクエストを作成しなくても修正して再承認できます。

また、接続ごとに **最大実行数** の制限を設定し、承認済みリクエストが何回実行できるかを制御できます。デフォルトは1です。0に設定すると無制限になります。失敗した実行はこの制限にカウントされません。

#### ロールベースのレビュー要件（エンタープライズ）

Kviklet エンタープライズライセンスを使用すると、特定のロールを持つユーザーからの承認を必要とするように個々の接続を設定できます。これにより、特定のデータベースを管理するチームの承認を必要としたり、重要な接続を DBA や管理承認の背後にゲートしたりすることができます。

**仕組み：**

各接続には **必要なレビュー総数**（`numTotalRequired`）があり、これは下限として機能します。つまり、ロールに関係なく必要な最小限の承認数です。これに加えて、特定のロールを持つユーザーからの承認数を指定する **ロール要件** を追加できます（例：「DBA から1件、セキュリティから1件」）。

リクエストが承認されるのは、**両方**の条件が満たされた場合のみです：
- 個別の承認の総数が `numTotalRequired` を満たしている
- 各ロール要件が個別に満たされている

ユーザーが複数のロールに属している場合、そのユーザーからの1回の承認は、一致するすべてのロール要件に対してカウントされます。ただし、総数に対しては1件の承認としてのみカウントされます。

**例：** 接続が合計3件の承認を必要とし、そのうち DBA から1件、セキュリティから1件が必要です。DBA とセキュリティの両方のロールを持つユーザーが承認した場合、これは両方のロール要件を満たしますが、必要な合計3件のうち1件としてのみカウントされます。さらに2件の承認（任意のユーザーから）が必要です。

エンタープライズライセンスが期限切れになった場合、既存のロールベースのレビュー要件は引き続き適用されますが、変更できなくなります。削除してシンプルなレビュー総数設定に戻すことのみ可能です。

### ロール

Kviklet にはデフォルト、管理者、開発者の3つのロールが用意されています。

- デフォルトロールは、すべての接続とリクエストへの読み取りアクセスを提供します。このロールは全ユーザーに割り当てられ、削除できません。ただし、権限は自由に変更できます。
- 管理者は、接続の作成と編集、ユーザーの追加と権限設定を行う権限を持ちます。
- 開発者は、リクエストの作成、承認、コメント、および実際のステートメントの実行を行うことができます。

ロールをカスタマイズして、特定の接続や DB 接続グループのみにアクセスを許可することもできます。これは、異なるデータベースを持つ異なるチームがいる場合に、アクセスをよりきめ細かく制御するのに便利です。

#### 新しいロールの作成

新しいロールの作成手順は次のとおりです。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)

デフォルト設定はほとんどのロールにとってあまり重要ではなく、ユーザーの Read と RoleView アクセスを許可してそのままにしておけば問題ありません。より重要なのは、接続に対する個別の権限を追加することです。ここでは、まずセレクターを追加して特定の接続を選択します。これは特定の ID にするか、ワイルドカード `*` を使用して複数の接続にマッチさせることができます。例えば、すべての開発データベース（もしそれらのアクセスも Kviklet で管理している場合）にアクセスできるロールが必要な場合、`dev-*` のようなセレクターを使用し、接続の ID が正しく設定されていることを確認してください。

もちろん、組織内の異なるチーム向けに独自のルールを作成することもできます。

### ロール同期（エンタープライズ）

アイデンティティプロバイダーのグループからユーザーロールを自動的に同期します。この機能にはエンタープライズライセンスが必要です。

**設定** は 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 プロバイダーを設定して、ID トークンに `groups` クレームを含めます：

- **Keycloak**:

  Keycloak はデフォルトではグループをトークンに含めないため、クライアントにマッパーを追加する必要があります。

  1. 左メニューの **Clients** に移動
  2. Kviklet クライアントを選択
  3. **Client scopes** タブに移動
  4. 専用スコープ（例：`kviklet-dedicated`）をクリック
  5. **Mappers** タブに移動
  6. **Add mapper** → **By configuration** をクリック
  7. **Group Membership** を選択
  8. マッパーを設定：

  | 設定 | 値 |
  |---------|-------|
  | 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」は、Kviklet の Role Sync 設定で構成した「Groups Attribute」（デフォルト：`groups`）と一致する必要があります。

- **その他の OIDC プロバイダー**：ID トークンにユーザーのグループメンバーシップを含めるグループマッパー/クレームを追加します。これは通常、プロバイダーの管理 UI で行います。

  問題が発生した場合は、遠慮なく issue を作成してください。まだすべての OIDC プロバイダーを試したわけではなく、実装に若干の違いがあり、Kviklet 側の更新が必要になる可能性があります。

#### LDAP 設定

LDAP ロール同期は `memberOf` 属性を使用します：

1. LDAP サーバーで `memberOf` オーバーレイが有効になっていることを確認します
2. Kviklet の **Groups Attribute** を `memberOf` に設定します
3. グループ名は、ユーザー属性の `memberOf` 属性から抽出されます

#### SAML 設定

SAML IdP を設定して、アサーションにグループを含めます：

1. ユーザーのグループメンバーシップをマッピングする属性ステートメントを追加します
2. Kviklet の **Groups Attribute** を SAML 属性名に一致するように設定します
3. グループ名は、ユーザー属性の SAML 属性から抽出されます

### 通知

Kviklet を設定して、Slack または Teams のチャンネルに通知を送信できます。これは、新しいリクエストがレビューを必要とする場合にチームに通知するのに便利です。設定は Settings → General → Notification Settings で行えます。

#### Slack

Slack 通知を設定するには、Slack アプリを作成し、Webhook を有効にする必要があります。手順はこちら：https://api.slack.com/messaging/webhooks

#### Teams

Teams 通知は Power Automate **ワークフロー** の Webhook を使用します。Kviklet は Adaptive Card を送信し、Webhook テンプレートがチャンネルに投稿します。

**推奨：ワークフローテンプレートの使用**

1. Teams で、通知を表示するチャンネルを開き、チャンネル名の横にある **...** をクリックし、**ワークフロー** を選択します（または **Workflows** アプリを追加します）。
2. **「Send webhook alerts to a channel」** テンプレートを検索して作成します。
3. プロンプトが表示されたらサインインし、対象のチームとチャンネルを選択してワークフローを作成します。
4. トリガーステップを開き、生成された **HTTP POST URL** をコピーします。
5. Kviklet の Settings → General → Notification Settings に URL を貼り付け、保存をクリックします。

**代替：ワークフローを手動で作成する**

自分でフローを構築したい場合（またはテンプレートが利用できない場合）：

1. チャンネルの **...** → **ワークフロー** → トリガー **「When a Teams webhook request is received」** でフローを作成します。
2. アクション **Microsoft Teams → 「Post card in a chat or channel」** を追加します。
3. アクションの **Adaptive Card** フィールドを式 `string(triggerBody())` に設定し、Kviklet が送信したカードを投稿するようにします。
4. 対象のチームとチャンネルを選択し、**保存** をクリックしてから、トリガーステップから **HTTP POST URL** をコピーします。

現在、以下の通知があります：

- 承認が必要な新しいリクエスト
- リクエストへの新しい承認

#### Base URL 設定

Kviklet をリバースプロキシや Kubernetes Ingress の背後で実行する場合、通知リンクがパブリックドメインではなく内部 IP アドレスを使用する可能性があります。Kviklet は受信リクエストを調べて正しい URL を追跡しようとしますが、一部のリバースプロキシは Forwarded ヘッダーを正しく設定しません。これを修正するには、Base URL を明示的に設定します：```
KVIKLET_BASE_URL=https://kviklet.example.com

## 暗号化

認証情報がデータベースに平文で保存されるのを避けたい場合は、Kvikletのpostgresデータベース自体でデータベース暗号化を有効にすることを推奨します。ほとんどのホスティングプロバイダーでは、これはチェックボックスをクリックするだけで簡単に設定できます。
それでも、Kvikletデータベースが何らかの形で侵害された場合、これは大きなセキュリティリスクとなります。なぜなら、このデータベースには、潜在的にすべての本番データストアのデータベース認証情報が含まれているからです。そのため、保存時の認証情報の暗号化を有効にすることができます。

これを行うには、単に2つの環境変数を設定してください。```
ENCRYPTION_ENABLED=true
ENCRYPTION_KEY_CURRENT=some-secret

Kvikletは起動時にすべての接続を再暗号化するため、その後、以前のキーを削除してコンテナを再起動できます。

## APIキー

Kvikletは、システムへのプログラムによるアクセスのためにAPIキーをサポートしています。これはエンタープライズ専用機能であり、有効なライセンスが必要です。APIキーは、設定 -> APIキー セクションで作成できます。

![API Keys](https://assets.kitploit.com/production/public/readmes/7140/a11d80c93ef29ead3b8b3bf3b435a782208d10bd2978d80cd2c4edc1fc7bc506.png)
![API Keys](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