</details>

### Configuration de la base de données

Kviklet a besoin de sa propre base de données postgres (ou au moins d'un schéma) pour enregistrer les métadonnées sur les requêtes, les connexions, les approbations, etc.
Vous pouvez trouver leur image officielle ici : https://hub.docker.com/_/postgres, ou utiliser une version hébergée dans le cloud par votre fournisseur de cloud de votre choix.

Lors du démarrage du conteneur kviklet, vous devrez ensuite définir ces trois variables d'environnement en conséquence :```
SPRING_DATASOURCE_PASSWORD = password
SPRING_DATASOURCE_USERNAME = username
SPRING_DATASOURCE_URL = jdbc:postgresql://[host]:[port]/[database]?currentSchema=[schema]

Nous publions nos conteneurs sur GitHub packages pour l'instant, donc avec tout cela configuré, vous pouvez exécuter `ghcr.io/kviklet/kviklet:main` n'oubliez pas de mapper le port `8080` qui est le port par défaut sur lequel Kviklet démarre.

Un exemple d'exécution docker run pourrait ressembler à ceci :```
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

L'identifiant client et le secret Google peuvent être facilement obtenus en suivant les instructions de Google ici :
https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid

Pour les URIs de redirection valides, vous devez configurer : https://[kviklet_host]/api/login/oauth2/code/google
Pour les origines autorisées, simplement l'URL de votre kviklet hébergé.

Après avoir défini ces variables d'environnement, tous les membres de votre organisation peuvent se connecter avec le bouton « Se connecter avec Google ». Mais ils n'auront aucune permission par défaut, vous devrez leur attribuer un rôle après leur première connexion.

#### Keycloak

Si vous souhaitez plutôt configurer le SSO avec Keycloak, vous devez définir ces 4 variables d'environnement :```
KVIKLET_IDENTITYPROVIDER_CLIENTID
KVIKLET_IDENTITYPROVIDER_CLIENTSECRET
KVIKLET_IDENTITYPROVIDER_TYPE=keycloak
KVIKLET_IDENTITYPROVIDER_ISSUERURI=http://[host]:[port]/realms/[realm]

Créez une application OAuth GitHub sur https://github.com/settings/developers et configurez :

- URL de rappel d'autorisation : `https://[kviklet_host]/api/login/oauth2/code/github`
- URL de la page d'accueil : l'URL de votre Kviklet hébergé

`KVIKLET_IDENTITYPROVIDER_GITHUB_ALLOWEDORGS` est **obligatoire** (Kviklet refuse de démarrer sans cela). Les applications OAuth GitHub ne peuvent pas restreindre qui termine le flux OAuth, donc Kviklet appelle `/user/orgs` après l'authentification et rejette les utilisateurs qui ne sont pas membres d'au moins une organisation autorisée (insensible à la casse, seules les 100 premières organisations sont vérifiées).

Pour que la vérification d'organisation voie l'appartenance d'un utilisateur, celui-ci doit cliquer sur **Accorder** (ou **Demander**) à côté de chaque organisation autorisée sur l'écran de consentement OAuth. Si l'organisation a activé « Restreindre les applications OAuth tierces », un propriétaire de l'organisation doit également approuver l'application OAuth une fois avant que l'appartenance d'un membre devienne visible.

Kviklet demande les portées `read:user`, `user:email` et `read:org`. Les adresses e-mail sont toujours lues depuis `/user/emails` et seule une entrée `primary && verified` est acceptée, donc les utilisateurs avec des adresses e-mail privées se connectent toujours avec succès.

#### Autres fournisseurs OIDC

D'autres fournisseurs compatibles OIDC (GitLab, Auth0, Okta, etc.) devraient fonctionner de manière similaire à Keycloak. Notez que l'`URL de redirection` changera selon le type que vous choisissez, donc si vous choisissez `gitlab`, ce sera `https://[kviklet_host]/api/login/oauth2/code/gitlab`. Si vous rencontrez des problèmes, n'hésitez pas à créer une issue, nous n'avons pas encore testé tous les fournisseurs OIDC existants et il pourrait y avoir de légères différences dans l'implémentation qui pourraient nécessiter des mises à jour du côté de Kviklet.

### LDAP

Kviklet prend en charge l'authentification LDAP. Pour activer et configurer LDAP, vous pouvez remplacer les variables d'environnement suivantes :```
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

Détails de configuration :

- `SAML_ENABLED` : Définissez sur `true` pour activer l'authentification SAML
- `SAML_ENTITYID` : L'ID d'entité de votre fournisseur d'identité SAML
- `SAML_SSOSERVICELOCATION` : L'URL du service SSO de votre fournisseur d'identité
- `SAML_VERIFICATIONCERTIFICATE` : Le certificat X.509 utilisé pour vérifier les réponses SAML (incluez les lignes BEGIN/END CERTIFICATE)

Vous pouvez éventuellement personnaliser les correspondances d'attributs SAML :```
SAML_USERATTRIBUTES_EMAILATTRIBUTE=email
SAML_USERATTRIBUTES_NAMEATTRIBUTE=name
SAML_USERATTRIBUTES_IDATTRIBUTE=nameID

## Configuration

### Connexions

Après avoir démarré Kviklet, vous devez d'abord configurer une connexion à une base de données. Allez dans Paramètres -> Bases de données -> Ajouter une connexion.

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

Vous pouvez ici configurer les exigences de révision et les limites d'exécution pour chaque connexion. Voir [Portes de révision](#review-gates) pour plus de détails.

#### AWS IAM AUTH

Kviklet prend en charge l'utilisation de IAM Auth pour les connexions aux bases de données Postgres et MySQL. Pour cela, choisissez IAM Auth lors de la création d'une nouvelle connexion.

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

Cela supprime l'option de définir un mot de passe et utilise à la place les identifiants AWS pour se connecter à la base de données.

Kviklet utilise `DefaultCredentialsProvider` d'AWS pour trouver les identifiants et générer le jeton pour la connexion. Cela signifie que tous les emplacements typiques devraient fonctionner (variables d'environnement ou rôles d'instance associés) l'ordre exact est documenté ici : https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/DefaultCredentialsProvider.html

De plus, vous pouvez fournir un ARN de rôle AWS que Kviklet assumera, et utiliser ces identifiants pour créer le jeton DB temporaire. Ceci est particulièrement utile pour se connecter à des bases de données qui ne sont pas dans le même compte AWS que Kviklet. Pour utiliser cette fonctionnalité, saisissez simplement l'ARN du rôle dans le champ désigné lors de la création ou de l'édition d'une connexion IAM Auth. Laisser le champ vide utilisera le fournisseur d'identifiants par défaut (aucune assumption de rôle).

La région AWS à utiliser lors de la génération du jeton est déduite de votre URL de connexion, il n'y a donc pas d'option pour la définir.

Pour apprendre à configurer IAM Auth pour votre base de données, suivez la documentation officielle AWS : https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html
Les deux points principaux sont :

- Créer un utilisateur DB avec l'option IAM auth et les permissions correctes
- Créer une politique IAM qui permet à l'entité AWS de générer des jetons pour cet utilisateur

### Portes de révision

Par défaut, Kviklet permet une configuration simple du nombre de révisions. Vous pouvez configurer le nombre d'approbations nécessaires pour une demande sur une connexion spécifique avant qu'elle ne puisse être exécutée.

Le statut d'approbation d'une demande est calculé en fonction de la dernière action de chaque réviseur. Si un réviseur approuve puis demande des modifications, seule la demande de modification compte — son approbation précédente est supprimée. La modification d'une demande réinitialise toujours toutes les approbations antérieures, garantissant qu'aucune modification ne peut être exécutée sans être d'abord révisée. De même, si une exécution échoue (par exemple en raison d'une erreur de syntaxe SQL), les approbations sont réinitialisées afin que la demande puisse être corrigée et ré-approuvée sans avoir à en créer une nouvelle.

Vous pouvez également configurer une limite de **nombre maximal d'exécutions** par connexion pour contrôler la fréquence à laquelle une demande approuvée peut être exécutée. La valeur par défaut est 1. Mettre cette valeur à 0 permet des exécutions illimitées. Les exécutions échouées ne comptent pas dans cette limite.

#### Exigences de révision basées sur les rôles (Entreprise)

Avec une licence Kviklet Enterprise, vous pouvez configurer des connexions individuelles pour exiger des approbations provenant d'utilisateurs avec des rôles spécifiques. Cela vous permet par exemple d'exiger l'approbation de l'équipe qui maintient une base de données donnée ou de verrouiller des connexions sensibles derrière des approbations DBA ou de direction.

**Comment cela fonctionne :**

Chaque connexion a un nombre **total de révisions requises** (`numTotalRequired`) qui agit comme un seuil minimal — le nombre minimum d'approbations distinctes nécessaires, indépendamment des rôles. En plus de cela, vous pouvez ajouter des **exigences de rôle** qui spécifient combien d'approbations doivent provenir d'utilisateurs avec un rôle particulier (par exemple, « 1 du DBA, 1 de la Sécurité »).

Une demande n'est approuvée que lorsque **les deux** conditions sont remplies :
- Le nombre total d'approbations distinctes atteint `numTotalRequired`
- Chaque exigence de rôle est individuellement satisfaite

Si un utilisateur appartient à plusieurs rôles, une seule approbation de cet utilisateur compte pour toutes les exigences de rôle correspondantes. Cependant, elle ne compte toujours que pour une seule approbation dans le total.

**Exemple :** Une connexion nécessite 3 approbations totales, dont 1 d'un DBA et 1 de la Sécurité. Un utilisateur qui a à la fois le rôle DBA et Sécurité approuve — cela satisfait les deux exigences de rôle mais ne compte que pour 1 des 3 approbations totales nécessaires. Deux autres approbations de n'importe quels utilisateurs sont toujours nécessaires.

Si votre licence entreprise expire, les exigences de révision basées sur les rôles existantes restent appliquées mais ne peuvent plus être modifiées. Vous pouvez uniquement les supprimer pour revenir à la simple configuration du nombre total de révisions.

### Rôles

Kviklet est livré avec 3 rôles : Par défaut, Administrateurs et Développeurs.

- Le rôle Par défaut donne un accès en lecture à toutes les connexions et demandes. Ce rôle est attribué à chaque utilisateur et ne peut pas être supprimé. Vous pouvez cependant modifier ses permissions comme vous le souhaitez.
- Les Administrateurs ont la permission de créer et modifier des connexions, ainsi que d'ajouter de nouveaux utilisateurs et de définir leurs permissions.
- Les Développeurs peuvent créer des demandes, les approuver, les commenter et bien sûr exécuter les instructions réelles.

Vous pouvez personnaliser les rôles et, par exemple, donner à un rôle l'accès uniquement à une connexion spécifique ou à un groupe de connexions de base de données.
Ceci est utile par exemple si vous avez différentes équipes avec différentes bases de données et souhaitez contrôler l'accès de manière plus granulaire.

#### Créer un nouveau rôle

La création d'un nouveau rôle se fait comme suit. Allez dans Paramètres -> Rôles -> Ajouter un rôle.

![Ajouter un rôle](https://assets.kitploit.com/production/public/readmes/7140/a91b79287c0b3130b83bdde1c059f49b89c5d43a1c0deae33b211ea427956f8e.png)
![Ajouter un rôle](https://assets.kitploit.com/production/public/readmes/7140/c535ac152759bb21bea04a0968ce43fa7bf946c7699feca23c71f9eaba41ceaf.png)

Les paramètres par défaut ne sont pas très pertinents pour la plupart des rôles et vous pouvez simplement donner à l'utilisateur l'accès Lecture et Affichage des rôles et laisser ainsi.
Ce qui est plus intéressant, c'est l'ajout de permissions individuelles pour les connexions. Ici, vous ajoutez d'abord un sélecteur pour sélectionner des connexions spécifiques. Cela peut être un identifiant spécifique ou vous pouvez utiliser des jokers avec `*` pour correspondre à plusieurs connexions. Par exemple, si vous voulez un rôle qui a accès à toutes les bases de données de développement (au cas où vous gérez aussi l'accès à celles-ci avec Kviklet), vous utiliseriez un sélecteur comme `dev-*` et vous assureriez que les identifiants des connexions sont définis correctement.

Vous pouvez bien sûr aussi inventer un système que vous utilisez pour vos différentes équipes au sein de votre organisation.

### Synchronisation des rôles (Entreprise)

Synchronisez automatiquement les rôles des utilisateurs à partir des groupes de votre fournisseur d'identité. Cette fonctionnalité nécessite une licence entreprise.

**La configuration** se fait dans Paramètres > Synchronisation des rôles :

- **Activer la synchronisation des rôles** : Activer/désactiver la synchronisation
- **Mode de synchronisation** :
  - **Synchronisation complète** - Les rôles des utilisateurs correspondent exactement à leurs correspondances de groupes IdP (plus le rôle par défaut)
  - **Additif** - Les groupes IdP ajoutent des rôles mais ne suppriment pas les existants
  - **Première connexion uniquement** - Les rôles ne se synchronisent que lors de la première connexion, les modifications manuelles sont conservées par la suite
- **Attribut de groupes** : L'attribut IdP contenant les appartenances aux groupes (par défaut : `groups`)
- **Correspondances de rôles** : Mappez les noms de groupes IdP (par exemple, `engineering`) aux rôles Kviklet

#### Configuration OIDC

Configurez votre fournisseur OIDC pour inclure une revendication `groups` dans le jeton d'identité :

- **Keycloak** :

  Keycloak n'inclut pas les groupes dans les jetons par défaut, vous devrez donc ajouter un mappeur au client.

  1. Naviguez vers **Clients** dans le menu de gauche
  2. Sélectionnez votre client Kviklet
  3. Allez dans l'onglet **Client scopes**
  4. Cliquez sur le scope dédié (par exemple, `kviklet-dedicated`)
  5. Allez dans l'onglet **Mappers**
  6. Cliquez sur **Add mapper** → **By configuration**
  7. Sélectionnez **Group Membership**
  8. Configurez le mappeur :

  | Paramètre | Valeur |
  |-----------|--------|
  | Nom | `groups` |
  | Nom de la revendication du jeton | `groups` |
  | Chemin complet du groupe | **OFF** |
  | Ajouter au jeton d'identité | **ON** |
  | Ajouter au jeton d'accès | **ON** |
  | Ajouter à userinfo | **ON** |

  9. Cliquez sur **Enregistrer**

  > **Important :** Le « Nom de la revendication du jeton » doit correspondre à « l'Attribut de groupes » configuré dans les paramètres de synchronisation des rôles de Kviklet (par défaut : `groups`).

- **Autres fournisseurs OIDC** : Ajoutez un mappeur/revendication de groupes qui inclut les appartenances aux groupes de l'utilisateur dans le jeton d'identité. Cela se fait généralement dans l'interface d'administration du fournisseur.

  Si vous rencontrez des problèmes, n'hésitez pas à créer une issue, nous n'avons pas encore testé tous les fournisseurs OIDC existants et il pourrait y avoir de légères différences dans l'implémentation qui pourraient nécessiter des mises à jour du côté de Kviklet.

#### Configuration LDAP

La synchronisation des rôles LDAP utilise l'attribut `memberOf` :

1. Assurez-vous que votre serveur LDAP a le module complémentaire `memberOf` activé
2. Définissez **Attribut de groupes** sur `memberOf` dans Kviklet
3. Les noms de groupes sont ensuite extraits de l'attribut `memberOf` dans les attributs de l'utilisateur.

#### Configuration SAML

Configurez votre IdP SAML pour inclure les groupes dans l'assertion :

1. Ajoutez une instruction d'attribut qui mappe les appartenances aux groupes des utilisateurs
2. Définissez **l'Attribut de groupes** dans Kviklet pour correspondre au nom de votre attribut SAML
3. Les noms de groupes sont ensuite extraits de l'attribut SAML dans les attributs de l'utilisateur.

### Notifications

Vous pouvez configurer Kviklet pour envoyer des notifications à un canal dans Slack ou Teams. Cela est utile pour informer votre équipe des nouvelles demandes qui doivent être révisées. Vous pouvez configurer cela dans Paramètres -> Général -> Paramètres de notification.

#### Slack

Pour configurer les notifications Slack, vous devez créer une application Slack et activer les webhooks pour celle-ci. Vous pouvez suivre les instructions ici : https://api.slack.com/messaging/webhooks

#### Teams

Les notifications Teams utilisent un webhook **Workflow** Power Automate. Kviklet envoie une carte adaptative que le modèle de webhook publie dans votre canal.

**Recommandé : utiliser le modèle de workflow**

1. Dans Teams, ouvrez le canal dans lequel vous voulez recevoir des notifications, cliquez sur les **...** à côté du nom du canal et choisissez **Workflows** (ou ajoutez l'application **Workflows**).
2. Recherchez et créez le modèle **« Send webhook alerts to a channel »**.
3. Connectez-vous lorsque vous y êtes invité, puis sélectionnez l'équipe et le canal cibles et créez le workflow.
4. Ouvrez l'étape déclencheur et copiez l'**URL HTTP POST** générée.
5. Collez l'URL dans Kviklet sous Paramètres -> Général -> Paramètres de notification et cliquez sur enregistrer.

**Alternative : construire le workflow manuellement**

Si vous préférez construire le flux vous-même (ou si le modèle est indisponible) :

1. Canal **...** -> **Workflows** -> créez un flux avec le déclencheur **« When a Teams webhook request is received »**.
2. Ajoutez l'action **Microsoft Teams -> « Post card in a chat or channel »**.
3. Définissez le champ **Carte adaptative** de l'action sur l'expression `string(triggerBody())` pour qu'elle publie la carte que Kviklet envoie.
4. Sélectionnez l'équipe et le canal cibles, **Enregistrez**, puis copiez l'**URL HTTP POST** de l'étape déclencheur.

Actuellement, il y a des notifications pour :

- Nouvelles demandes nécessitant des approbations
- Nouvelles approbations sur des demandes

#### Configuration de l'URL de base

Lorsque Kviklet s'exécute derrière un proxy inverse ou un Ingress Kubernetes, les liens de notification peuvent utiliser l'adresse IP interne au lieu de votre domaine public. Kviklet essaie de suivre l'URL correcte en examinant les requêtes entrantes, mais certains proxys inverses ne définissent pas correctement les en-têtes Forwarded. Pour résoudre ce problème, définissez explicitement l'URL de base :```
KVIKLET_BASE_URL=https://kviklet.example.com

## Chiffrement

Si vous ne souhaitez pas que les identifiants soient stockés en clair dans la base de données, il est recommandé d'activer le chiffrement de la base de données sur la base de données PostgreSQL de Kviklet elle-même. Pour la plupart des fournisseurs hébergés, il s'agit d'une simple case à cocher. Néanmoins, si la base de données Kviklet est compromise d'une manière ou d'une autre, cela représente un risque de sécurité important. Car elle contient les identifiants de base de données pour potentiellement tous vos datastores de production. Vous pouvez donc activer le chiffrement des identifiants au repos.

Pour ce faire, définissez simplement les deux variables d'environnement.```
ENCRYPTION_ENABLED=true
ENCRYPTION_KEY_CURRENT=some-secret

Kviklet rechiffrera toutes les connexions au démarrage, afin que vous puissiez ensuite redémarrer le conteneur sans la clé précédente.

## Clés API

Kviklet prend en charge les clés API pour un accès programmatique au système. Il s'agit d'une fonctionnalité réservée aux entreprises et nécessite une licence valide. Vous pouvez créer des clés API dans la section Paramètres -> Clés API.

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

Utilisez-la comme suit :```bash
curl --location '[kviklet_host]/api/connections/' \
--header 'Authorization: Bearer your-api-key'

alternativement, vous pouvez utiliser des fichiers :```
PROXY_TLS_CERTIFICATE_SOURCE=file
PROXY_TLS_CERTIFICATE_CERT_FILE=path/to/cert.pem
PROXY_TLS_CERTIFICATE_KEY_FILE=path/to/key.pem