Chaves de assinatura

As chaves de assinatura OIDC do Logto, também conhecidas como "chaves privadas OIDC" e "chaves de cookie OIDC", são as chaves de assinatura usadas para assinar tokens JWT (tokens de acesso e tokens de ID) e cookies de navegador nas sessões de login do Logto. Essas chaves de assinatura são geradas ao semear o banco de dados do Logto (código aberto) ou ao criar um novo locatário (Cloud) e podem ser gerenciadas através do CLI (código aberto), Management APIs ou Console UI.

Por padrão, o Logto usa o algoritmo de curva elíptica (EC) para gerar assinaturas digitais. No entanto, considerando que os usuários frequentemente precisam verificar assinaturas JWT e muitas ferramentas antigas não suportam o algoritmo EC (apenas suportam RSA), implementamos a funcionalidade para rotacionar chaves privadas e permitir que os usuários escolham o algoritmo de assinatura (incluindo tanto RSA quanto EC). Isso garante compatibilidade com serviços que usam ferramentas de verificação de assinatura desatualizadas.

nota

Teoricamente, as chaves de assinatura não devem ser vazadas e não têm um tempo de expiração, o que significa que não há necessidade de rotacioná-las. No entanto, rotacionar periodicamente a chave de assinatura após um certo período pode aumentar a segurança.

Como funciona?

• Chave privada OIDC Ao inicializar uma instância do Logto, um par de chave pública e chave privada é gerado automaticamente e registrado no provedor OIDC subjacente. Assim, quando o Logto emite um novo token JWT (token de acesso ou token de ID), o token é assinado com a chave privada. Ao mesmo tempo, qualquer aplicativo cliente que receba um token JWT pode usar a chave pública emparelhada para verificar a assinatura do token, a fim de garantir que o token não seja adulterado por terceiros. A chave privada é protegida no servidor Logto. A chave pública, no entanto, como o nome sugere, é pública para todos e pode ser acessada através da interface /oidc/jwks do endpoint OIDC. Um algoritmo de chave de assinatura pode ser especificado ao gerar a chave privada, e o Logto usa o algoritmo EC (Curva Elíptica) por padrão. Os usuários administradores podem mudar o algoritmo padrão para RSA (Rivest-Shamir-Adleman) rotacionando as chaves privadas.
• Chave de cookie OIDC Quando o usuário inicia um fluxo de login ou cadastro, uma "sessão OIDC" será criada no servidor, assim como um conjunto de cookies de navegador. Com esses cookies, o navegador pode solicitar à Logto Experience API para realizar uma série de interações em nome do usuário, como login, cadastro e redefinição de senha. No entanto, ao contrário dos tokens JWT, os cookies são apenas assinados e verificados pelo próprio serviço OIDC do Logto, medidas de criptografia assimétrica não são necessárias. Assim, não temos chaves públicas emparelhadas para chaves de assinatura de cookies, nem algoritmos de criptografia assimétrica.

Rotacionar chaves de assinatura a partir do Console UI

O Logto introduz um recurso de "Rotação de Chaves de Assinatura", que permite criar uma nova chave privada OIDC e chave de cookie em seu locatário.

1. Navegue até Console > Chaves de assinatura. A partir daí, você pode gerenciar tanto as chaves privadas OIDC quanto as chaves de cookie OIDC.

2. Para rotacionar a chave de assinatura, clique no botão "Rotacionar chaves privadas" ou "Rotacionar chaves de cookie". Ao rotacionar chaves privadas, você tem a opção de mudar o algoritmo de assinatura.

3. E você encontrará uma tabela que lista todas as chaves de assinatura em uso. Nota: Você pode excluir a chave anterior, mas não pode excluir a atual.

   Status	Descrição
   Atual	Isso indica que esta chave está atualmente em uso ativo em seus aplicativos e APIs.
   Anterior	Refere-se a uma chave que foi usada anteriormente, mas foi rotacionada. Tokens existentes com esta chave de assinatura permanecem válidos.

Lembre-se de que a rotação envolve as seguintes três ações:

1. Criar uma nova chave de assinatura: Isso exigirá que todos os seus aplicativos e APIs adotem a nova chave de assinatura.
2. Rotacionar a chave atual: A chave existente será designada como "anterior" após a rotação e não será utilizada por novos aplicativos e APIs criados. No entanto, tokens assinados com esta chave ainda permanecerão válidos.
3. Remover sua chave anterior: Chaves rotuladas como "anteriores" serão revogadas e removidas da tabela.

atenção

Nunca rotacione chaves de assinatura consecutivamente (duas ou mais vezes), pois isso pode invalidar TODOS os tokens emitidos.

• Para usuários OSS, após rotacionar a chave de assinatura, é necessário reiniciar a instância do Logto para que a nova chave de assinatura entre em vigor.
• Para usuários Cloud, a nova chave de assinatura entra em vigor imediatamente após a rotação, mas certifique-se de não rotacionar a chave de assinatura várias vezes consecutivamente.