Pular para o conteúdo principal

Emitir na máquina do titular

Neste fluxo, o titular emite o próprio certificado na página de emissão do Amplia, que gera o par de chaves no computador dele com o Web PKI: o seu sistema só cria o pedido e envia o titular para a página.

Fluxo​

  1. O seu servidor cria o pedido, com o telefone do titular nos parâmetros.
  2. O seu servidor pede o link de emissão do pedido, GET /api/orders/{id}/issue-link?returnUrl=…, passando a URL para a qual o Amplia volta depois de emitir o certificado. A resposta é o próprio link, uma string JSON como "https://amplia.lacunasoftware.com/issue/{token}?returnUrl={value}".
  3. O titular abre o link. A página de emissão do Amplia envia um código por SMS ao telefone dele, gera o par de chaves com o Web PKI e emite o certificado.
  4. O Amplia devolve o titular para a URL de retorno.

Os samples mostram uma página que redireciona o titular para o link: 

const RETURN_URL = 'http://localhost:3000/issue-cert-user-amplia/complete';

let request = new CreateOrderRequest({
	caId: CONFIG['caId'],
	validityEnd: Util.getTwoYearsFromNowDate(),
	kind: CertificateKinds.PUBLIC_KEY,
	parameters: new PkiBrazilCertificateParameters({
		name: req.body.subjectName,
		cpf: req.body.cpf,
		phoneNumber: req.body.phoneNumber
	})
});
let order = await client.createOrder(request);
let link = await client.getOrderIssueLink(order.getId(), RETURN_URL);
res.render('issue-cert-user-amplia/redirect', {
	redirectLink: link
});

A página de retorno dos samples só avisa o titular de que o certificado foi emitido. Para usar o certificado no seu sistema, leia o pedido quando o titular voltar e busque o certificado só depois que o status do pedido for Issued e ele tiver um certificateId: GET /api/orders/{id} e depois GET /api/v2/certificates/{certificateId}. O Amplia também pode avisar o seu sistema quando o certificado for emitido, por um webhook.

  • O link de emissão contém o segredo do pedido: quem o tiver pode emitir o certificado. Mantenha-o no servidor, nunca o registre no log nem o mostre, e abra-o com um carregamento completo de página na mesma aba.
  • Dê à URL de retorno um token à prova de adulteração e com prazo de validade que identifique o pedido, em vez do id puro do pedido; o token da demo vale uma hora.
  • A demo verifica, antes de criar o pedido, se o navegador do visitante executa o Web PKI, que não roda em celulares nem no Safari para desktop: um pedido criado nesses ambientes nunca poderia ser concluído na página de emissão. O Amplia também permite que os titulares emitam em celulares Android e iOS. TODO(docs): como funciona a emissão no celular.

Em vez de redirecionar o titular você mesmo, você pode fazer o Amplia enviar o link ou mostrar um QR code:

EntregaEndpointO que acontece
E-mailPOST /api/orders/{id}/send-issue-email-requestO Amplia envia ao endereço que está nos parâmetros do pedido (emailAddress) uma mensagem com um botão para o link de emissão e, caso o botão não funcione, o endereço da página de emissão e um código para digitar nela.
SMSPOST /api/orders/{id}/send-issue-sms-request, ou POST /api/v2/orders/{id}/send-issue-sms-request com um corpo {"attemptNumber": …}O Amplia envia o link de emissão por SMS ao telefone que está nos parâmetros do pedido (phoneNumber).
QR codeGET /api/orders/{id}/issue-qrcode-imageDevolve uma imagem PNG de um QR code que leva à página de emissão.
GET /api/orders/{id}/issue-qrcode-dataDevolve, como uma string JSON, a URL que o QR code contém, para você desenhar o código.
GET /api/orders/{id}/issue-qrcode-linkDevolve um link para GET /api/orders/{id}/issue-qrcode, que serve o mesmo PNG sem a chave de API, para uma tag <img>.
  • O e-mail e o SMS mandam o link só para o titular: o seu sistema nunca o vê, então uma aplicação com o papel Agente de Registro pode usá-los, enquanto o link de emissão e o QR code exigem um papel que possa emitir (veja Criar uma aplicação e uma chave de API).
  • Os dois falham se o pedido já foi emitido (OrderAlreadyFulfilled). O e-mail exige um endereço de e-mail no pedido (NoEmailAddress) e o envio de e-mail habilitado na instância (EmailDisabled); o SMS exige um telefone (NoPhoneNumber) e o SMS habilitado (SmsDisabled).
  • O assunto do e-mail é "Link para emissão do seu certificado digital".
  • O QR code contém um endereço …/ic/1/{secret} na instância (ou no gateway de QR code configurado nela), que redireciona para a página de emissão. Como o link de emissão, ele permite que qualquer pessoa que o leia emita o certificado.
  • Das bibliotecas cliente, só o cliente .NET encapsula esses endpoints (SendIssueEmailAsync, SendIssueSmsAsync, GetOrderIssueQRCodeDataAsync, GetOrderIssueQRCodeImageAsync); com as outras, chame-os diretamente, com o header X-Api-Key.
  • E-mails e SMS passam pelos provedores configurados na instância: veja Configuração de envio de e-mails e Configuração de envio de SMS.
  • Em uma instância on-premises, a configuração Amplia__IssueProcedureConfirmationEnabled desliga a confirmação por SMS durante a emissão.
  • TODO(docs): o que attemptNumber muda (a primeira versão do endpoint de SMS envia 0).

Veja também​

Ver em Markdown