Pular para o conteúdo principal

Issue on the holder's machine

In this flow, the holder issues their own certificate on Amplia's issue page, which makes the key pair on their computer with Web PKI: your system only creates the order and sends the holder to the page.

Flow​

  1. Your server creates the order, with the holder's phone number in its parameters.
  2. Your server asks for the order's issue link, GET /api/orders/{id}/issue-link?returnUrl=…, passing the URL that Amplia returns to once the certificate is issued. The response is the link itself, a JSON string such as "https://amplia.lacunasoftware.com/issue/{token}?returnUrl={value}".
  3. The holder opens the link. Amplia's issue page texts a code to their phone, makes the key pair with Web PKI and issues the certificate.
  4. Amplia sends the holder back to the return URL.

The samples render a page that redirects the holder to the 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
});

The samples' return page only tells the holder that the certificate was issued. To use the certificate in your system, read the order when the holder returns, and fetch the certificate only once the order's status is Issued and it has a certificateId: GET /api/orders/{id}, then GET /api/v2/certificates/{certificateId}. Amplia can also notify your system when the certificate is issued, through a webhook.

Keep the issue link safe​

  • The issue link holds the order's secret: anyone who has it can issue the certificate. Keep it on the server, never log or show it, and open it with a full page load in the same tab.
  • Give the return URL a tamper-proof, expiring token that names the order, rather than the bare order id; the demo's token lasts one hour.
  • The demo checks, before creating the order, that the visitor's browser can run Web PKI, which doesn't run on phones or in desktop Safari: an order created there could never be finished on the issue page. Amplia also lets holders issue on Android and iOS phones. TODO(docs): how issuance on a phone works.

Instead of redirecting the holder yourself, you can have Amplia send the link, or show a QR code:

DeliveryEndpointWhat happens
EmailPOST /api/orders/{id}/send-issue-email-requestAmplia emails the address in the order's parameters (emailAddress) a message with a button to the issue link and, in case the button doesn't work, the address of the issue page and a code to type there.
SMSPOST /api/orders/{id}/send-issue-sms-request, or POST /api/v2/orders/{id}/send-issue-sms-request with a body {"attemptNumber": …}Amplia texts the issue link to the phone number in the order's parameters (phoneNumber).
QR codeGET /api/orders/{id}/issue-qrcode-imageReturns a PNG image of a QR code that leads to the issue page.
GET /api/orders/{id}/issue-qrcode-dataReturns, as a JSON string, the URL that the QR code holds, for you to draw the code yourself.
GET /api/orders/{id}/issue-qrcode-linkReturns a link to GET /api/orders/{id}/issue-qrcode, which serves the same PNG without the API key, for an <img> tag.
  • Email and SMS send the link only to the holder: your system never sees it, so an application with the Registration Agent role can use them, while the issue link and the QR code need a role that can issue (see Application roles).
  • Both fail if the order was already issued (OrderAlreadyFulfilled). The email needs an email address in the order (NoEmailAddress) and email enabled on the instance (EmailDisabled); the SMS needs a phone number (NoPhoneNumber) and SMS enabled (SmsDisabled).
  • The email's subject is in Portuguese, "Link para emissão do seu certificado digital".
  • The QR code holds an …/ic/1/{secret} address on the instance (or on the QR code gateway configured for it), which redirects to the issue page. Like the issue link, it lets anyone who reads it issue the certificate.
  • Of the client libraries, only the .NET client wraps these endpoints (SendIssueEmailAsync, SendIssueSmsAsync, GetOrderIssueQRCodeDataAsync, GetOrderIssueQRCodeImageAsync); with the others, call them directly, with the X-Api-Key header.
  • Emails and SMS messages go through the providers configured on the instance: see Configure email and Configure SMS.
  • On an on-premises instance, the Amplia__IssueProcedureConfirmationEnabled setting turns off the SMS confirmation during issuance.
  • TODO(docs): what attemptNumber changes (the first version of the SMS endpoint sends 0).

See also​

View as Markdown