Selo de estado:
Preview(teto atual do produto) · Curso ACD-210 — Conectores e conexões · Aula 8 de 8 · Atualizado em 2026-10-05.
Objetivo#
Ao final desta aula você vai rotacionar credencial sem quebrar dependentes — sabendo quantos pipelines param, e por que trocar o valor aqui não encerra o risco na origem.
Vídeo#
Identificador no manifesto: acd-210-08-credenciais-e-rotacao · duração-alvo 7 min · tela do produto: /conexoes.
Roteiro de gravação (5 capítulos):
| # | Minutagem-alvo | Capítulo | Tela do produto |
|---|---|---|---|
| 1 | 0:00–1:00 | Abertura: título + selo. Não existe um princípio único para "todas as credenciais": três famílias, três comportamentos. | /conexoes |
| 2 | 1:00–2:30 | Cifra × verificador: o que é hash e o que é AES-256-GCM, e por que a credencial da sua fonte precisa ser recuperável. | /conexoes |
| 3 | 2:30–4:20 | O cartão do cofre: Versão vigente, Rotação, Dependências ("N pipeline(s) param…"). Trocar o valor no cofre. | /conexoes/salva/[id] |
| 4 | 4:20–5:50 | Os três estados de rotação e o botão Já invalidei a antiga na origem. Revogar credencial com a confirmação que conta os dependentes. | /conexoes/salva/[id] |
| 5 | 5:50–7:00 | Cache de 5 minutos, execução em andamento, e o "faça você mesmo". | /dags |
Conteúdo#
Não existe um princípio único para "todas as credenciais"
"O valor aparece uma vez, perder significa gerar outra, a antiga é recusada na hora" é verdade só para as chaves emitidas pelo produto. Uma credencial que o produto precisa usar na sua origem é recuperável por natureza — e "recusar a antiga" depende de alguém revogá-la lá, não aqui.
As três famílias
| Família | O que o sistema faz com o segredo | Exemplos |
|---|---|---|
| 1. Verificadores | Só confere um valor que você apresenta. O guardado é um hash; nem o produto volta ao original | 1a. chave de API de dados (ing_live_…) e service principal (sp_live_…) · 1b. senha de login |
| 2. Credenciais recuperáveis da origem | Precisa usar o valor para autenticar no seu banco/API. Cifrado, e lido de novo na execução | senha, token, chave ou certificado de uma conexão de dados |
| 3. Segredos de assinatura e de cálculo | Precisa do valor para assinar ou calcular algo do produto | segredo de embed, semente TOTP do MFA, chave da conta de serviço do workspace |
Este curso vive na família 2 — e é justamente a família em que "rotacionar" é ambíguo.
Cifra × verificador, em uma tabela
| Credencial | Como fica guardada | Por quê |
|---|---|---|
| Senha de login | verificador (scrypt com sal) | O servidor só confere o que você digita |
| Chave de API (dados) | verificador (SHA-256) + prefixo visível | Você apresenta a chave; o produto só confere |
| Credencial da sua fonte | cifrada (AES-256-GCM) no banco, ou referência a uma versão no cofre | Um hash não autenticaria no seu banco. O processamento precisa do valor |
| Segredo de embed · semente TOTP · chave da conta de serviço | cifrados (AES-256-GCM) | O produto precisa assinar ou calcular com eles |
Para a família 2 há duas possibilidades por conexão: cifrada no banco (o padrão de hoje) ou no cofre externo, com o banco guardando só uma referência. O único cofre suportado é o Google Cloud Secret Manager, e a referência aponta para uma versão numerada — nunca latest.
A troca que não conclui a rotação
O aviso que a tela mostra em toda troca
"Trocar o valor no cofre NÃO conclui a rotação. A credencial anterior continua VÁLIDA na origem (banco, provedor, IAM) até ser invalidada LÁ. Só marque a rotação como concluída depois de revogar a credencial antiga na origem — até lá, considere-a exposta."
Por isso a conexão tem um estado de rotação próprio, visível no cartão do cofre:
| Estado na tela | O que significa |
|---|---|
| Sem rotação registrada | A versão em uso é a original cadastrada |
| Valor trocado no cofre — rotação PENDENTE na origem | Existe versão nova, validada e promovida, mas ninguém confirmou a invalidação na origem. A rotação não acabou |
| Rotação concluída na origem | Alguém com acesso à origem confirmou a revogação lá. Só aqui a rotação terminou |
O botão que fecha o ciclo é literal: Já invalidei a antiga na origem.
O ciclo de troca, na ordem em que acontece
Cada passo só roda se o anterior deu certo, e o relatório da tela mostra cada um:
- garantir o segredo no cofre (idempotente);
- criar a versão nova;
- validar — ler a versão de volta e conferir que os campos são exatamente os esperados;
- promover — a referência passa a apontar para a versão nova;
- invalidar o cache da conexão;
- aposentar a versão anterior — desabilitada, não destruída (janela de rollback e perícia).
Se a validação (passo 3) falhar, nada é promovido: a versão nova é desabilitada e a credencial anterior continua em uso. O passo 6 é o único "melhor esforço" — falhar em aposentar não desfaz uma credencial nova já válida, e o relatório diz que a antiga seguiu habilitada.
Dependentes: quantos pipelines param
O cartão do cofre mostra, ao lado de Versão vigente e Rotação, a linha Dependências: "N pipeline(s) param se esta credencial ficar indisponível" — ou "nenhum pipeline usa esta conexão ainda". É esse número que transforma a rotação em decisão informada. Ao usar Revogar credencial com dependentes, o produto pede confirmação explícita: revogar vai fazer falhar as próximas execuções de N pipelines.
E a revogação é deliberadamente irreversível no sentido útil: ela não volta para a credencial cifrada no banco (isso faria a revogação parecer aplicada sem estar), não reabre a versão anterior e não apaga a versão.
Cache e execuções em andamento
O valor resolvido fica em memória do processo, com validade de 5 minutos, e a chave do cache inclui tenant + conexão + segredo + versão. Promover uma versão nova muda a chave, então o valor antigo não é servido por engano; rotação e revogação invalidam o cache na hora no processo que executou a operação; em outros processos — o executor dos pipelines roda em outro lugar — o teto é a validade de 5 minutos.
A resolução acontece no início da execução. Uma execução que já começou termina com o valor que resolveu; a seguinte resolve de novo e usa a credencial nova — ou falha, se você revogou.
E não existe fallback silencioso: havendo referência de cofre, o cofre é a única fonte. Cofre indisponível ou IAM negado interrompem a execução com mensagem acionável, nunca resolvem para um segredo homônimo ou de outro tenant.
No workspace Aurora Varejo
A senha do banco de vendas da Comércio Aurora apareceu num log. João abre a conexão Vendas — demonstração e lê o cartão: Dependências: 2 pipeline(s) param se esta credencial ficar indisponível. Ele usa Trocar o valor no cofre (versão nova), cola a senha nova e Gravar versão nova no cofre. O estado passa a Valor trocado no cofre — rotação PENDENTE na origem, com o aviso em destaque. João pede ao DBA que revogue a senha antiga no banco; só depois disso ele usa Já invalidei a antiga na origem. Entre as duas coisas, a senha velha continuava funcionando no banco — e o estado da tela dizia isso, em vez de fingir que a rotação havia terminado.
Erros comuns
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| "Troquei a senha e a origem ainda aceita a antiga" | Comportamento esperado | Revogue na origem e então marque a rotação como concluída |
| Execução falhou com "credencial revogada" | A referência está revogada no cofre | Cadastre credencial nova; não há volta para o valor antigo do banco |
| Execução falhou com "cofre indisponível" | Secret Manager fora do ar ou IAM negado | Falha fechada de propósito: nada foi resolvido por aproximação |
| A execução em andamento usou a credencial velha | O segredo é resolvido no início da execução | Esperado; a execução seguinte usa a nova |
| Fonte SaaS falhando depois de alguns dias | Rotação do refresh token OAuth | Reconecte a fonte. Até a onda 15 o produto recusava salvar Bling, Conta Azul e HubSpot por esse motivo; hoje os três aceitam cadastro — confira a coluna Configuração do catálogo em vez de decorar a lista |
| "Quero ver a senha atual" | Não existe | Use Substituir credencial: o campo abre vazio |
| Rotacionei e dois painéis pararam | Dependentes não conferidos antes | Leia a linha Dependências antes de revogar |
Limites inventariados
Um único cofre externo é suportado (Google Cloud Secret Manager) — e, quando ele não está configurado no ambiente, o cartão diz que as ações ficam indisponíveis ali. Não existem códigos de recuperação de MFA nem autoatendimento de troca de senha de login: os dois são caso de suporte. O teto segue Preview.
Faça você mesmo#
No workspace de treino Aurora Varejo, como dono, usando a conexão sintética criada nas aulas 1 e 3.
- Abra a conexão salva (
/conexoes→ cartão da conexão) e localize o cartão do cofre. Leia as quatro linhas: Versão vigente, Campos, Rotação e Dependências. - Anote o número de dependentes — quantos pipelines param se esta credencial ficar indisponível. Se for "nenhum pipeline usa esta conexão ainda", registre isso: é o estado seguro para treinar.
- Expanda Como o cofre funciona aqui e transcreva o item que explica por que o valor não volta para você.
- Se o cofre externo estiver configurado no ambiente, use Trocar o valor no cofre (versão nova), informe uma senha de treino, leia o aviso completo antes de confirmar e use Gravar versão nova no cofre. Se não estiver, transcreva a frase que diz que as ações ficam indisponíveis ali e siga para o passo 6 usando Substituir credencial na ficha da conexão (no assistente, a ação equivalente chama-se Trocar a senha).
- Confirme que o estado de rotação virou Valor trocado no cofre — rotação PENDENTE na origem e que o aviso de que a credencial antiga continua válida na origem está visível.
- Descreva por escrito, em três passos, o que falta para a rotação terminar: revogar na origem, confirmar com Já invalidei a antiga na origem, e só então considerar o risco encerrado.
- Localize o botão Revogar credencial e não clique: anote a frase de confirmação que o produto exibiria, incluindo o número de pipelines que falhariam.
- Classifique três credenciais do seu workspace nas três famílias (ex.: senha do banco da conexão = família 2; chave
ing_live_…= família 1a; semente TOTP = família 3) e diga, para cada uma, se é cifra ou verificador.
Você terminou quando você sabe quantos dependentes a conexão tem, provou na tela que trocar o valor deixa a rotação PENDENTE na origem, e consegue classificar corretamente três credenciais entre as três famílias.
Checagem rápida#
Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.
Documentação relacionada#
- administracao/credenciais-e-rotacao
- suporte/troubleshooting-conexao-credenciais
- data/conectores — por que a rotação de refresh token recusa três conectores
Capacidades ensinadas#
(conceitual — sem capacidade específica da matriz) — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".