Compartilhar via

Girar chaves de assinatura

  • Artigo

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

Pré-requisitos

  • A autoridade de ID verificada é integrada manualmente e as chaves de assinatura estão em sua própria instância do Azure Key Vault. A configuração rápida usa uma chave de assinatura compartilhada, gerenciada pela Microsoft, que você não pode girar por conta própria.
  • O usuário administrador que executa a rotação de chaves deve ter permissão para chaves no cofre de chaves.

Girar as chaves de assinatura

As chaves públicas estão disponíveis no documento de DID (identificador descentralizado) para qualquer pessoa que precise verificar as assinaturas produzidas por um emissor. Para uma autoridade que usa o método did:web, o documento DID está disponível em https://contoso.com/.well-known/did.json, em que 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 coloque o did.json atualizado em vigor.

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 cofre de chaves. Esta 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 valor outOfSync que indica que há uma discrepância entre o Key Vault e o documento did.json disponível publicamente.

    Screenshot that shows a new key in Key Vault.

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

    Screenshot that shows did.json.

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

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

Preciso girar as chaves na ID verificada?

Tecnicamente, você não precisará girar as chaves de assinatura na ID verificada se estiver usando sua própria instância do Key Vault. A chave de assinatura atual não expira. Como acontece com qualquer solução de chave pública/privada, é uma melhor prática girar as chaves periodicamente.

O que acontece quando eu giro a chave de assinatura?

Depois de executar com êxito as etapas 1-4, a ID verificada tem uma nova chave de assinatura e todos os tokens 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 verificada emitidas assinadas por uma chave que não é mais atual continuam funcionando se a chave pública estiver disponível no documento did.json público e a chave não esteja 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 did.json público, qualquer tentativa de verificação falhará porque o verificador não poderá resolver a chave pública usada como assinatura. Há dois cenários sobre os quais você deve estar ciente.

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

Por exemplo, digamos que você tenha 12 chaves no Key Vault e quiser que a ID verificada não carregue as chaves 8 e 9 na lista de chaves. Você precisa desabilitar as chaves 8 e 9 no Key Vault e executar as etapas 2 a 4.

Segundo: neste exemplo, se você girar as chaves 12 vezes, a ID verificada não carregará mais as duas chaves mais antigas. 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 verificada 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 verificada com uma data do término 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. A ID verificada executa mais tarefas quando chama a API /signingKeys/rotate do que apenas girando a chave no Key Vault.

Próximas etapas