# 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.

[Image: O separador Chaves de assinatura das definições do sistema]

## 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

1. Garanta que todas as aplicações que fixam um certificado manualmente confiam na chave **seguinte**.
2. Use **Rotate key**. Os novos tokens passam a ser assinados com a nova chave; os tokens mais antigos mantêm-se válidos.
3. 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](https://dts-identity.com/pt/docs/integrations/applications.md) para saber onde se definem as credenciais de uma aplicação.
