</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 클라이언트 ID와 시크릿은 다음 Google 안내를 따라 쉽게 얻을 수 있습니다:
https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid

유효한 리디렉션 URI의 경우 다음을 구성해야 합니다: https://[kviklet_host]/api/login/oauth2/code/google
허용된 출처(Allowed Origins)의 경우, 호스팅된 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]

GitHub OAuth 앱을 https://github.com/settings/developers 에서 생성하고 다음을 구성하세요:

- Authorization callback URL: `https://[kviklet_host]/api/login/oauth2/code/github`
- Homepage URL: 호스팅된 Kviklet URL

`KVIKLET_IDENTITYPROVIDER_GITHUB_ALLOWEDORGS`는 **필수**입니다 (Kviklet은 이 값 없이 시작되지 않습니다). GitHub OAuth 앱은 OAuth 흐름을 완료할 수 있는 사용자를 제한할 수 없으므로, Kviklet은 인증 후 `/user/orgs`를 호출하여 허용 목록에 있는 org 중 하나의 멤버가 아닌 사용자를 거부합니다 (대소문자 구분 없이, 처음 100개 org 확인).

조직 확인을 통해 사용자의 멤버십을 확인하려면, 사용자는 OAuth 동의 화면에서 허용 목록에 있는 각 org 옆에 있는 **Grant** (또는 **Request**)를 클릭해야 합니다. org에서 "Restrict third-party OAuth applications"이 활성화된 경우, org 소유자가 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`이 됩니다. 문제가 발생하면 이슈를 생성해 주세요. 아직 모든 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`: SAML 인증을 활성화하려면 `true`로 설정하십시오.
- `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을 시작한 후 먼저 데이터베이스 연결을 구성해야 합니다. 설정 -> 데이터베이스 -> 연결 추가로 이동합니다.

![연결 추가](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은 Postgres 및 MySQL 데이터베이스 연결에 대해 IAM 인증 사용을 지원합니다. 새 연결을 만들 때 IAM 인증을 선택하세요.

![IAM 인증](https://assets.kitploit.com/production/public/readmes/7140/14ed42bd639eb9b0ba81b22850e277703f2da9495dd101f68066f95fc51f291c.png)
![IAM 인증](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 인증 연결을 만들거나 편집할 때 지정된 필드에 역할 ARN을 입력하기만 하면 됩니다. 필드를 비워 두면 기본 자격 증명 공급자가 사용됩니다(역할 맡기 없음).

토큰 생성 중 사용할 AWS 리전은 연결 URL에서 자동으로 유추되므로 설정 옵션이 없습니다.

데이터베이스에 대해 IAM 인증을 설정하는 방법은 공식 AWS 문서를 참조하세요: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html
주요 두 가지 사항은 다음과 같습니다:

- IAM 인증 옵션과 올바른 권한이 있는 DB 사용자 생성
- AWS 엔터티가 이 사용자에 대해 토큰을 생성할 수 있도록 하는 IAM 정책 생성

### 검토 게이트

기본적으로 Kviklet은 간단한 검토 횟수 구성을 허용합니다. 특정 연결에서 승인 요청이 실행되기 전에 필요한 승인 수를 구성할 수 있습니다.

요청의 승인 상태는 각 검토자의 최신 작업을 기준으로 계산됩니다. 검토자가 승인한 후 변경을 요청하면 요청 변경만 계산되며, 이전 승인은 제거됩니다. 요청을 편집하면 항상 모든 이전 승인이 재설정되어 변경 사항이 검토 없이 실행될 수 없도록 합니다. 마찬가지로 실행이 실패하면(예: SQL 구문 오류로 인해) 승인이 재설정되어 새 요청을 만들 필요 없이 요청을 수정하고 재승인할 수 있습니다.

또한 연결별로 **최대 실행 횟수** 제한을 구성하여 승인된 단일 요청을 실행할 수 있는 횟수를 제어할 수 있습니다. 기본값은 1입니다. 이 값을 0으로 설정하면 무제한 실행이 가능합니다. 실패한 실행은 이 제한에 포함되지 않습니다.

#### 역할 기반 검토 요구 사항 (Enterprise)

Kviklet Enterprise 라이선스를 사용하면 개별 연결에 대해 특정 역할을 가진 사용자의 승인이 필요하도록 구성할 수 있습니다. 이를 통해 예를 들어 특정 데이터베이스를 유지 관리하는 팀의 승인을 요구하거나 민감한 연결을 DBA 또는 관리자 승인 뒤에 둘 수 있습니다.

**작동 방식:**

각 연결에는 **필요한 총 검토 수**(`numTotalRequired`)가 있으며, 이는 최소 요구 사항 역할을 합니다. 이 위에 역할 요구 사항을 추가하여 특정 역할을 가진 사용자로부터 필요한 승인 수를 지정할 수 있습니다(예: "DBA에서 1명, 보안에서 1명").

요청은 **다음 두 조건이 모두** 충족될 때만 승인됩니다:
- 고유한 승인 총 수가 `numTotalRequired`를 충족합니다.
- 각 역할 요구 사항이 개별적으로 충족됩니다.

사용자가 여러 역할에 속하는 경우 해당 사용자의 단일 승인은 일치하는 모든 역할 요구 사항에 적용됩니다. 그러나 총 승인 수에는 여전히 1회로만 계산됩니다.

**예시:** 연결에 3개의 총 승인이 필요하며, 그중 DBA 1명과 보안 1명이 포함되어야 합니다. DBA와 보안 역할을 모두 가진 사용자가 승인하면 두 역할 요구 사항이 모두 충족되지만 필요한 총 3개 승인 중 1개로만 계산됩니다. 다른 사용자의 승인 2개가 여전히 필요합니다.

엔터프라이즈 라이선스가 만료되면 기존 역할 기반 검토 요구 사항은 계속 적용되지만 더 이상 수정할 수 없습니다. 간단한 총 검토 구성으로 되돌리려면 제거만 가능합니다.

### 역할

Kviklet은 기본, 관리자 및 개발자라는 3개의 역할과 함께 제공됩니다.

- 기본 역할은 모든 연결 및 요청에 대한 읽기 액세스 권한을 제공합니다. 이 역할은 모든 사용자에게 할당되며 제거할 수 없습니다. 그러나 이 역할의 권한은 자유롭게 변경할 수 있습니다.
- 관리자는 연결을 만들고 편집할 수 있는 권한과 새 사용자를 추가하고 권한을 설정할 수 있는 권한이 있습니다.
- 개발자는 요청을 만들고 승인 및 댓글을 달 수 있으며 실제 명령문을 실행할 수 있습니다.

역할을 사용자 정의하고 예를 들어 특정 연결 또는 DB 연결 그룹에만 액세스 권한을 부여할 수 있습니다.
이는 예를 들어 다른 팀이 다른 데이터베이스를 가지고 있고 액세스를 더 세밀하게 제어하려는 경우 유용합니다.

#### 새 역할 만들기

새 역할을 만드는 방법은 다음과 같습니다. 설정 -> 역할 -> 역할 추가로 이동합니다.

![역할 추가](https://assets.kitploit.com/production/public/readmes/7140/a91b79287c0b3130b83bdde1c059f49b89c5d43a1c0deae33b211ea427956f8e.png)
![역할 추가](https://assets.kitploit.com/production/public/readmes/7140/c535ac152759bb21bea04a0968ce43fa7bf946c7699feca23c71f9eaba41ceaf.png)

대부분의 역할에 대해 기본 설정은 그다지 중요하지 않으며 사용자에게 읽기 및 역할 보기 액세스 권한을 부여하고 그대로 두면 됩니다.
더 흥미로운 점은 연결에 대한 개별 권한을 추가하는 것입니다. 여기서 먼저 선택기를 추가하여 특정 연결을 선택합니다. 이는 특정 ID이거나 와일드카드 `*`를 사용하여 여러 연결과 일치시킬 수 있습니다. 예를 들어 모든 개발 데이터베이스에 액세스할 수 있는 역할을 원하는 경우(kviklet으로 해당 데이터베이스에 대한 액세스를 관리하는 경우) `dev-*`와 같은 선택기를 사용하고 연결 ID가 올바르게 설정되어 있는지 확인하세요.

물론 조직 내에서 다른 팀에 사용하는 시스템을 직접 만들 수도 있습니다.

### 역할 동기화 (Enterprise)

ID 공급자 그룹에서 사용자 역할을 자동으로 동기화합니다. 이 기능은 엔터프라이즈 라이선스가 필요합니다.

**구성**은 설정 > 역할 동기화에서 수행됩니다:

- **역할 동기화 사용**: 동기화 켜기/끄기
- **동기화 모드**:
  - **전체 동기화** - 사용자 역할이 IdP 그룹 매핑과 정확히 일치합니다(기본 역할 추가).
  - **추가적** - IdP 그룹이 역할을 추가하지만 기존 역할은 제거하지 않습니다.
  - **첫 로그인만** - 역할은 첫 로그인 시에만 동기화되며 이후 수동 변경 사항은 유지됩니다.
- **그룹 속성**: 그룹 구성원을 포함하는 IdP 속성(기본값: `groups`)
- **역할 매핑**: IdP 그룹 이름(예: `engineering`)을 Kviklet 역할에 매핑합니다.

#### OIDC 설정

ID 토큰에 `groups` 클레임을 포함하도록 OIDC 공급자를 구성합니다:

- **Keycloak**:

  Keycloak은 기본적으로 토큰에 그룹을 포함하지 않으므로 클라이언트에 매퍼를 추가해야 합니다.

  1. 왼쪽 메뉴에서 **클라이언트**로 이동합니다.
  2. Kviklet 클라이언트를 선택합니다.
  3. **클라이언트 범위** 탭으로 이동합니다.
  4. 전용 범위(예: `kviklet-dedicated`)를 클릭합니다.
  5. **매퍼** 탭으로 이동합니다.
  6. **매퍼 추가** → **구성별**을 클릭합니다.
  7. **그룹 구성원**을 선택합니다.
  8. 매퍼를 구성합니다:

  | 설정 | 값 |
  |---------|-------|
  | 이름 | `groups` |
  | 토큰 클레임 이름 | `groups` |
  | 전체 그룹 경로 | **끄기** |
  | ID 토큰에 추가 | **켜기** |
  | 액세스 토큰에 추가 | **켜기** |
  | 사용자 정보에 추가 | **켜기** |

  9. **저장**을 클릭합니다.

  > **중요:** "토큰 클레임 이름"은 Kviklet의 역할 동기화 설정에서 구성된 "그룹 속성"(기본값: `groups`)과 일치해야 합니다.

- **기타 OIDC 공급자**: ID 토큰에 사용자의 그룹 구성원을 포함하는 그룹 매퍼/클레임을 추가합니다. 이는 일반적으로 공급자의 관리 UI에서 수행됩니다.

  문제가 발생하면 이슈를 생성해 주세요. 아직 모든 OIDC 공급자를 테스트해 보지는 않았으며, Kviklet 측에서 업데이트가 필요한 구현상의 약간의 차이가 있을 수 있습니다.

#### LDAP 설정

LDAP 역할 동기화는 `memberOf` 속성을 사용합니다:

1. LDAP 서버에 `memberOf` 오버레이가 활성화되어 있는지 확인합니다.
2. Kviklet에서 **그룹 속성**을 `memberOf`로 설정합니다.
3. 그러면 사용자 속성의 `memberOf` 속성에서 그룹 이름이 추출됩니다.

#### SAML 설정

SAML IdP가 어설션에 그룹을 포함하도록 구성합니다:

1. 사용자 그룹 구성원을 매핑하는 속성 문을 추가합니다.
2. Kviklet에서 **그룹 속성**을 SAML 속성 이름과 일치하도록 설정합니다.
3. 그러면 사용자 속성의 SAML 속성에서 그룹 이름이 추출됩니다.

### 알림

Kviklet이 Slack 또는 Teams 채널에 알림을 보내도록 구성할 수 있습니다. 이는 검토가 필요한 새 요청에 대해 팀에 알리는 데 유용합니다. 설정 -> 일반 -> 알림 설정에서 구성할 수 있습니다.

#### Slack

Slack 알림을 구성하려면 Slack 앱을 만들고 웹훅을 활성화해야 합니다. 여기 지침을 따르세요: https://api.slack.com/messaging/webhooks

#### Teams

Teams 알림은 Power Automate **워크플로** 웹훅을 사용합니다. Kviklet은 적응형 카드를 보내고, 웹훅 템플릿이 이를 채널에 게시합니다.

**권장: 워크플로 템플릿 사용**

1. Teams에서 알림을 받을 채널을 열고 채널 이름 옆의 **...**을 클릭한 다음 **워크플로**를 선택합니다(또는 **워크플로** 앱을 추가).
2. **"채널에 웹훅 알림 보내기"** 템플릿을 검색하여 만듭니다.
3. 메시지가 나타나면 로그인한 다음 대상 팀과 채널을 선택하고 워크플로를 만듭니다.
4. 트리거 단계를 열고 생성된 **HTTP POST URL**을 복사합니다.
5. URL을 Kviklet의 설정 -> 일반 -> 알림 설정에 붙여넣고 저장을 클릭합니다.

**대안: 워크플로 수동 구축**

템플릿을 사용할 수 없거나 직접 흐름을 구축하려는 경우:

1. 채널 **...** -> **워크플로** -> 트리거 **"Teams 웹훅 요청이 수신되면"**으로 흐름을 만듭니다.
2. 작업 **Microsoft Teams -> "채팅 또는 채널에 카드 게시"**를 추가합니다.
3. 작업의 **적응형 카드** 필드를 표현식 `string(triggerBody())`로 설정하여 Kviklet이 보낸 카드를 게시하도록 합니다.
4. 대상 팀과 채널을 선택하고 **저장**을 클릭한 다음 트리거 단계에서 **HTTP POST URL**을 복사합니다.

현재 다음과 같은 알림이 있습니다:

- 승인이 필요한 새 요청
- 요청에 대한 새 승인

#### 기본 URL 구성

Kviklet을 리버스 프록시 또는 Kubernetes 인그레스 뒤에서 실행할 때 알림 링크가 공개 도메인 대신 내부 IP 주소를 사용할 수 있습니다. Kviklet은 들어오는 요청을 확인하여 올바른 URL을 추적하려고 하지만 일부 리버스 프록시는 전달된 헤더를 올바르게 설정하지 않습니다. 이를 수정하려면 기본 URL을 명시적으로 설정하세요:```
KVIKLET_BASE_URL=https://kviklet.example.com

## 암호화

자격 증명이 DB에 일반 텍스트로 저장되는 것을 원하지 않는다면, Kviklet postgres DB 자체에서 데이터베이스 암호화를 활성화하는 것이 좋습니다. 대부분의 호스팅 제공업체에서는 간단한 체크박스를 선택하면 됩니다.
그럼에도 불구하고, Kviklet 데이터베이스가 어떻게든 유출된다면 이는 큰 보안 위험입니다. 잠재적으로 모든 프로덕션 데이터 저장소의 데이터베이스 자격 증명을 포함하고 있기 때문입니다. 따라서 저장 시 자격 증명 암호화를 활성화할 수 있습니다.

이를 위해 간단히 두 개의 환경 변수를 설정하십시오.```
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)

다음과 같이 사용합니다:

```sql
SELECT * FROM users WHERE id = ?;
``````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