> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Segurança
> Proteja workflows, dados e integrações do Flowker com autenticação pelo Access Manager, credenciais por conexão e TLS gerenciado pelo deploy.
export const GDSL = ({children}) =>
{children}
;
O Flowker protege seus workflows, dados e integrações com autenticação pelo Access Manager e gestão de credenciais por conexão. Seu deploy gerencia o TLS do tráfego de API. Esta página cobre o modelo de segurança como implementado no release atual.
## Autenticação da plataforma
***
O Flowker delega a autenticação da plataforma ao **Access Manager**, habilitado com `PLUGIN_AUTH_ENABLED`. Quando habilitado, cada requisição a uma rota de API protegida deve carregar um Bearer token (OIDC JWT), e cada rota protegida aplica uma permissão por recurso e por ação. É assim que funciona a autorização por papel e por política.
Habilite o Access Manager em produção.
```bash theme={null}
curl -X GET https://your-flowker-instance/v1/workflows \
-H "Authorization: Bearer "
```
**Como funciona:**
* **Access Manager habilitado**: cada requisição a uma rota de API protegida carrega um Bearer token, e cada rota protegida aplica uma permissão por recurso e por ação.
* **Access Manager desabilitado**: os endpoints não exigem autenticação. Quando um Bearer token está presente, o Flowker ainda lê a identidade dele em regime de melhor esforço. O Flowker atribui a requisição ao sujeito declarado. Use esse modo apenas para desenvolvimento local.
* Credenciais inválidas ou ausentes retornam `401 Unauthorized`.
**Exceção das probes de saúde:**
As probes de liveness e readiness não exigem autenticação. Elas servem ao monitoramento de infraestrutura (probes do Kubernetes, balanceadores de carga) e não expõem dados sensíveis.
## Autenticação de provedor
***
Quando o Flowker chama um serviço externo, ele autentica com as credenciais da configuração de provedor pela qual o nó chama. Suas credenciais de plataforma e suas credenciais de provedor ficam separadas.
**Tipos de autenticação aceitos:**
| Tipo | Descrição | Caso de uso |
| ------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `none` | Sem autenticação | Serviços internos atrás de uma VPN ou service mesh |
| `api_key` | API Key enviada como header ou parâmetro de query | APIs de terceiros com acesso por chave |
| `bearer` | Bearer token no header `Authorization` | Serviços que usam tokens estáticos ou pré-gerados |
| `basic` | Autenticação HTTP Basic (username:password) | Sistemas legados ou APIs internas |
| `oidc_client_credentials` | Fluxo OAuth 2.0 de client credentials | Integrações máquina a máquina com provedores de identidade |
| `oidc_user` | Fluxo OAuth 2.0 de token de usuário | Integrações que agem em nome de um usuário específico |
| `oauth2_token_endpoint` | Client credentials OAuth 2.0 contra um token endpoint (sem descoberta OIDC) | Provedores no estilo OAuth2 sem metadados de descoberta OIDC |
| `hmac` | Assinatura de requisição com um secret HMAC compartilhado | Provedores que verificam um header de assinatura da requisição |
O bloco `config.auth` na configuração de provedor guarda a autenticação que o serviço externo exige, como um par `{ type, config }`. O Flowker aplica isso a cada chamada que um nó faz por essa conexão.
O Flowker envia as folhas secretas em `config.auth` (uma API key, bearer token, senha, client secret ou secret HMAC) para o backend de secrets. O Flowker então as remove da configuração persistida. Com a leitura de volta de secrets configurada, uma leitura autorizada da configuração de provedor pode resolvê-las para mostrar. Restrinja essa permissão e trate a resposta dela como sensível.
Qualquer outra coisa que você coloque no documento de configuração (um header, por exemplo) fica com a configuração, e uma leitura pode retorná-la. Coloque cada credencial em `config.auth`.
Para rotacionar um secret, envie o novo valor em uma atualização. Para manter o atual, omita o campo ou envie-o em branco. Isso funciona enquanto `auth.type` continua o mesmo. Uma atualização que muda `auth.type` deve carregar um valor para cada secret que o novo tipo exige e o anterior não exigia. Caso contrário, o Flowker a rejeita com `FLK-0952`. Uma mudança entre dois tipos que usam o mesmo secret, como `oidc_user` para `oidc_client_credentials`, não precisa desse valor de novo.
```json theme={null}
{
"config": {
"auth": {
"type": "bearer",
"config": {
"token": "eyJhbGciOiJSUzI1NiIs..."
}
}
}
}
```
Para fluxos OIDC (`oidc_client_credentials` e `oidc_user`), o Flowker cuida da obtenção e da renovação de token automaticamente. Para `oidc_client_credentials`, informe a URL do issuer, o client ID e o client secret. Para `oidc_user`, informe a URL do issuer, o client ID, o username e a senha. `client_secret` é opcional para clients públicos.
## Segurança de rede
***
**TLS:**
* Configure a terminação TLS para o tráfego de API do Flowker no seu deploy.
* Use URLs base `https://` para chamadas externas. O Flowker aceita uma URI no `base_url` do provedor HTTP genérico. Ele não a restringe a HTTPS.
* Transmita credenciais e payloads sensíveis apenas por conexões criptografadas.
**Configuração de CORS:**
O Flowker aceita configurações de CORS ajustáveis:
* As origens permitidas são configuráveis por deploy
* Requisições cross-origin não podem carregar credenciais (`AllowCredentials` fica desligado)
* O Flowker mantém em cache as respostas de preflight para desempenho
## Resiliência
***
O Flowker protege contra falhas em cascata vindas de serviços externos com os padrões circuit breaker e nova tentativa.
**Circuit breaker:**
Quando um serviço externo falha repetidamente, o circuit breaker abre e para de enviar requisições. Isso evita que seus workflows travem em um provedor que não responde.
* Passa pelos estados `closed` → `open` → `half-open`
* Cada circuito se aplica a uma configuração de provedor e a um tenant, então falhas contra uma conexão não afetam outra
* Você configura os limiares globalmente (falhas consecutivas antes de abrir)
* O estado half-open permite um número limitado de requisições de teste antes de fechar por completo
**Novas tentativas:**
O Flowker resolve o orçamento de tentativas de cada nó com as duas primeiras regras. A classe da falha então decide se esse orçamento é gasto:
1. **Adesão no nó.** Um `retry.max_attempts` maior que `1` liga as novas tentativas seja qual for o método. O valor é a contagem total de tentativas, e a plataforma limita isso a 5. Um `retry.max_attempts` de `1` não é uma adesão. Ele define uma única tentativa.
2. **Método HTTP.** Sem adesão, o Flowker trata `POST` e `PATCH` como não idempotentes e dá a eles uma única tentativa. Cada outro verbo tenta de novo, com 3 tentativas no total por padrão. Isso inclui `GET`, `HEAD`, `OPTIONS`, `PUT` e `DELETE`.
3. **Classe da falha.** O orçamento é gasto apenas em uma falha transitória: um erro de rede, um timeout na tentativa, qualquer status `5xx`, ou status `408` ou `429`. Cada outro `4xx` falha na primeira tentativa por mais alto que seja o orçamento. Um circuito aberto e uma execução cancelada também param o laço. Um corpo de requisição acima do limite de tamanho configurado e um corpo de resposta acima do mesmo limite também o param.
O backoff é exponencial com full jitter. Cada espera é um valor aleatório entre zero e um teto. O teto começa em 1 segundo e dobra a cada tentativa. `retry.backoff_seconds` define o primeiro teto, entre 1 e 60. A espera aleatória evita que muitas execuções tentem de novo o mesmo serviço no mesmo momento.
## O que vem a seguir
***
Aprenda a criar configurações de provedor e conectar serviços externos.
Monitore o Flowker com traces, métricas e logs estruturados.