Voltar às atualizações
New releaseSep 22, 2026

kviklet v0.9.0

Fluxo de Revisão/Aprovação similar a Pull Request para consultas de banco de dados. Para acesso de Engenharia à produção que seja compatível, mas suave.

Compartilhar

Kviklet

Kviklet.dev | Notas de Versão | Discord

Acesso seguro a ambientes de produção sem prejudicar a produtividade dos desenvolvedores.

Kviklet Kviklet

Kviklet (pronuncia-se Quick-let) aplica o Princípio dos Quatro Olhos ao acesso a bancos de dados de produção, com um fluxo de revisão e aprovação semelhante a um pull request para instruções SQL individuais ou sessões de banco de dados com tempo limitado. Engenheiros podem revisar e aprovar as solicitações uns dos outros sem encaminhar cada consulta por meio de um DBA ou equipe de operações.

Kviklet é auto-hospedado e é executado como um contêiner Docker com um banco de dados PostgreSQL para o estado da aplicação. Sua interface web permite enviar, revisar e executar solicitações. Uma licença empresarial opcional desbloqueia autenticação SAML, requisitos de revisão baseados em funções, sincronização de funções e chaves de API. Solicite uma licença empresarial em kviklet.dev.

Os bancos de dados suportados são Postgres, MySQL, MariaDB, MS SQL Server e MongoDB.

Modelo de Acesso

Recomendamos conectar o Kviklet ao seu provedor de identidade existente. O Kviklet suporta SSO por meio de OIDC (Google, Keycloak, etc.) ou SAML (somente empresarial), bem como autenticação LDAP (Active Directory, etc.).
Os usuários então criam solicitações para conexões que mapeiam para um usuário específico do banco de dados. Essas solicitações são:

  • Consulta Única: uma instrução SQL específica enviada para revisão.
  • Acesso Temporário: uma sessão com tempo limitado na qual você pode executar várias instruções.

Dependendo da configuração, as solicitações são revisadas e aprovadas por outros usuários antes que o Kviklet permita a execução.

O Kviklet se conecta ao banco de dados em nome do usuário. A senha do banco de dados da conexão nunca é mostrada ao usuário.

Um administrador pode configurar qual função tem acesso a qual conexão e quais portões de revisão são necessários para a execução. O acesso no nível do banco de dados é gerenciado por meio dos mecanismos de RBAC do banco de dados subjacente. Por exemplo, é possível criar uma função somente leitura para uma conexão somente leitura e atribuir menos requisitos de revisão para essa do que para uma conexão de escrita.

O Kviklet registra as instruções executadas e as associa ao usuário e à solicitação de acesso. Para cobertura completa do acesso manual ao banco de dados, restrinja conexões diretas e encaminhe qualquer acesso manual por meio do Kviklet. Os engenheiros não precisam receber ou compartilhar as credenciais subjacentes do banco de dados.

Recursos empresariais adicionais incluem:

  • SAML: Suporte para autenticação SAML.
  • Proxy (Postgres, MariaDB, MySQL): Use seu cliente de banco de dados preferido por meio de uma sessão de acesso temporário aprovada com uma senha temporária. As instruções executadas são registradas no log de auditoria do Kviklet.
  • Portões de Revisão Baseados em Funções: Exigir aprovações de funções específicas antes da execução.
  • Sincronização de Funções: Sincronizar automaticamente as funções do usuário a partir dos grupos do seu provedor de identidade.
  • Chaves de API: Acesso programático à API do Kviklet.
Mais capturas de tela

Solicitações

Todas as solicitações de dados ficam em um só lugar. Como PRs abertos para seus bancos de dados de produção:

Requests Requests

Sessões ao Vivo

Uma solicitação de acesso temporário aprovada abre uma sessão SQL ao vivo diretamente no navegador:

Live Session Live Session

Log de auditoria

Toda instrução executada é registrada — seja executada como uma consulta única revisada, em uma sessão ao vivo ou por meio do proxy de banco de dados:

audit log audit log

Recurso por Tipo de Banco de Dados/Conexão

A maioria dos recursos está disponível para todos os bancos de dados (SSO, LDAP, RBAC, Fluxo de Revisão/Aprovação, log de auditoria, etc.). Mas alguns recursos são restritos, seja porque simplesmente ainda não foram construídos ou porque não fazem sentido para esse propósito específico. A tabela a seguir mostra quais recursos estão disponíveis para qual tipo de banco de dados:

Banco de DadosRevisão de InstruçãoAcesso TemporárioProxy(Beta)Explain Plan
Postgres
MySQL
MariaDB
SQL Server
MongoDB
Kubernetes

Configuração

O Kviklet é distribuído como um contêiner docker simples. Você pode encontrar as versões disponíveis em Releases. Recomendamos atualizar regularmente a versão que você está usando, pois continuamos a construir novos recursos.
A mais recente atualmente é ghcr.io/kviklet/kviklet:0.8.0, você também pode usar :main, mas pode acontecer de vez em quando de mesclarmos algo com bugs acidentalmente. Embora tentemos evitar isso.

Início Rápido

Se você só quer experimentar como funciona:

  1. Aqui está um docker-compose.yaml mínimo:

    Clique para expandir o conteúdo do compose ``` services: postgres: image: postgres:16 restart: always environment: POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres POSTGRES_DB: postgres ports: - "5432:5432" volumes: - ./postgres-data:/var/lib/postgresql/data # - ./sample_data.sql:/docker-entrypoint-initdb.d/init.sql

    kviklet-postgres: image: postgres:16 restart: always environment: POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres POSTGRES_DB: kviklet ports: - "5433:5432" volumes: - ./kviklet-postgres-data:/var/lib/postgresql/data

    kviklet: image: ghcr.io/kviklet/kviklet:main ports: - "80:8080" environment: - SPRING_DATASOURCE_URL=jdbc:postgresql://kviklet-postgres:5432/kviklet - SPRING_DATASOURCE_USERNAME=postgres - SPRING_DATASOURCE_PASSWORD=postgres - INITIAL_USER_EMAIL=[email protected] - INITIAL_USER_PASSWORD=admin depends_on: - kviklet-postgres

  1. Execute o docker-compose.yml via docker-compose up -d. O Kviklet será iniciado na porta 80, acesse localhost e explore. O login de administrador é [email protected] com admin como senha.

  2. O docker-compose contém um banco de dados postgres extra para o qual você pode configurar uma conexão no Kviklet. Para fazer com que este banco de dados contenha alguns dados, descomente esta linha: ``` - ./sample_data.sql:/docker-entrypoint-initdb.d/init.sql

E crie um arquivo sample_data.sql:

Clique para expandir o conteúdo de sample_data.sql ```sql CREATE TABLE Locations ( Name VARCHAR(100) NOT NULL, Address VARCHAR(255) NOT NULL, City VARCHAR(100) NOT NULL, Country VARCHAR(100) NOT NULL, PostalCode VARCHAR(20) NOT NULL );

alter table public.Locations owner to postgres;

INSERT INTO public.Locations (Name, Address, City, Country, PostalCode) VALUES ('Central Park', '59th to 110th St', 'New York', 'USA', '10022'), ('Eiffel Tower', 'Champ de Mars, 5 Avenue Anatole', 'Paris', 'France', '75007'), ('Colosseum', 'Piazza del Colosseo, 1', 'Rome', 'Italy', '00184'), ('Sydney Opera House', 'Bennelong Point', 'Sydney', 'Australia', '2000'), ('Great Wall of China', 'Huairou District', 'Beijing', 'China', '101405');

</details>

### Configuração do Banco de Dados

O Kviklet precisa de seu próprio banco de dados postgres (ou pelo menos schema) 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 estas 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]

Métodos de autenticação alternativos

  • IAM Auth: É possível usar o AWS IAM Auth para a conexão com o banco de dados; nesse caso, basta omitir a senha e definir apenas o nome de usuário. Você também precisa definir a variável de ambiente: ``` SPRING_DATASOURCE_IAMAUTH=true

O Kviklet carregará as credenciais dos locais habituais (variáveis de ambiente, funções de instância, etc.) e gerará um token para a conexão.

  • Certificados: Você também pode usar certificados para a conexão com o banco de dados, veja aqui um exemplo.

Usuário Inicial

Você precisará de um usuário administrador inicial para fins de configuração. Para isso, defina as 2 variáveis de ambiente: INITIAL_USER_EMAIL e INITIAL_USER_PASSWORD para que você possa fazer login na interface web. Você pode alterar a senha depois através da UI.
Exemplo:``` INITIAL_USER_EMAIL=[email protected] INITIAL_USER_PASSWORD=someverysecurepassword

Publicamos nossos containers no GitHub packages 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 na qual o Kviklet é iniciado.

Um exemplo de 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

SSO via OIDC / OAuth2

Google

Se você quiser configurar SSO para sua instância do Kviklet (o que faz muito sentido, já que de outra forma você teria que gerenciar senhas novamente). Você precisa configurar estas 3 variáveis de ambiente:``` KVIKLET_IDENTITYPROVIDER_CLIENTID KVIKLET_IDENTITYPROVIDER_CLIENTSECRET KVIKLET_IDENTITYPROVIDER_TYPE=google

O client id e o secret do Google você pode obter facilmente seguindo as instruções do Google aqui:
https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid

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

Depois de definir essas variáveis de ambiente, todos na sua organização podem fazer login com o botão sign in with google. Mas eles não terão nenhuma permissão por padrão, você terá que atribuir um papel a eles depois que fizerem login uma vez.

#### Keycloak

Se você quiser configurar SSO com Keycloak em vez disso, 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]

Você obtém o client id e o secret quando cria uma aplicação no Keycloak. Para URIs de redirecionamento válidos, você deve configurar: https://[kviklet_host]/api/login/oauth2/code/keycloak Para Allowed Origins, simplesmente a url do seu kviklet hospedado.

Depois de definir essas variáveis de ambiente, a página de login deve mostrar um botão Login with Keycloak que redireciona para a sua instância do keycloak. Na edição enterprise, você pode habilitar a sincronização de funções para sincronizar automaticamente as funções da sua instância do keycloak para o kviklet. Consulte a seção Role Sync para mais detalhes.

GitHub (Beta)

Beta: A autenticação GitHub é nova e não suporta role sync ainda — todo novo usuário entra com a função padrão e precisa ter funções atribuídas manualmente.

O GitHub não é compatível com OIDC (é puro OAuth 2.0), então ele tem suporte dedicado no Kviklet. Defina estas variáveis de ambiente:``` KVIKLET_IDENTITYPROVIDER_CLIENTID KVIKLET_IDENTITYPROVIDER_CLIENTSECRET KVIKLET_IDENTITYPROVIDER_TYPE=github KVIKLET_IDENTITYPROVIDER_GITHUB_ALLOWEDORGS=your-org,another-org

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

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

`KVIKLET_IDENTITYPROVIDER_GITHUB_ALLOWEDORGS` é **obrigatório** (o Kviklet recusa-se a iniciar sem ele). As GitHub OAuth Apps não conseguem restringir quem completa o fluxo OAuth, por isso o Kviklet chama `/user/orgs` após a autenticação e rejeita utilizadores que não sejam membros de pelo menos uma organização na lista de permitidas (sem distinção de maiúsculas/minúsculas, são verificadas as primeiras 100 organizações).

Para que a verificação de organização consiga ver a pertença de um utilizador, este tem de clicar em **Grant** (ou **Request**) ao lado de cada organização permitida no ecrã de consentimento OAuth. Se a organização tiver "Restrict third-party OAuth applications" ativado, um proprietário da organização também tem de aprovar a OAuth app uma vez antes de a pertença de qualquer membro se tornar visível.

O Kviklet solicita os scopes `read:user`, `user:email` e `read:org`. Os emails são sempre lidos a partir de `/user/emails` e apenas uma entrada `primary && verified` é aceite, pelo que utilizadores com endereços de email privados ainda conseguem iniciar sessão com sucesso.

#### Outros fornecedores OIDC

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

### LDAP

O Kviklet suporta autenticação LDAP. Para ativar e configurar o LDAP, 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

Veja o que significa cada configuração:

  • LDAP_ENABLED: Defina como true para habilitar a autenticação LDAP.
  • LDAP_URL: A URL do seu servidor LDAP.
  • LDAP_BASE: O DN base para buscas no LDAP.
  • LDAP_PRINCIPAL: O DN do usuário administrador para vinculação ao servidor LDAP.
  • LDAP_PASSWORD: A senha do usuário administrador.
  • LDAP_UNIQUE_IDENTIFIER_ATTRIBUTE: O atributo LDAP usado como identificador único para usuários (padrão: "uid").
  • LDAP_EMAIL_ATTRIBUTE: O atributo LDAP que contém o endereço de e-mail do usuário (padrão: "mail").
  • LDAP_FULL_NAME_ATTRIBUTE: O atributo LDAP que contém o nome completo do usuário (padrão: "cn").
  • LDAP_USER_OU: A Unidade Organizacional (OU) onde as contas de usuário são armazenadas (padrão: "people").
  • LDAP_SEARCH_BASE: Permite substituir o DN base para buscas de usuários (padrão: "ou=people"). Se você usa FreeIPA, pode ser necessário definir isso como, por exemplo, cn=users. Se definido, LDAP_USER_OU é ignorado.

Você pode personalizar esses atributos para corresponder ao seu esquema LDAP. Após configurar o LDAP, os usuários poderão fazer login usando suas credenciais LDAP. Na primeira vez que um usuário LDAP faz login, uma conta de usuário correspondente será criada no Kviklet com permissões padrão. Um administrador precisará atribuir funções apropriadas a esses usuários após o primeiro login.

SAML (somente Enterprise)

O Kviklet suporta autenticação SAML 2.0. Para habilitar o SAML, defina as seguintes variáveis de ambiente:``` SAML_ENABLED=true SAML_ENTITYID=https://your-identity-provider.com SAML_SSOSERVICELOCATION=https://your-identity-provider.com/sso SAML_VERIFICATIONCERTIFICATE=-----BEGIN CERTIFICATE-----\nMIICmzCCAYMCBgF4...\n-----END CERTIFICATE-----

Detalhes de configuração:

- `SAML_ENABLED`: Defina como `true` para habilitar a autenticação SAML
- `SAML_ENTITYID`: O ID da 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 as 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

Seu provedor de identidade deve ser configurado com:

  • Entity ID: https://[kviklet_host]/api/saml2/service-provider-metadata/saml
  • Redirect Uri: https://[kviklet_host]/api/login/saml2/sso/saml

Após configurar o SAML, os usuários podem fazer login através do provedor de identidade. No primeiro login, uma conta de usuário é criada com permissões padrão.

Se você for redirecionado corretamente para o IDP, mas depois receber um erro de cors, você pode adicionar o host do seu IDP às origens permitidas no Kviklet através de:``` CORS_ALLOWEDORIGINS=https://[idp_host]

## Configuração

### Conexões

Depois de 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 os requisitos de revisão e os limites de execução para cada conexão. Consulte [Portões de Revisão](#review-gates) para mais detalhes.

#### AWS IAM AUTH

O Kviklet suporta o uso de IAM Auth para conexões de banco de dados Postgres, MySQL e MariaDB; 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, em vez disso, usará 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 se conectar a bancos de dados que não estão na mesma conta da 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 assumir 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ção para defini-la.

Para aprender como configurar o IAM Auth para o 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 as permissões corretas
- Criar uma política IAM que permita à entidade da AWS gerar tokens para esse usuário

### Portões 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 poderem ser executadas.

O status de aprovação de uma solicitação é calculado com base na última ação de cada revisor. Se um revisor aprovar e depois solicitar alterações, apenas a solicitação de alteração conta — sua 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 reaprovada sem precisar criar uma nova.

Você também pode configurar um limite de **máximo de execuções** por conexão para controlar com que frequência uma única solicitação aprovada pode ser executada. O padrão é 1. Definir 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 Kviklet Enterprise, você pode configurar conexões individuais para exigir aprovações de usuários com funções específicas. Isso permite, por exemplo, exigir aprovação da equipe que mantém um determinado banco de dados ou proteger conexões sensíveis atrás de aprovações de DBA ou da 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 de DBA, 1 de Segurança").

Uma solicitação só é aprovada quando **ambas** as condições são atendidas:

- O número total de aprovações distintas atende a `numTotalRequired`
- Cada requisito de função é individualmente satisfeito

Se um usuário pertence 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 como apenas uma aprovação para a contagem total.

**Exemplo:** Uma conexão requer 3 aprovações totais, incluindo 1 de um DBA e 1 de Segurança. Um usuário que possui tanto a função de DBA quanto a de Segurança aprova — isso satisfaz ambos os requisitos de função, mas conta como apenas 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 aplicados, 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: Default, Admins e Developers.

- A função padrão fornece acesso de Leitura a todas as conexões e Solicitações. Essa função é atribuída a todos os usuários e não pode ser removida. No entanto, você pode alterar as permissões dessa função como quiser.
- Admins têm permissão para criar e editar conexões, bem como adicionar novos Usuários e definir suas permissões.
- Developers podem criar Solicitações, bem como aprová-las e comentá-las e, é claro, executar as instruções propriamente ditas.

Você pode personalizar 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ê tem equipes diferentes com bancos de dados diferentes e deseja 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 acesso de User Read e RoleView e deixar por isso mesmo.
Mais interessante é a adição de permissões individuais para Conexões. Aqui você primeiro adiciona um seletor para selecionar conexões específicas. Isso 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ê também pode, é claro, criar um sistema que use para suas diferentes equipes dentro da sua organização.

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

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

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

- **Habilitar 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 grupos do IdP (mais a função padrão)
  - **Aditivo** - 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; alterações manuais são preservadas depois
- **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 (por exemplo, `engineering`) para funções do Kviklet

#### Configuração OIDC

Configure seu provedor OIDC para incluir uma claim `groups` no token de ID:

- **Keycloak**:

  O Keycloak não inclui grupos nos tokens por padrão, então você precisará adicionar um mapper ao cliente.
  1. Navegue até **Clients** no menu à esquerda
  2. Selecione seu cliente Kviklet
  3. Vá para a aba **Client scopes**
  4. Clique no escopo dedicado (por exemplo, `kviklet-dedicated`)
  5. Vá para a aba **Mappers**
  6. Clique em **Add mapper** → **By configuration**
  7. Selecione **Group Membership**
  8. Configure o mapper:

  | Configuração        | Valor    |
  | ------------------- | -------- |
  | 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. Clique em **Save**

  > **Importante:** O "Token Claim Name" deve corresponder ao "Groups Attribute" configurado nas configurações de Sincronização de Funções do Kviklet (padrão: `groups`).

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

  Se você encontrar problemas, sinta-se à vontade para criar uma 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.

#### Configuração LDAP

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

1. Certifique-se de que seu servidor LDAP tenha o overlay `memberOf` habilitado
2. Defina **Groups Attribute** 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 asserção:

1. Adicione uma declaração de atributo que mapeie as associações de grupo do usuário
2. Defina o **Groups Attribute** 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 Slack App 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 de **Workflow** do Power Automate. O Kviklet envia um Adaptive Card, que o template do webhook publica no seu canal.

**Recomendado: use o template de workflow**

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

**Alternativa: construir o workflow manualmente**

Se você preferir construir o fluxo você mesmo (ou o template não estiver disponível):

1. Canal **...** -> **Workflows** -> crie um fluxo com o gatilho **"When a Teams webhook request is received"**.
2. Adicione a ação **Microsoft Teams -> "Post card in a chat or channel"**.
3. Defina o campo **Adaptive Card** da ação como a expressão `string(triggerBody())` para que ele publique o card que o Kviklet envia.
4. Selecione o Team e o Canal de destino, **Save**, depois copie a **HTTP POST URL** 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 Kubernetes Ingress, 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 observando as solicitaçõ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

Isso garante que todos os links de notificação apontem para o URL público correto.

Telemetria

O Kviklet reporta estatísticas de uso anónimas para nos ajudar a compreender que funcionalidades são utilizadas e onde ocorrem erros. Para a desativar, defina:``` KVIKLET_TELEMETRY_ENABLED=false

O Kviklet registra uma linha na inicialização informando se a telemetria está ativada.

**O que é enviado.** Cada evento carrega um id de instância aleatório (gerado uma vez e armazenado no banco de dados do Kviklet), a URL base pela qual o Kviklet é acessado (veja acima; frequentemente um hostname interno) e a versão do Kviklet. Os usuários são identificados apenas por um id opaco com escopo na instância, de modo que usuários únicos podem ser contados, mas nenhum endereço de e-mail ou nome é jamais enviado. Os eventos exatos e suas propriedades são definidos em `backend/src/main/kotlin/dev/kviklet/kviklet/telemetry/TelemetryEvent.kt`.

**O que nunca é enviado.** Consultas, instruções, resultados, saída de comandos, mensagens de erro, nomes de conexão, hostnames, credenciais, títulos ou descrições de requisições, comentários e nomes de usuários ou funções.

### Logging

Por padrão, o Kviklet grava logs legíveis por humanos (pretty) no stdout, o que é conveniente ao lê-los diretamente ou via `docker logs`.

Se você envia logs para um sistema central (Elasticsearch, Loki, Datadog, CloudWatch, …), pode alternar para **logs JSON** estruturados, que são mais fáceis de indexar e consultar. Defina o formato por meio de uma variável de ambiente:```
# One of: ecs (Elastic Common Schema), logstash, gelf (Graylog)
LOGGING_STRUCTURED_FORMAT_CONSOLE=ecs

Criptografia

Se você não quer que as credenciais sejam armazenadas em texto simples no banco de dados, é recomendável que você habilite 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 clicar. No entanto, se o banco de dados do Kviklet for comprometido de alguma forma, isso é um enorme risco de segurança. Pois ele contém as credenciais de banco de dados para potencialmente todos os seus armazenamentos de dados de produção. Então você pode habilitar 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

O Kviklet criptografará todas as suas credenciais existentes na inicialização e usará o segredo para futuras conexões que você criar.

### Rotação de Chave

Se você quiser rotacionar a chave, basta adicionar outra variável para a chave anterior e alterar a atual:```
ENCRYPTION_KEY_PREVIOUS=some-secret
ENCRYPTION_KEY_CURRENT=another-secret

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

Chaves de API

Kviklet suporta chaves de API para acesso programático ao sistema. Este é um recurso exclusivo da versão enterprise e requer uma licença válida. Você pode criar chaves de API em Configurações -> Chaves de API.

Chaves de API Chaves de API

Use assim:```bash curl --location '[kviklet_host]/api/connections/'
--header 'Authorization: Bearer your-api-key'

As chaves de API herdam as permissões do usuário que as cria. Atualmente, apenas administradores podem gerenciar chaves de API e todas as ações realizadas com uma chave de API são atribuídas ao usuário que criou a chave.

Alguma documentação rudimentar da API pode ser encontrada em `[kviklet_host]/api/swagger-ui/index.html`. Mas tenha em mente que isto é um trabalho em andamento e a API pode mudar em versões futuras.

No final, a verdade está no código, então você pode sempre olhar para o controller para ver como a API está definida. Se você tiver alguma dúvida, sinta-se à vontade para abrir uma issue.

## Funcionalidades Experimentais

Atualmente existem duas funcionalidades experimentais. Elas foram construídas principalmente com base no feedback da comunidade. Sinta-se à vontade para experimentá-las e deixar qualquer contribuição que você possa ter. Esperamos desenvolvê-las mais no futuro e fazê-las funcionar bem com o fluxo de aprovação principal.

### Kubernetes Exec

Se você quiser usar a funcionalidade Kubernetes Exec, você precisa criar uma conexão kubernetes separada. O Kviklet usará o usuário do pod implantado para executar o comando. Portanto, certifique-se de que o usuário tenha as permissões necessárias para executar comandos nos pods que você deseja acessar.

O Kviklet também usa /bin/sh para executar o comando, então você precisará garantir que seus pods tenham um shell ou pelo menos um symlink em /bin/sh. Se isso te incomodar, sinta-se à vontade para abrir uma issue, podemos potencialmente tornar isso configurável ou encontrar outra solução.

Os comandos do Kubernetes aguardam apenas 5 segundos pela saída; se o comando demorar mais do que isso, o Kviklet aguardará até uma hora antes de expirar o comando. Esta é uma solução provisória, estamos investigando websockets para tornar isso mais responsivo e potencialmente habilitar sessões de terminal.

### Proxy - Postgres, MariaDB, MySQL (Enterprise)

Se você criar solicitações para acesso temporário, você pode - em vez de usar a interface web - executar suas consultas através de um proxy gerenciado pelo kviklet e usar o cliente de banco de dados de sua escolha.
O proxy é uma funcionalidade enterprise: ele requer uma licença válida, e um administrador adicionalmente precisa ativá-lo em Configurações -> Geral -> Proxy de Banco de Dados.
Para isso, o contêiner escuta em portas estáveis (5432 e 3306 por padrão, configuráveis via `kviklet.proxy.postgres.port` e `kviklet.proxy.mysql.port`), então você precisa expor essas portas.
Os usuários podem então criar uma solicitação de acesso temporário e clicar em "Iniciar Proxy" assim que ela for aprovada. Cada solicitação recebe um nome de usuário e senha temporários; o Kviklet roteia cada conexão para sua solicitação pelo nome de usuário. Com estes, eles podem se conectar ao banco de dados. O Kviklet valida o usuário e senha temporários e faz proxy de todas as solicitações para o usuário subjacente no banco de dados. Quaisquer instruções executadas são registradas no log de auditoria como se tivessem sido executadas via interface web.

Nota: O proxy atualmente não suporta rastreamento de resultados. Portanto, as instruções executadas são registradas, mas não os resultados ou se uma instrução teve sucesso ou falhou.

![Postgres Proxy](https://assets.kitploit.com/production/public/readmes/7140/153b5b3e85c492079f01f1ffda490a53df2be01cfd808553abc511eb90fc1731.png)
![Postgres Proxy](https://assets.kitploit.com/production/public/readmes/7140/2c886b3cb184b13bbee9120ca5f1cdd9f45dd7743c5cf7a01fe8d5f7474d507a.png)

#### Proxy - TLS

O Kviklet termina a conexão TLS com o banco de dados. Isso significa que, por padrão, qualquer tráfego de e para o proxy em si não é criptografado.  
Se você quiser que o kviklet recriptografe o tráfego, você pode fornecer ao Kviklet um certificado TLS e chave para o proxy definindo as seguintes variáveis de ambiente:```
PROXY_TLS_CERTIFICATE_SOURCE=env
PROXY_TLS_CERTIFICATE_CERT=your-certificate
PROXY_TLS_CERTIFICATE_KEY=your-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

De qualquer forma, o certificado e a chave devem ser armazenados em [formato pem](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail).

## Dúvidas? Contribuições?

Se você tiver alguma dúvida, quiser fornecer feedback ou precisar de ajuda com a configuração, junte-se à nossa [comunidade no Discord](https://discord.gg/7SmPJfeP6e). Você também pode criar uma [issue no GitHub](https://github.com/kviklet/kviklet/issues) para relatar bugs e solicitar recursos.

Se você quiser contribuir, sinta-se à vontade para fazer um fork e criar PRs para coisas pequenas. Se você planeja recursos maiores, eu agradeceria uma discussão prévia em uma issue no GitHub ou no Discord.

Você também pode entrar em contato comigo em [email protected].

Categorias