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 JWTs (tokens de acesso (Access tokens) e tokens de ID (ID tokens)) e cookies de navegador nas sessões de login (sign-in sessions) do Logto. Essas chaves de assinatura são geradas ao inicializar o banco de dados do Logto (open-source) ou ao criar um novo tenant (Cloud) e podem ser gerenciadas via CLI (open-source), Management APIs ou Console UI.

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

nota:

Teoricamente, as chaves de assinatura não devem ser expostas e não possuem tempo de expiração, ou seja, 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 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 JWT (token de acesso ou token de ID), o token é assinado com a chave privada. Ao mesmo tempo, qualquer aplicativo cliente que recebe um JWT pode usar a chave pública correspondente para verificar a assinatura do token, garantindo que o token não foi adulterado por terceiros. A chave privada é protegida no servidor Logto. A chave pública, como o nome sugere, é pública para todos e pode ser acessada através da interface /oidc/jwks do endpoint OIDC. Um algoritmo de assinatura pode ser especificado ao gerar a chave privada, e o Logto utiliza o algoritmo EC (Curva Elíptica) por padrão. Os usuários administradores podem alterar o algoritmo padrão para RSA (Rivest-Shamir-Adleman) ao rotacionar 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 no navegador. Com esses cookies, o navegador pode solicitar à Experience API do Logto 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 JWTs, os cookies são assinados e verificados apenas pelo próprio serviço OIDC do Logto, não sendo necessárias medidas de criptografia assimétrica. Portanto, não temos pares de chaves públicas para as chaves de assinatura de cookies, nem algoritmos de criptografia assimétrica.

Rotacionar chaves de assinatura pela Console UI

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

1. Navegue até Console > Chaves de assinatura. Lá, 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 as chaves privadas, você tem a opção de alterar o algoritmo de assinatura.

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

   Status	Descrição
   Atual	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 essa 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. No entanto, tokens assinados com essa chave ainda permanecerão válidos.
3. Remover sua chave anterior: Chaves rotuladas como "anterior" 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 Logto para que a nova chave de assinatura tenha efeito.
• 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 consecutivas.

Recursos relacionados

Introdução aos algoritmos de assinatura EC e RSA em JWT