Pular para o conteúdo principal

Rotacionar chaves de assinatura (OSS)

nota:

Se você está usando o Logto Cloud, pode rotacionar as chaves de assinatura na interface do Console. Por favor, consulte este tutorial.

O Logto OSS oferece suporte à rotação de chaves de assinatura desde a versão v1.8.

As chaves de assinatura OIDC do Logto, também conhecidas como “chaves privadas OIDC” e “chaves de cookie OIDC”, são as chaves usadas para assinar JWTs (tokens de acesso (Access tokens) e tokens de ID (ID tokens)) e cookies do navegador nas sessões de login do Logto.

Rotacionar suas chaves de assinatura regularmente pode reduzir os riscos de comprometimento potencial das chaves. O Logto recomenda que você rotacione suas chaves de assinatura pelo menos uma vez por ano.

Rotacionar chaves privadas de assinatura OIDC​

Use o comando CLI abaixo para gerar uma nova chave privada de assinatura OIDC. Por padrão, a nova chave entra em vigor imediatamente. Para preparar a rotação e dar tempo para os clientes atualizarem o JWKS antes que a nova chave assine os JWTs, configure um período de carência.

Opções disponíveis:

--type          (Opcional) O algoritmo da chave de assinatura para seus JWTs.
                Os valores são "rsa" ou "ec". O padrão é "ec".
--gracePeriod   (Opcional) Período de carência em segundos para rotação de chave privada preparada.
                O padrão é a variável de ambiente PRIVATE_KEY_ROTATION_GRACE_PERIOD, ou 0 se não definida.
logto db config rotate oidc.privateKeys --type rsa

Por exemplo, para preparar a nova chave privada por 4 horas antes que ela se torne ativa:

logto db config rotate oidc.privateKeys --type rsa --gracePeriod 14400

Você também pode definir o período de carência padrão para rotação de chave privada com uma variável de ambiente:

PRIVATE_KEY_ROTATION_GRACE_PERIOD=14400

Defina esta variável de ambiente no serviço Logto ao rotacionar pelo Admin Console ou Management API, ou no shell onde você executa o comando CLI ao rotacionar pelo CLI.

Use o comando CLI abaixo para gerar uma nova chave de cookie OIDC. A rotação de chave de cookie não suporta período de carência.

logto db config rotate oidc.cookieKeys

E as chaves anteriores?​

Para chaves privadas OIDC, o Logto mantém até três chaves durante a rotação preparada:

  • Next: A nova chave aguardando o término do período de carência.
  • Current: A chave atualmente usada para assinar novos JWTs.
  • Previous: A chave mais recentemente removida, mantida para que os JWTs existentes permaneçam válidos.

Após o período de carência, a chave Next se torna Current, a antiga chave Current se torna Previous e a chave Previous mais antiga é removida.

Para chaves de cookie, o Logto mantém a chave atual e a anterior. Tenha cuidado ao excluir chaves anteriores, pois isso pode causar problemas inesperados. Recomenda-se manter a chave anterior até que você tenha certeza de que todas as sessões ou tokens existentes assinados com ela expiraram.

Solução de problemas​

Usando Logto como Provedor OIDC no Cloudflare Zero Trust​

Se você pretende usar o Logto como provedor OIDC com o Cloudflare Zero Trust, observe que ele não suporta provedores OIDC usando algoritmos ECDSA. Ao rotacionar chaves privadas de assinatura OIDC, certifique-se de usar o algoritmo RSA especificando --type rsa no comando de rotação:

logto db config rotate oidc.privateKeys --type rsa