</details>

### Configuração do BD

Kviklet precisa do seu próprio banco de dados postgres (ou pelo menos esquema) para salvar metadados sobre consultas, conexões, aprovações, etc.
Você pode encontrar a imagem oficial aqui: https://hub.docker.com/_/postgres, ou usar uma versão hospedada na nuvem pelo provedor de nuvem de sua escolha.

Ao iniciar o contêiner kviklet, você precisará definir essas três variáveis de ambiente de acordo:```
SPRING_DATASOURCE_PASSWORD = password
SPRING_DATASOURCE_USERNAME = username
SPRING_DATASOURCE_URL = jdbc:postgresql://[host]:[port]/[database]?currentSchema=[schema]

Publicamos nossos contêineres nos pacotes GitHub por enquanto, então com tudo isso configurado, você pode executar `ghcr.io/kviklet/kviklet:main` não se esqueça de mapear a porta `8080` que é a porta padrão em que o Kviklet é iniciado.

Um exemplo de execução do docker run poderia ser assim:```
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

O ID e segredo do cliente Google podem ser facilmente obtidos seguindo as instruções do Google aqui:
https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid

Para URIs de redirecionamento válidos, você deve configurar: https://[kviklet_host]/api/login/oauth2/code/google
Para Origens Permitidas, simplesmente a URL do seu kviklet hospedado.

Após definir essas variáveis de ambiente, todos na sua organização podem fazer login com o botão "Entrar com o Google". Mas eles não terão nenhuma permissão por padrão; você precisará atribuir um papel a eles depois que fizerem login uma vez.

#### Keycloak

Se você quiser configurar SSO com Keycloak, você precisa definir estas 4 variáveis de ambiente:```
KVIKLET_IDENTITYPROVIDER_CLIENTID
KVIKLET_IDENTITYPROVIDER_CLIENTSECRET
KVIKLET_IDENTITYPROVIDER_TYPE=keycloak
KVIKLET_IDENTITYPROVIDER_ISSUERURI=http://[host]:[port]/realms/[realm]

Crie um aplicativo OAuth do GitHub em https://github.com/settings/developers e configure:

- Authorization callback URL: `https://[kviklet_host]/api/login/oauth2/code/github`
- Homepage URL: a URL do seu Kviklet hospedado

`KVIKLET_IDENTITYPROVIDER_GITHUB_ALLOWEDORGS` é **obrigatório** (o Kviklet se recusa a iniciar sem ele). Os aplicativos OAuth do GitHub não podem restringir quem completa o fluxo OAuth, então o Kviklet chama `/user/orgs` após a autenticação e rejeita usuários que não são membros de pelo menos uma organização na lista de permissões (sem distinção entre maiúsculas e minúsculas, primeiras 100 organizações verificadas).

Para que a verificação da organização veja a associação de um usuário, o usuário deve clicar em **Grant** (ou **Request**) ao lado de cada organização na lista de permissões na tela de consentimento OAuth. Se a organização tiver "Restrict third-party OAuth applications" ativado, o proprietário da organização também precisa aprovar o aplicativo OAuth uma vez antes que a associação de qualquer membro se torne visível.

O Kviklet solicita os escopos `read:user`, `user:email` e `read:org`. Os e-mails são sempre lidos de `/user/emails` e apenas uma entrada `primary && verified` é aceita, para que usuários com endereços de e-mail privados ainda façam login com sucesso.

#### Outros provedores OIDC

Outros provedores compatíveis com OIDC (GitLab, Auth0, Okta, etc.) devem funcionar de forma semelhante ao Keycloak. Observe que a `redirect URI` mudará dependendo do tipo que você escolher, então se você escolher `gitlab`, será `https://[kviklet_host]/api/login/oauth2/code/gitlab`.
Se você encontrar problemas, sinta-se à vontade para criar um issue, ainda não testamos todos os provedores OIDC existentes (ainda) e pode haver pequenas diferenças na implementação que podem exigir atualizações do lado do Kviklet.

### LDAP

O Kviklet suporta autenticação LDAP. Para habilitar e configurar o LDAP, você pode substituir as seguintes variáveis de 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

Detalhes de configuração:

- `SAML_ENABLED`: Defina como `true` para ativar a autenticação SAML
- `SAML_ENTITYID`: O ID de entidade do seu provedor de identidade SAML
- `SAML_SSOSERVICELOCATION`: A URL do serviço SSO do seu provedor de identidade
- `SAML_VERIFICATIONCERTIFICATE`: O certificado X.509 usado para verificar respostas SAML (inclua as linhas BEGIN/END CERTIFICATE)

Opcionalmente, você pode personalizar os mapeamentos de atributos SAML:```
SAML_USERATTRIBUTES_EMAILATTRIBUTE=email
SAML_USERATTRIBUTES_NAMEATTRIBUTE=name
SAML_USERATTRIBUTES_IDATTRIBUTE=nameID

## Configuração

### Conexões

Após iniciar o Kviklet, você primeiro precisa configurar uma conexão de banco de dados. Vá para Configurações -> Bancos de Dados -> Adicionar Conexão.

![Adicionar Conexão](https://assets.kitploit.com/production/public/readmes/7140/3ded2a0b23e5d2f02feb21a854263c91dedea25a789fb75ab8342384c4e39b52.png)
![Adicionar Conexão](https://assets.kitploit.com/production/public/readmes/7140/585238c9eddad8ed4e2440096ce0616445a6696e1042f58676a1d0b038edde7f.png)

Aqui você pode configurar requisitos de revisão e limites de execução para cada conexão. Consulte [Gates de Revisão](#review-gates) para detalhes.

#### AWS IAM AUTH

O Kviklet suporta o uso de IAM Auth para conexões de banco de dados Postgres e MySQL. Para isso, escolha IAM Auth ao criar uma nova conexão.

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

Isso removerá a opção de definir uma senha e usará as credenciais da AWS para se conectar ao banco de dados.

O Kviklet usa o `DefaultCredentialsProvider` da AWS para encontrar credenciais e gerar o token para a conexão. Isso significa que todos os locais típicos devem funcionar (variáveis de ambiente ou funções de instância associadas); a ordem exata está documentada aqui: https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/DefaultCredentialsProvider.html

Além disso, você pode fornecer um ARN de função da AWS que o Kviklet assumirá e usar essas credenciais para criar o token temporário do banco de dados. Isso é particularmente útil para conectar-se a bancos de dados que não estão na mesma conta AWS que o Kviklet. Para usar esse recurso, basta inserir o ARN da função no campo designado ao criar ou editar uma conexão IAM Auth. Deixar o campo vazio usará o provedor de credenciais padrão (sem assunção de função).

A região da AWS a ser usada durante a geração do token é inferida a partir da URL da sua conexão, portanto, não há opções para defini-la.

Para aprender como configurar o IAM Auth para seu banco de dados, siga a documentação oficial da AWS: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html
Os dois pontos principais são:

- Criar um usuário de banco de dados com a opção de autenticação IAM e permissões corretas
- Criar uma política IAM que permita à entidade AWS gerar tokens para este usuário

### Gates de Revisão

Por padrão, o Kviklet permite uma configuração simples de contagem de revisões. Você pode configurar quantas aprovações as solicitações em uma conexão específica precisam antes de serem executadas.

O status de aprovação de uma solicitação é calculado com base na ação mais recente de cada revisor. Se um revisor aprova e depois solicita alterações, apenas a solicitação de alteração conta — a aprovação anterior é removida. Editar uma solicitação sempre redefine todas as aprovações anteriores, garantindo que nenhuma alteração possa ser executada sem ser revisada primeiro. Da mesma forma, se uma execução falhar (por exemplo, devido a um erro de sintaxe SQL), as aprovações são redefinidas para que a solicitação possa ser corrigida e re-aprovada sem precisar criar uma nova.

Você também pode configurar um limite de **execuções máximas** por conexão para controlar quantas vezes uma única solicitação aprovada pode ser executada. O padrão é 1. Definir isso como 0 permite execuções ilimitadas. Execuções com falha não contam para esse limite.

#### Requisitos de Revisão Baseados em Funções (Enterprise)

Com uma Licença Enterprise do Kviklet, você pode configurar conexões individuais para exigir aprovações de usuários com funções específicas. Isso permite que você, por exemplo, exija aprovação da equipe que mantém um determinado banco de dados ou restrinja conexões sensíveis a aprovações de DBA ou gerência.

**Como funciona:**

Cada conexão tem uma contagem de **total de revisões necessárias** (`numTotalRequired`) que atua como um piso — o número mínimo de aprovações distintas necessárias independentemente das funções. Além disso, você pode adicionar **requisitos de função** que especificam quantas aprovações devem vir de usuários com uma função específica (por exemplo, "1 do DBA, 1 da Segurança").

Uma solicitação é aprovada somente quando **ambas** as condições são atendidas:
- O número total de aprovações distintas atende a `numTotalRequired`
- Cada requisito de função é satisfeito individualmente

Se um usuário pertencer a várias funções, uma única aprovação desse usuário conta para todos os requisitos de função correspondentes. No entanto, ainda conta apenas como uma aprovação para a contagem total.

**Exemplo:** Uma conexão requer 3 aprovações totais, incluindo 1 de um DBA e 1 da Segurança. Um usuário que tem ambas as funções de DBA e Segurança aprova — isso satisfaz ambos os requisitos de função, mas conta apenas como 1 das 3 aprovações totais necessárias. Ainda são necessárias mais duas aprovações de quaisquer usuários.

Se sua licença enterprise expirar, os requisitos de revisão baseados em funções existentes permanecem em vigor, mas não podem mais ser modificados. Você só pode removê-los para voltar à configuração simples de total de revisões.

### Funções

O Kviklet vem com 3 funções: Padrão, Administradores e Desenvolvedores.

- A função padrão fornece acesso de leitura a todas as conexões e Solicitações. Esta função é atribuída a todos os usuários e não pode ser removida. No entanto, você pode alterar as permissões desta função como desejar.
- Os administradores têm permissão para criar e editar conexões, bem como adicionar novos Usuários e definir suas permissões.
- Os desenvolvedores podem criar Solicitações, bem como aprová-las e comentar sobre elas e, claro, executar as instruções reais.

Você pode personalizar as Funções e, por exemplo, dar a uma função acesso apenas a uma conexão específica ou a um grupo de conexões de banco de dados.
Isso é útil, por exemplo, se você tiver equipes diferentes com bancos de dados diferentes e quiser controlar o acesso a eles de forma mais granular.

#### Criando uma nova Função

Criar uma nova função funciona da seguinte forma. Vá para Configurações -> Funções -> Adicionar Função.

![Adicionar Função](https://assets.kitploit.com/production/public/readmes/7140/a91b79287c0b3130b83bdde1c059f49b89c5d43a1c0deae33b211ea427956f8e.png)
![Adicionar Função](https://assets.kitploit.com/production/public/readmes/7140/c535ac152759bb21bea04a0968ce43fa7bf946c7699feca23c71f9eaba41ceaf.png)

As configurações padrão não são tão relevantes para a maioria das funções e você pode simplesmente dar ao usuário acesso de Leitura e Visualização de Função e deixar assim.
Mais interessante é a adição de permissões individuais para Conexões. Aqui você primeiro adiciona um seletor para selecionar conexões específicas. Pode ser um id específico ou você pode usar curingas com `*` para corresponder a várias conexões. Por exemplo, se você quiser ter uma função que tenha acesso a todos os bancos de dados de desenvolvimento (caso você também gerencie o acesso a eles com o Kviklet), você usaria um seletor como `dev-*` e garantiria que os ids das conexões estejam definidos corretamente.

Você pode, é claro, criar também um sistema que use para suas diferentes equipes dentro da sua organização.

### Sincronização de Funções (Enterprise)

Sincronize automaticamente as funções dos usuários a partir dos grupos do seu provedor de identidade. Este recurso requer uma licença enterprise.

**Configuração** é feita em Configurações > Sincronização de Funções:

- **Ativar Sincronização de Funções**: Ativar/desativar a sincronização
- **Modo de Sincronização**:
  - **Sincronização Completa** - As funções do usuário correspondem exatamente aos mapeamentos de grupo do IdP (mais a função padrão)
  - **Aditiva** - Os grupos do IdP adicionam funções, mas não removem as existentes
  - **Apenas no Primeiro Login** - As funções são sincronizadas apenas no primeiro login, as alterações manuais são preservadas posteriormente
- **Atributo de Grupos**: O atributo do IdP que contém as associações de grupo (padrão: `groups`)
- **Mapeamentos de Funções**: Mapeie nomes de grupos do IdP (ex.: `engineering`) para funções do Kviklet

#### Configuração OIDC

Configure seu provedor OIDC para incluir uma declaração `groups` no token de ID:

- **Keycloak**:

  O Keycloak não inclui grupos em tokens por padrão, então você precisará adicionar um mapeador ao cliente.

  1. Navegue até **Clientes** no menu esquerdo
  2. Selecione seu cliente Kviklet
  3. Vá para a guia **Escopos do Cliente**
  4. Clique no escopo dedicado (ex.: `kviklet-dedicated`)
  5. Vá para a guia **Mapeadores**
  6. Clique em **Adicionar mapeador** → **Por configuração**
  7. Selecione **Associação de Grupo**
  8. Configure o mapeador:

  | Configuração | Valor |
  |---|---|
  | Nome | `groups` |
  | Nome da Declaração do Token | `groups` |
  | Caminho completo do grupo | **DESLIGADO** |
  | Adicionar ao token de ID | **LIGADO** |
  | Adicionar ao token de acesso | **LIGADO** |
  | Adicionar ao userinfo | **LIGADO** |

  9. Clique em **Salvar**

  > **Importante:** O "Nome da Declaração do Token" deve corresponder ao "Atributo de Grupos" configurado nas configurações de Sincronização de Funções do Kviklet (padrão: `groups`).

- **Outros provedores OIDC**: Adicione um mapeador/declaração de grupos que inclua as associações de grupo do usuário no token de ID. Isso geralmente é feito na interface de administração do provedor.

  Se você encontrar problemas, fique à vontade para criar um issue; ainda não testamos todos os provedores OIDC existentes (ainda) e pode haver pequenas diferenças na implementação que podem exigir atualizações no lado do Kviklet.

#### Configuração LDAP

A sincronização de funções LDAP usa o atributo `memberOf`:

1. Certifique-se de que seu servidor LDAP tenha a sobreposição `memberOf` ativada
2. Defina **Atributo de Grupos** como `memberOf` no Kviklet
3. Os nomes dos grupos são então extraídos do atributo `memberOf` nos atributos dos usuários.

#### Configuração SAML

Configure seu IdP SAML para incluir grupos na declaração:

1. Adicione uma declaração de atributo que mapeie as associações de grupo do usuário
2. Defina o **Atributo de Grupos** no Kviklet para corresponder ao nome do atributo SAML
3. Os nomes dos grupos são então extraídos do atributo SAML nos atributos dos usuários.

### Notificações

Você pode configurar o Kviklet para enviar notificações para um canal no Slack ou Teams. Isso é útil para notificar sua equipe sobre novas solicitações que precisam ser revisadas. Você pode configurar isso em Configurações -> Geral -> Configurações de Notificação.

#### Slack

Para configurar notificações do Slack, você precisa criar um Aplicativo Slack e habilitar webhooks para ele. Você pode seguir as instruções aqui: https://api.slack.com/messaging/webhooks

#### Teams

As notificações do Teams usam um webhook **Workflow** do Power Automate. O Kviklet envia um Adaptive Card, que o modelo do webhook publica no seu canal.

**Recomendado: use o modelo de workflow**

1. No Teams, abra o canal onde você deseja receber notificações, clique nos **...** ao lado do nome do canal e escolha **Workflows** (ou adicione o aplicativo **Workflows**).
2. Pesquise e crie o modelo **"Enviar alertas de webhook para um canal"**.
3. Faça login quando solicitado, selecione a Equipe e o Canal de destino e crie o workflow.
4. Abra a etapa de gatilho e copie a **URL HTTP POST** gerada.
5. Cole a URL no Kviklet em Configurações -> Geral -> Configurações de Notificação e clique em salvar.

**Alternativa: crie o workflow manualmente**

Se você preferir criar o fluxo manualmente (ou o modelo não estiver disponível):

1. Canal **...** -> **Workflows** -> crie um fluxo com o gatilho **"Quando uma solicitação de webhook do Teams for recebida"**.
2. Adicione a ação **Microsoft Teams -> "Postar cartão em um chat ou canal"**.
3. Defina o campo **Adaptive Card** da ação para a expressão `string(triggerBody())` para que ele poste o cartão que o Kviklet envia.
4. Selecione a Equipe e o Canal de destino, **Salve**, depois copie a **URL HTTP POST** da etapa de gatilho.

Atualmente existem notificações para:

- Novas Solicitações, que precisam de aprovações
- Novas aprovações em solicitações

#### Configuração de URL Base

Ao executar o Kviklet atrás de um proxy reverso ou Ingress do Kubernetes, os links de notificação podem usar o endereço IP interno em vez do seu domínio público. O Kviklet tenta rastrear a URL correta analisando as requisições recebidas, mas alguns proxies reversos não definem os cabeçalhos Forwarded corretamente. Para corrigir isso, defina a URL base explicitamente:```
KVIKLET_BASE_URL=https://kviklet.example.com

## Criptografia

Se você não quiser que as credenciais sejam armazenadas em texto claro no banco de dados, é recomendável que você ative a criptografia do banco de dados no próprio banco de dados Postgres do Kviklet. Para a maioria dos provedores hospedados, isso é uma simples caixa de seleção para marcar.
No entanto, se o banco de dados do Kviklet for comprometido de alguma forma, isso representa um enorme risco de segurança. Pois ele contém as credenciais do banco de dados para potencialmente todos os seus armazenamentos de dados de produção. Então você pode ativar a criptografia das credenciais em repouso.

Para fazer isso, basta definir as duas variáveis de ambiente.```
ENCRYPTION_ENABLED=true
ENCRYPTION_KEY_CURRENT=some-secret

Kviklet irá reencriptar todas as conexões na inicialização, de modo que você possa então reiniciar o contêiner com a chave anterior removida.

## Chaves de API

O Kviklet suporta chaves de API para acesso programático ao sistema. Este é um recurso apenas para empresas e requer uma licença válida. Você pode criar chaves de API na seção Configurações -> Chaves de API.

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

Use da seguinte forma:```bash
curl --location '[kviklet_host]/api/connections/' \
--header 'Authorization: Bearer your-api-key'

alternativamente você pode usar arquivos:```
PROXY_TLS_CERTIFICATE_SOURCE=file
PROXY_TLS_CERTIFICATE_CERT_FILE=path/to/cert.pem
PROXY_TLS_CERTIFICATE_KEY_FILE=path/to/key.pem