</details>

### Configurazione del database

Kviklet necessita di un proprio database postgres (o almeno uno schema) per salvare i metadati su query, connessioni, approvazioni, ecc.
Puoi trovare la loro immagine ufficiale qui: https://hub.docker.com/_/postgres, o utilizzare una versione ospitata nel cloud dal tuo fornitore di servizi cloud preferito.

Quando avvii il container kviklet, dovrai quindi impostare queste tre variabili d'ambiente di conseguenza:```
SPRING_DATASOURCE_PASSWORD = password
SPRING_DATASOURCE_USERNAME = username
SPRING_DATASOURCE_URL = jdbc:postgresql://[host]:[port]/[database]?currentSchema=[schema]

Pubbliciamo i nostri container su GitHub Packages per ora, quindi con tutto ciò impostato puoi eseguire `ghcr.io/kviklet/kviklet:main` non dimenticare di mappare la porta `8080` che è la porta predefinita su cui Kviklet si avvia.

Un esempio di docker run potrebbe essere:```
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

The google client id and secret you can easily get by following google instructions here:
https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid

For valid redirect URIs, you should configure: https://[kviklet_host]/api/login/oauth2/code/google
For Allowed Origins, simply your hosted kviklet url.

After setting those environment variables everyone in your organization can login with the sign in with google button. But they wont have any permissions by default, you will have to assign them a role after they log in once.

#### Keycloak

If you want to setup SSO with Keycloak instead you need to set these 4 environment variables:```
KVIKLET_IDENTITYPROVIDER_CLIENTID
KVIKLET_IDENTITYPROVIDER_CLIENTSECRET
KVIKLET_IDENTITYPROVIDER_TYPE=keycloak
KVIKLET_IDENTITYPROVIDER_ISSUERURI=http://[host]:[port]/realms/[realm]

Crea un'app OAuth GitHub su https://github.com/settings/developers e configurala:

- URL di callback di autorizzazione: `https://[kviklet_host]/api/login/oauth2/code/github`
- URL della homepage: l'URL della tua istanza Kviklet

`KVIKLET_IDENTITYPROVIDER_GITHUB_ALLOWEDORGS` è **richiesto** (Kviklet si rifiuta di avviarsi senza di esso). Le app OAuth GitHub non possono limitare chi completa il flusso OAuth, quindi Kviklet chiama `/user/orgs` dopo l'autenticazione e rifiuta gli utenti che non sono membri di almeno un'org consentita (senza distinzione tra maiuscole e minuscole, vengono controllate le prime 100 org).

Affinché il controllo dell'org possa vedere l'appartenenza di un utente, l'utente deve fare clic su **Grant** (o **Request**) accanto a ciascuna org consentita nella schermata di consenso OAuth. Se l'org ha attivato "Restrict third-party OAuth applications", anche un proprietario dell'org deve approvare l'app OAuth una volta prima che l'appartenenza di qualsiasi membro diventi visibile.

Kviklet richiede gli ambiti `read:user`, `user:email` e `read:org`. Le email vengono sempre lette da `/user/emails` e viene accettata solo una voce `primary && verified`, quindi gli utenti con indirizzi email privati riescono comunque ad accedere.

#### Altri provider OIDC

Altri provider conformi OIDC (GitLab, Auth0, Okta, ecc.) dovrebbero funzionare in modo simile a Keycloak. Nota che l'`URI di reindirizzamento` cambierà a seconda del tipo scelto, quindi se scegli `gitlab` sarà `https://[kviklet_host]/api/login/oauth2/code/gitlab`.
Se incontri problemi, sentiti libero di creare un issue. Non abbiamo ancora provato ogni singolo provider OIDC là fuori e potrebbero esserci leggere differenze nell'implementazione che potrebbero richiedere aggiornamenti da parte di Kviklet.

### LDAP

Kviklet supporta l'autenticazione LDAP. Per abilitare e configurare LDAP, puoi sovrascrivere le seguenti variabili d'ambiente:```
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

Dettagli di configurazione:

- `SAML_ENABLED`: Imposta su `true` per abilitare l'autenticazione SAML
- `SAML_ENTITYID`: L'ID dell'entità del tuo provider di identità SAML
- `SAML_SSOSERVICELOCATION`: L'URL del servizio SSO del tuo provider di identità
- `SAML_VERIFICATIONCERTIFICATE`: Il certificato X.509 utilizzato per verificare le risposte SAML (includere le righe BEGIN/END CERTIFICATE)

Puoi opzionalmente personalizzare i mapping degli attributi SAML:```
SAML_USERATTRIBUTES_EMAILATTRIBUTE=email
SAML_USERATTRIBUTES_NAMEATTRIBUTE=name
SAML_USERATTRIBUTES_IDATTRIBUTE=nameID

## Configurazione

### Connessioni

Dopo aver avviato Kviklet, devi prima configurare una connessione al database. Vai su Impostazioni -> Database -> Aggiungi connessione.

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

Qui puoi configurare i requisiti di revisione e i limiti di esecuzione per ogni connessione. Vedi [Review Gates](#review-gates) per i dettagli.

#### AWS IAM AUTH

Kviklet supporta l'autenticazione IAM per le connessioni ai database Postgres e MySQL. Per utilizzarla, scegli IAM Auth quando crei una nuova connessione.

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

Questa opzione rimuove la possibilità di impostare una password e utilizza invece le credenziali AWS per connettersi al database.

Kviklet utilizza `DefaultCredentialsProvider` di AWS per trovare le credenziali e generare il token per la connessione. Questo significa che tutti i luoghi tipici funzionano (variabili d'ambiente o ruoli di istanza associati). L'ordine esatto è documentato qui: https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/DefaultCredentialsProvider.html

Inoltre, puoi fornire un ARN del ruolo AWS che Kviklet assumerà e utilizzerà le credenziali di quel ruolo per creare il token DB temporaneo. Ciò è particolarmente utile per connettersi a database che non si trovano nello stesso account AWS di Kviklet. Per utilizzare questa funzionalità, inserisci l'ARN del ruolo nel campo designato quando crei o modifichi una connessione IAM Auth. Lasciando il campo vuoto, verrà utilizzato il provider di credenziali predefinito (senza assunzione di ruolo).

La regione AWS da utilizzare durante la generazione del token viene dedotta dall'URL di connessione, quindi non ci sono opzioni per impostarla.

Per imparare come configurare IAM Auth per il tuo database, segui la documentazione ufficiale AWS: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html
I due punti principali sono:

- Creare un utente DB con l'opzione di autenticazione IAM e le autorizzazioni corrette
- Creare una policy IAM che permetta all'entità AWS di generare token per questo utente

### Review Gates

Per impostazione predefinita, Kviklet consente una semplice configurazione del conteggio delle revisioni. Puoi configurare quante approvazioni sono necessarie per una richiesta su una specifica connessione prima che possa essere eseguita.

Lo stato di approvazione di una richiesta viene calcolato in base all'ultima azione di ciascun revisore. Se un revisore approva e successivamente richiede modifiche, conta solo la richiesta di modifica — la sua approvazione precedente viene rimossa. La modifica di una richiesta reimposta sempre tutte le approvazioni precedenti, assicurando che nessuna modifica possa essere eseguita senza essere prima revisionata. Allo stesso modo, se un'esecuzione fallisce (ad esempio a causa di un errore di sintassi SQL), le approvazioni vengono reimpostate in modo che la richiesta possa essere corretta e riapprovata senza doverne creare una nuova.

Puoi anche configurare un limite di **esecuzioni massime** per connessione per controllare quante volte una richiesta approvata può essere eseguita. Il valore predefinito è 1. Impostandolo a 0 si consentono esecuzioni illimitate. Le esecuzioni fallite non contano ai fini di questo limite.

#### Requisiti di revisione basati sui ruoli (Enterprise)

Con una licenza Enterprise di Kviklet puoi configurare singole connessioni per richiedere approvazioni da utenti con ruoli specifici. Questo ti permette, ad esempio, di richiedere l'approvazione del team che gestisce un determinato database o di vincolare connessioni sensibili all'approvazione di DBA o dirigenti.

**Come funziona:**

Ogni connessione ha un numero totale di revisioni richieste (`numTotalRequired`) che funge da minimo — il numero minimo di approvazioni distinte necessarie indipendentemente dai ruoli. In aggiunta, puoi aggiungere **requisiti di ruolo** che specificano quante approvazioni devono provenire da utenti con un ruolo particolare (ad esempio, "1 da DBA, 1 da Sicurezza").

Una richiesta è approvata solo quando **entrambe** le condizioni sono soddisfatte:
- Il numero totale di approvazioni distinte raggiunge `numTotalRequired`
- Ogni requisito di ruolo è soddisfatto individualmente

Se un utente appartiene a più ruoli, una singola approvazione da quell'utente conta per tutti i requisiti di ruolo corrispondenti. Tuttavia, conta comunque come una sola approvazione verso il conteggio totale.

**Esempio:** Una connessione richiede 3 approvazioni totali, inclusa 1 da un DBA e 1 dalla Sicurezza. Un utente che ha entrambi i ruoli DBA e Sicurezza approva — questo soddisfa entrambi i requisiti di ruolo ma conta solo come 1 delle 3 approvazioni totali necessarie. Sono ancora necessarie altre due approvazioni da qualsiasi utente.

Se la tua licenza enterprise scade, i requisiti di revisione basati sui ruoli esistenti rimangono in vigore ma non possono più essere modificati. Puoi solo rimuoverli per tornare alla semplice configurazione del conteggio totale delle revisioni.

### Ruoli

Kviklet include 3 ruoli: Predefinito, Amministratori e Sviluppatori.

- Il ruolo Predefinito fornisce accesso in lettura a tutte le connessioni e alle Richieste. Questo ruolo è assegnato a ogni utente e non può essere rimosso. Puoi comunque modificare i permessi di questo ruolo come preferisci.
- Gli Amministratori hanno il permesso di creare e modificare connessioni, nonché di aggiungere nuovi Utenti e impostare i loro permessi.
- Gli Sviluppatori possono creare Richieste, approvarle, commentarle e, naturalmente, eseguire le istruzioni effettive.

Puoi personalizzare i Ruoli e, ad esempio, dare a un ruolo l'accesso solo a una connessione specifica o a un gruppo di connessioni DB.
Questo è utile, ad esempio, se hai team diversi con database differenti e desideri controllare l'accesso in modo più granulare.

#### Creazione di un nuovo Ruolo

La creazione di un nuovo ruolo funziona come segue. Vai su Impostazioni -> Ruoli -> Aggiungi ruolo.

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

Le impostazioni predefinite non sono molto rilevanti per la maggior parte dei ruoli e puoi semplicemente concedere all'Utente l'accesso in lettura e la visualizzazione dei ruoli e lasciare così.
Più interessante è l'aggiunta di permessi individuali per le Connessioni. Qui devi prima aggiungere un selettore per selezionare connessioni specifiche. Può essere un ID specifico oppure usare caratteri jolly con `*` per corrispondere a più connessioni. Ad esempio, se vuoi un ruolo che abbia accesso a tutti i database di sviluppo (nel caso tu gestisca anche l'accesso a questi con Kviklet), useresti un selettore come `dev-*` e assicurati che gli ID delle connessioni siano impostati correttamente.

Puoi naturalmente anche creare un sistema per i diversi team all'interno della tua organizzazione.

### Sincronizzazione ruoli (Enterprise)

Sincronizza automaticamente i ruoli utente dai gruppi del tuo identity provider. Questa funzionalità richiede una licenza enterprise.

**La configurazione** si trova in Impostazioni > Sincronizzazione ruoli:

- **Abilita sincronizzazione ruoli**: Attiva/disattiva la sincronizzazione
- **Modalità di sincronizzazione**:
  - **Sincronizzazione completa** - I ruoli utente corrispondono esattamente alle loro mappature dei gruppi IdP (più il ruolo predefinito)
  - **Aggiuntiva** - I gruppi IdP aggiungono ruoli ma non rimuovono quelli esistenti
  - **Solo al primo accesso** - I ruoli vengono sincronizzati solo al primo accesso, le modifiche manuali vengono preservate successivamente
- **Attributo gruppi**: L'attributo IdP che contiene le appartenenze ai gruppi (predefinito: `groups`)
- **Mappature ruoli**: Mappa i nomi dei gruppi IdP (ad esempio, `engineering`) ai ruoli Kviklet

#### Configurazione OIDC

Configura il tuo provider OIDC per includere un claim `groups` nel token ID:

- **Keycloak**:

  Keycloak non include i gruppi nei token per impostazione predefinita, quindi dovrai aggiungere un mapper al client.

  1. Vai su **Clients** nel menu a sinistra
  2. Seleziona il tuo client Kviklet
  3. Vai alla scheda **Client scopes**
  4. Fai clic sullo scope dedicato (ad esempio, `kviklet-dedicated`)
  5. Vai alla scheda **Mappers**
  6. Fai clic su **Add mapper** → **By configuration**
  7. Seleziona **Group Membership**
  8. Configura il mapper:

  | Impostazione | Valore |
  |--------------|--------|
  | Nome | `groups` |
  | Nome claim token | `groups` |
  | Percorso gruppo completo | **DISATTIVATO** |
  | Aggiungi al token ID | **ATTIVATO** |
  | Aggiungi al token di accesso | **ATTIVATO** |
  | Aggiungi a userinfo | **ATTIVATO** |

  9. Fai clic su **Salva**

  > **Importante:** Il "Nome claim token" deve corrispondere all'"Attributo gruppi" configurato nelle impostazioni di sincronizzazione ruoli di Kviklet (predefinito: `groups`).

- **Altri provider OIDC**: Aggiungi un mapper/claim per i gruppi che includa le appartenenze ai gruppi dell'utente nel token ID. Questo viene solitamente fatto nell'interfaccia di amministrazione del provider.

  Se incontri problemi, sentiti libero di creare un issue, non abbiamo testato tutti i provider OIDC (ancora) e potrebbero esserci piccole differenze nell'implementazione che potrebbero richiedere aggiornamenti dal lato di Kviklet.

#### Configurazione LDAP

La sincronizzazione ruoli LDAP utilizza l'attributo `memberOf`:

1. Assicurati che il tuo server LDAP abbia l'overlay `memberOf` abilitato
2. Imposta **Attributo gruppi** su `memberOf` in Kviklet
3. I nomi dei gruppi vengono quindi estratti dall'attributo `memberOf` negli attributi dell'utente.

#### Configurazione SAML

Configura il tuo IdP SAML per includere i gruppi nell'asserzione:

1. Aggiungi un attributo statement che mappi le appartenenze ai gruppi dell'utente
2. Imposta l'**Attributo gruppi** in Kviklet in modo che corrisponda al nome dell'attributo SAML
3. I nomi dei gruppi vengono quindi estratti dall'attributo SAML negli attributi dell'utente.

### Notifiche

Puoi configurare Kviklet per inviare notifiche a un canale Slack o Teams. Questo è utile per avvisare il tuo team riguardo a nuove richieste che necessitano di revisione. Puoi configurare questa opzione in Impostazioni -> Generali -> Impostazioni notifiche.

#### Slack

Per configurare le notifiche Slack, devi creare un'app Slack e abilitare i webhook per essa. Puoi seguire le istruzioni qui: https://api.slack.com/messaging/webhooks

#### Teams

Le notifiche Teams utilizzano un webhook **Workflow** di Power Automate. Kviklet invia una scheda adattiva (Adaptive Card), che il modello del webhook pubblica nel tuo canale.

**Raccomandato: utilizzare il modello di workflow**

1. In Teams, apri il canale in cui desideri ricevere le notifiche, fai clic sui **...** accanto al nome del canale e scegli **Workflows** (o aggiungi l'app **Workflows**).
2. Cerca e crea il modello **"Send webhook alerts to a channel"**.
3. Accedi quando richiesto, quindi seleziona il Team e Canale di destinazione e crea il workflow.
4. Apri il passo del trigger e copia l'**URL HTTP POST** generato.
5. Incolla l'URL in Kviklet sotto Impostazioni -> Generali -> Impostazioni notifiche e fai clic su salva.

**Alternativa: creare il workflow manualmente**

Se preferisci creare il flusso da solo (o il modello non è disponibile):

1. Canale **...** -> **Workflows** -> crea un flusso con il trigger **"When a Teams webhook request is received"**.
2. Aggiungi l'azione **Microsoft Teams -> "Post card in a chat or channel"**.
3. Imposta il campo **Adaptive Card** dell'azione sull'espressione `string(triggerBody())` in modo che pubblichi la scheda inviata da Kviklet.
4. Seleziona il Team e Canale di destinazione, **Salva**, quindi copia l'**URL HTTP POST** dal passo del trigger.

Attualmente ci sono notifiche per:

- Nuove richieste che necessitano di approvazioni
- Nuove approvazioni sulle richieste

#### Configurazione URL di base

Quando Kviklet è eseguito dietro un proxy inverso o un Ingress Kubernetes, i link delle notifiche potrebbero utilizzare l'indirizzo IP interno invece del tuo dominio pubblico. Kviklet cerca di tracciare l'URL corretto guardando le richieste in arrivo, ma alcuni proxy inversi non impostano correttamente gli header Forwarded. Per risolvere, imposta l'URL di base esplicitamente:```
KVIKLET_BASE_URL=https://kviklet.example.com

## Crittografia

Se non vuoi che le credenziali vengano memorizzate in chiaro nel DB, è consigliabile abilitare la crittografia del database sul DB PostgreSQL di Kviklet stesso. Per la maggior parte dei provider ospitati, è sufficiente selezionare una casella.
Tuttavia, se il database di Kviklet viene in qualche modo compromesso, si tratta di un enorme rischio per la sicurezza, poiché contiene le credenziali del database per potenzialmente tutti i tuoi archivi di dati di produzione. È quindi possibile abilitare la crittografia delle credenziali a riposo.

Per farlo, basta impostare le due variabili d'ambiente.```
ENCRYPTION_ENABLED=true
ENCRYPTION_KEY_CURRENT=some-secret

Kviklet ri-cifrerà tutte le connessioni all'avvio, in modo da poter riavviare il contenitore con la chiave precedente rimossa.

## Chiavi API

Kviklet supporta le chiavi API per l'accesso programmatico al sistema. Questa è una funzionalità solo per enterprise e richiede una licenza valida. Puoi creare chiavi API nella sezione Settings -> API Keys.

![Chiavi API](https://assets.kitploit.com/production/public/readmes/7140/a11d80c93ef29ead3b8b3bf3b435a782208d10bd2978d80cd2c4edc1fc7bc506.png)
![Chiavi API](https://assets.kitploit.com/production/public/readmes/7140/21948bc6a43dbdd88be563befbfc9052a1dd4a99735817c2ff99680c9c32cbd0.png)

Usalo come segue:```bash
curl --location '[kviklet_host]/api/connections/' \
--header 'Authorization: Bearer your-api-key'

in alternativa puoi usare file:```
PROXY_TLS_CERTIFICATE_SOURCE=file
PROXY_TLS_CERTIFICATE_CERT_FILE=path/to/cert.pem
PROXY_TLS_CERTIFICATE_KEY_FILE=path/to/key.pem