Gerenciamento de credenciais

Obter seu primeiro token é apenas o começo. Uma vez que um aplicativo OAuth está em produção, suas credenciais precisam ser armazenadas com segurança, rotacionadas ocasionalmente e revogadas rapidamente se algo der errado. Essas são exatamente as perguntas que uma revisão de segurança faz. Esta página cobre os três pontos, além do que um token vazado pode realmente alcançar e o que fazer se houver um vazamento.

Onde um client secret deve ficar

Guarde-o em uma variável de ambiente ou em um gerenciador de segredos (AWS Secrets Manager, Vault, etc.), nunca no controle de versão, e nunca em um arquivo de configuração que seja commitado junto com seu código.
Nunca o inclua dentro de um aplicativo desktop ou de um cliente baseado em navegador. Qualquer coisa instalada na máquina de um usuário ou entregue a um navegador pode ter seu binário ou bundle inspecionado, então qualquer segredo embutido ali deve ser tratado como público a partir do momento em que é lançado.
É exatamente por isso que o fluxo Native Application não emite nenhum client secret: ele foi feito para integrações desktop e CLI que não têm como manter um em sigilo, então depende do PKCE (uma prova por requisição vinculada ao código de autorização) em vez disso. O fluxo Authorization Code + redirecionamento HTTPS personalizado também usa PKCE, e permite adicionar um client secret somente para clientes confidenciais cujo manipulador de redirecionamento roda em um servidor que você controla. Uma implementação apenas no navegador (SPA) desse fluxo deve prescindir do segredo, pelo mesmo motivo que o fluxo Native nunca tem um. Veja Primeiros passos: Escolha um fluxo OAuth.
Client Credentials é um fluxo servidor a servidor e sempre exige um segredo: armazene-o com as mesmas regras de qualquer outra credencial do lado do servidor.

Rotacionando um client secret sem downtime

Regenerar um segredo em Settings → OAuth no seu aplicativo o substitui completamente. Não existe uma janela em que o segredo antigo e o novo sejam válidos ao mesmo tempo: um chamador que ainda apresente o segredo antigo é rejeitado a partir de sua próxima requisição de token ou de refresh.

Isso não significa que toda requisição em andamento falhe no instante em que você rotaciona o segredo. Um token de acesso já emitido continua funcionando até sua própria TTL expirar (cerca de uma hora, veja Ciclo de vida do token), independentemente do que aconteça depois com o segredo que o emitiu originalmente. Somente uma nova requisição de token ou um refresh precisam do novo segredo.

Sequência de troca recomendada:

Regenere o segredo.
Na mesma mudança, atualize todos os lugares onde sua integração armazena o segredo (configuração, gerenciador de segredos, cada instância ou worker) antes que qualquer um deles precise emitir ou renovar um token novamente.
Confirme que as novas requisições de token têm sucesso com o novo segredo.

Se você não conseguir atualizar todas as instâncias de forma atômica, planeje a rotação como um deploy coordenado em vez de um rollout gradual: uma instância que ainda tiver o segredo antigo falha completamente na próxima vez que precisar de um token, em vez de recorrer ao antigo com elegância.

Revogando o acesso

Há duas formas de cortar o acesso, e ambas interrompem o novo acesso:

Revogar uma autorização específica em Settings → Third-party access. O aplicativo deixa de poder renovar ou obter tokens por meio dessa autorização, sem afetar o aplicativo para os demais usuários.
Excluir o aplicativo OAuth em Settings → OAuth. Isso o revoga para todos: nenhum novo token de acesso ou de refresh pode ser emitido para ele, e seu client secret para de funcionar da mesma forma que após uma rotação. Em um aplicativo que usa client credentials, isso também desativa o usuário de serviço do aplicativo na mesma operação.

Revogar uma autorização, excluir o aplicativo e rotacionar seu segredo não afetam um token de acesso já emitido: nenhuma dessas ações força sua expiração. Considere esse token utilizável, com seus escopos originais, até sua própria TTL expirar. Veja Ciclo de vida do token para o panorama completo do que afeta, ou não, um token ativo.

O que um token vazado pode alcançar

Um token vazado não é um vazamento de toda a sua organização: ele é limitado duas vezes, seguindo o modelo de segurança de três camadas:

Seus escopos OAuth (camada 1): fixados no token no momento em que ele foi emitido. Remover um escopo do aplicativo depois não reduz um token já emitido; isso só entra em vigor na próxima vez que o token for renovado ou reemitido.
O acesso a conteúdo e o papel (role) do usuário de serviço (camadas 2 e 3): quais nós (organizações, divisões, sites) o usuário de serviço do token pode ver, e o que ele pode fazer neles. Ao contrário dos escopos, isso não fica fixado no token: é avaliado em relação à sua configuração atual a cada requisição.

A conclusão prática: quanto mais restritos forem o aplicativo e seu usuário de serviço desde o início, menos vale um token vazado.

Após um vazamento suspeito

Siga esta ordem:

Rotacione o client secret imediatamente (Settings → OAuth → seu aplicativo). É a ação mais rápida que você pode tomar, e interrompe imediatamente qualquer nova requisição de token ou de refresh com o segredo antigo.
Exclua o aplicativo OAuth se não pretende continuar usando-o, ou suspeita que o comprometimento vá além de um segredo. Em um aplicativo de client credentials, isso também desativa seu usuário de serviço, cortando completamente a emissão de novos tokens.
Restrinja ou remova o acesso a conteúdo do usuário de serviço. Como o acesso a conteúdo e a papéis (camadas 2-3) é verificado em tempo real em vez de fixado no token, isso reduz imediatamente o que um token vazado ainda válido pode alcançar, mesmo antes de sua TTL expirar.
Trate o token como ativo por mais uma janela de TTL (cerca de uma hora). Nenhuma das etapas acima força a expiração de um token já emitido.
Emita novas credenciais (um novo segredo, ou um novo aplicativo) e atualize sua integração antes de retomar o uso normal.

Próximos passos

Ciclo de vida do token para TTLs, cache e comportamento de refresh
Primeiros passos: Modelo de segurança para ver como escopos, acesso a conteúdo e papéis se encaixam