Girar chaves de assinatura

Neste artigo, analisamos as etapas para rotacionar suas chaves de assinatura do ID Verificado do Microsoft Entra.

Pré-requisitos

Girar as chaves de assinatura

As chaves públicas estão disponíveis no documento DID (identificador descentralizado) para qualquer pessoa que precise verificar as assinaturas produzidas por um emissor. Para uma autoridade que utilize o método did:web, o documento DID está disponível em https://contoso.com/.well-known/did.json, onde contoso.com é um exemplo.

A ID verificada não deve começar a assinar usando a nova chave até que uma versão atualizada esteja disponível publicamente no servidor Web. Se você estiver usando uma implantação de várias regiões, talvez com a Rede de Distribuição de Conteúdo do Azure, pode levar algum tempo para que o processo de implantação posicione o did.json atualizado corretamente.

Para ajudar os administradores a executar a rotação de chaves de assinatura sem nenhuma interrupção de serviço, o processo de rotação segue estas etapas:

1. Chame a API signingKeys/rotate para criar uma nova chave de assinatura no Key Vault. O token de acesso na chamada deve ser para um usuário administrador com acesso a chaves no Azure Key Vault. Essa ação define uma nova chave atual no cofre de chaves. A chave anterior é movida para chaves mais antigas, mas ainda pode ser habilitada. A resposta é o objeto JSON de autoridade com o atributo didDocumentStatus tendo um outOfSync valor, o que indica que há uma discrepância entre o Key Vault e o documento disponível did.json publicamente.

   

2. Vá para Configuração no portal de ID Verificada. Selecione Registrar ID Descentralizada e copie ou baixe o arquivo atualizado did.json . Agora ele contém as chaves novas e antigas.

   

3. Substitua did.json em todos os servidores Web em que ele foi implantado anteriormente. Se você editá-lo manualmente, verifique se ele ainda tem sintaxe JSON válida usando uma ferramenta como https://jsonformatter.org/. Antes de continuar, verifique se você pode recuperar o novo did.json documento da Internet com um navegador.

4. Chame a API synchronizeWithDidDocument para começar a usar a nova chave de assinatura. Essa chamada à API valida que o Key Vault e o documento público did.json correspondem. Se corresponderem, a autoridade de ID verificada começará a assinar usando a nova chave no Key Vault. O valor de didDocumentStatus no objeto JSON da autoridade retornada é published. Se o valor ainda estiver outOfSync, haverá uma discrepância entre o Key Vault e o did.json documento e a chave anterior ainda será usada para assinatura.

Preciso rotacionar as chaves na Identidade Verificada?

Tecnicamente, você não precisa girar as chaves de assinatura na Identidade Verificada se estiver usando sua própria instância de Key Vault. A chave de assinatura atual não expira. Assim como acontece com qualquer solução de chave pública/privada, é uma prática recomendada girar as chaves periodicamente.

O que acontece quando eu girar a chave de assinatura?

Depois de executar com êxito as etapas 1 a 4, a ID Verificada tem uma nova chave de assinatura e todos os tokens da Web JSON assinados a partir desse momento são assinados usando a nova chave. Isso significa que solicitações de emissão e apresentação e credenciais emitidas estão sendo assinadas usando a nova chave.

O que acontece com as credenciais assinadas pela chave antiga?

As credenciais de ID verificadas emitidas assinadas por uma chave que não é mais atual continuarão funcionando se a chave pública estiver disponível no documento público did.json e a chave não estiver desabilitada ou excluída no Key Vault.

O que acontece quando as chaves de assinatura antigas não estão mais disponíveis?

Se uma chave usada para assinar uma credencial de ID verificada emitida não estiver no documento público did.json , qualquer tentativa de verificação falhará porque o verificador não poderá resolver a chave pública usada como assinatura. Existem dois cenários dos quais se deve estar ciente.

Primeiro: A ID verificada tem um limite de 10 chaves que podem ser usadas internamente. Elas compõem uma chave atual e nove chaves anteriores. Se o Key Vault contiver 12 chaves, o Verified ID carregará e usará as primeiras dez. Não é possível editar manualmente o did.json documento para adicionar chaves antigas porque isso leva a uma incompatibilidade entre o que a ID verificada carrega e o que o did.json documento contém. A tentativa de chamar synchronizeWithDidDocument nesse caso resulta no didDocumentStatus retorno outOfSync.

Por exemplo, digamos que você tenha 12 chaves no Key Vault e queira que a Identidade Verificada não carregue as chaves 8 e 9 da lista de chaves. Você deve desabilitar as chaves 8 e 9 no Key Vault e executar as etapas 2 a 4.

Segundo: Neste exemplo, se você rotacionar chaves 12 vezes, a ID Verificada não carregará as duas chaves mais antigas novamente. Qualquer credencial de ID verificada emitida usando essas duas chaves não pode mais ser verificada.

Observação

Sua política de rotação de chaves precisa ser coordenada com o tempo de vida das credenciais de ID verificadas emitidas para que as credenciais sejam renovadas ou reemitidas antes que uma chave antiga seja desativada. Um exemplo de uma solução que não funciona é emitir credenciais de ID verificadas com uma data de validade de 12 meses e, ao mesmo tempo, ter uma política de rotação de chaves para girar chaves todos os meses. Essa solução está em apuros nos últimos dois meses do ano porque as chaves antigas não estão mais disponíveis.

Posso girar chaves diretamente no Key Vault em vez de chamar a API de ID Verificada?

Você não deve usar o recurso de rotação no portal de administração do Key Vault. Verified ID executa mais tarefas ao invocar a API /signingKeys/rotate do que apenas girar a chave no Key Vault.

Próximas etapas