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 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 vazadas 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 (OIDC private key) 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 JWT (token de acesso ou token de ID), o token é assinado com a chave privada. Enquanto isso, 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 chave 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 (OIDC cookie key) 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 à 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 > Configurações do tenant > Configurações OIDC. 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. Para chaves privadas OIDC, você pode excluir a chave anterior, mas não pode excluir a chave atual ou a próxima. Para chaves de cookie OIDC, você pode excluir a chave anterior, mas não pode excluir a chave atual.

   Status	Descrição
   Próxima (Next)	Este status é usado para rotação de chave privada OIDC em estágio. A chave foi criada, mas o Logto não a usará para assinar novos JWTs até que o período de carência termine e a chave se torne efetiva.
   Atual (Current)	Indica que esta chave está sendo usada atualmente pelo Logto para assinar novos JWTs ou cookies.
   Anterior (Previous)	Refere-se a uma chave que foi usada anteriormente, mas foi rotacionada. JWTs ou cookies existentes assinados com essa chave permanecem válidos até expirarem ou a chave ser excluída.

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

1. Criar uma nova chave de assinatura: Para chaves privadas OIDC, o Logto pode preparar a nova chave como "Próxima (Next)" primeiro, para que seus aplicativos e APIs tenham tempo de atualizar a chave pública do endpoint /oidc/jwks antes que a nova chave seja usada para assinatura.
2. Rotacionar a chave atual: Quando a rotação se torna efetiva, a chave "Próxima (Next)" se torna "Atual (Current)", e a chave "Atual (Current)" existente se torna "Anterior (Previous)". Tokens assinados com a chave anterior ainda permanecerão válidos.
3. Remover a chave anterior mais antiga: O Logto mantém no máximo uma chave privada "Anterior (Previous)". Se já existir uma chave privada anterior quando a chave em estágio se tornar atual, a chave anterior mais antiga será removida.

Para o Logto Cloud, a rotação da chave privada OIDC entra em vigor após um período de carência de 4 horas. Durante esse período, a nova chave é preparada e exposta via JWKS antes que o Logto comece a assinar novos JWTs com ela. Na tabela do Console, a coluna Efetiva em (Effective at) mostra quando uma chave "Próxima (Next)" em estágio se tornará "Atual (Current)".

Para implantações OSS self-hosted, o período de carência padrão para rotação de chave privada é de 0 segundos, o que significa que a rotação é imediata. Para usar rotação em estágio, defina a variável de ambiente PRIVATE_KEY_ROTATION_GRACE_PERIOD no serviço Logto, ou passe um valor explícito de rotationGracePeriod no corpo da requisição ao chamar o endpoint da Management API POST /api/configs/oidc/private-keys/rotate.

atenção:

Evite rotacionar as chaves de assinatura repetidamente antes que a rotação pendente se torne efetiva, a menos que você queira substituir intencionalmente a chave "Próxima (Next)" em estágio.

Excluir a única chave "Anterior (Previous)" muito cedo pode invalidar JWTs ou cookies existentes que foram assinados com essa chave.

Recursos relacionados

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