Chaves de assinatura
Consulte, rode e revogue as chaves que assinam os tokens OIDC e SAML, e perceba porque a rotação é importante para as aplicações ligadas.
A plataforma assina os tokens que emite (ID tokens e access tokens OIDC, bem como as assertions OAuth/OIDC) com uma chave de assinatura privada. As aplicações ligadas verificam essas assinaturas contra a chave pública correspondente, que a plataforma publica no seu endpoint JWKS (/.well-known/jwks). O separador Chaves de assinatura permite-lhe inspecionar, rodar e revogar estas chaves.

Ciclo de vida das chaves
Siga um token: no momento da emissão é assinado com a chave atual e transporta o identificador dessa chave (kid) no seu header. A aplicação lê a kid, procura a chave no key set publicado e verifica a assinatura. O key set contém no máximo três chaves: a que vai assinar a seguir, a que assina agora e a que assinou até à última rotação. Enquanto uma chave se mantiver no set, os tokens que transportam a sua kid são verificáveis; uma chave revogada sai do set e, a partir daí, os seus tokens falham.
O separador Chaves de assinatura mostra estas três chaves com o respetivo estado:
| Estado | Função |
|---|---|
| A seguir na fila | Publicada com antecedência, para que as aplicações já a conheçam quando começar a assinar. |
| Atualmente em utilização | Assina todos os tokens emitidos agora. |
| Anteriormente em utilização | Assinou até à última rotação. Mantém-se no key set, pelo que os tokens que transportam a sua kid continuam verificáveis até que a revogue. |
Cada chave é identificada por um ID da chave (kid), que as aplicações usam para escolher a chave pública correta ao verificar um token. Um badge junto ao ID da chave mostra o tamanho da chave em bits. As chaves geradas de novo são RSA de 3072 bits; as chaves mais antigas de 2048 bits mantêm-se válidas para verificação e vão sendo substituídas pelo tamanho mais robusto à medida que roda.
Consultar e exportar uma chave
Para qualquer chave da lista, abra o menu de ações para:
- Copiar certificado de assinatura para a área de transferência.
- Ver certificado de assinatura e consultar os respetivos detalhes.
- Transferir certificado de assinatura como ficheiro
.pem.
Isto é útil quando uma aplicação precisa do certificado configurado manualmente em vez de o obter do endpoint JWKS.
Porque a rotação é importante
Rodar regularmente as chaves de assinatura limita os danos caso uma chave alguma vez seja comprometida e é um requisito de conformidade frequente. O trabalho que uma rotação implica depende da forma como cada aplicação obteve a chave:
- Um Service Provider SAML ou WS-Federation que confie num único certificado fixado tem de receber o certificado da chave seguinte antes de rodar, caso contrário a sua verificação de assinatura falha depois da mudança.
- Uma aplicação OIDC com uma chave configurada manualmente exige a mesma preparação.
- Uma aplicação que obtém o key set do endpoint JWKS adota a nova chave por si própria, porque o endpoint publica as chaves públicas seguinte, atual e anterior. Para estas aplicações, a rotação acontece sem indisponibilidade.
Nota: A rotação afeta as aplicações OIDC e OAuth. Depois de uma rotação, pode demorar cerca de 30 segundos até a alteração produzir pleno efeito.
Rodar e revogar
As ações encontram-se em Ações destrutivas, no fim da página. Cada uma pede confirmação.
| Ação | O que acontece | Efeito nos tokens existentes |
|---|---|---|
| Rotate key | A chave seguinte passa a atual; a antiga chave atual passa a anterior. Se já existia uma chave anterior, é revogada e passa para a lista de revogações. | A verificação dos tokens já emitidos continua; a chave anterior mantém-se no key set. |
| Rotate & revoke key | Roda como acima e revoga de imediato a chave anterior. | Os tokens que transportam a kid da chave anterior deixam de ser verificáveis. |
| Revoke key | Revoga a chave anterior sem rodar. | Os tokens que transportam a kid dessa chave deixam de ser verificáveis. |
As três revogações mais recentes mantêm-se listadas com a respetiva data, para fins de auditoria.
Sequência recomendada
- Garanta que todas as aplicações que fixam um certificado manualmente confiam na chave seguinte.
- Use Rotate key. Os novos tokens passam a ser assinados com a nova chave; os tokens mais antigos mantêm-se válidos.
- Assim que tiver a certeza de que nenhuma aplicação depende ainda da chave anterior, revogue-a.
Use Rotate & revoke key apenas quando precisar de invalidar de imediato os tokens emitidos anteriormente, por exemplo após uma suspeita de comprometimento de uma chave.
Atenção: Revogar uma chave de que as aplicações ainda dependem quebra a verificação de tokens dessas aplicações. Rode primeiro, confirme que as aplicações mudaram e só depois revogue.
Chaves centrais vs. certificado de assinatura por aplicação
As chaves de assinatura surgem em dois sítios, e não são a mesma coisa:
- As chaves de assinatura centrais desta página assinam todos os ID tokens e access tokens OIDC que a plataforma emite, bem como as Assertions SAML/WS-Federation que produz por predefinição. Uma rotação aqui afeta todas as aplicações que confiam nas chaves publicadas da plataforma.
- Um certificado de assinatura por aplicação pode ser configurado numa aplicação SAML ou WS-Federation individual, quando esse Service Provider espera confiar num certificado específico em vez da chave central da plataforma.
Se um Service Provider comunicar uma falha de assinatura, confirme primeiro em que chave está configurado para confiar: a chave central publicada no endpoint JWKS ou um certificado fixado nessa aplicação em concreto. Consulte Integrações → Aplicações para saber onde se definem as credenciais de uma aplicação.