---
title: "Autenticação com certificado - Rest PKI"
description: "Autenticação com certificado digital com o Rest PKI (legado) e o Web PKI, para integrações existentes: inicie a autenticação, assine o token no navegador, conclua e leia o certificado do usuário."
canonical: "https://docs.lacunasoftware.com/articles/rest-pki/certificate-authentication"
locale: "pt-BR"
product: "Rest PKI (legado)"
last_updated: "2026-10-12"
---

# Autenticação com certificado - Rest PKI

> **Aviso: Produto legado**
>
> O Rest PKI é um produto legado: continua recebendo correções de bugs e de segurança, mas novas integrações em nuvem
> devem usar o [Rest PKI Core](https://docs.lacunasoftware.com/articles/rest-pki/core), que também atende à maioria das APIs do Rest PKI. Esta página é para
> integrações existentes com o Rest PKI. Veja a [referência rápida do Rest PKI](https://docs.lacunasoftware.com/articles/rest-pki/quick-reference).

Os usuários entram na sua aplicação com o certificado digital: o [Rest PKI](https://docs.lacunasoftware.com/articles/rest-pki) emite um token de uso único, o
[Web PKI](https://docs.lacunasoftware.com/articles/web-pki) o assina com o certificado do usuário no navegador, e o Rest PKI verifica a assinatura e o certificado. 

O código desta página é do [projeto de exemplos em ASP.NET MVC](https://docs.lacunasoftware.com/articles/rest-pki/dotnet/mvc#auth): C# no servidor, com o `Lacuna.RestPki.Client`
1.24.1, e JavaScript no navegador, com o Web PKI. 

## Fluxo

1. **Servidor**: inicie a autenticação com o contexto de segurança; o Rest PKI devolve um token.
1. **Navegador**: o Web PKI lista os certificados do usuário; quando ele escolhe um, `signWithRestPki()` assina com ele, usando o token.
1. **Servidor**: conclua a autenticação com o token; o Rest PKI devolve os resultados da validação e o certificado do usuário.
1. **Servidor**: se os resultados forem válidos, encontre o seu usuário por um campo do certificado e faça o login dele.

| Etapa | Método do cliente | Endpoint |
|---|---|---|
| Início | `StartWithWebPkiAsync(securityContextId)` | `POST Api/Authentications` |
| Conclusão | `CompleteWithWebPkiAsync(token)` | `POST Api/Authentications/{token}/Finalize` |

## 1. Iniciar a autenticação

O servidor inicia a autenticação e mostra a página com o token, uma string de 22 caracteres, que diferencia maiúsculas de minúsculas e é
segura para URLs. Ele não é o seu token de acesso à API. 

```cs
var auth = Util.GetRestPkiClient().GetAuthentication();
var token = await auth.StartWithWebPkiAsync(Util.GetSecurityContextId());
base.SetNoCacheHeaders();
```

* O token vale para uma única autenticação. O sample envia headers que impedem o navegador de guardar a página em cache, para que o botão
  voltar não mostre uma página com um token já usado. 
* A autenticação precisa ser concluída em até uma hora por padrão; em uma instância on-premises, a configuração
  `TimeToCompleteAuthentications` muda esse prazo (desde o Rest PKI 1.12.6). 
* O contexto de segurança decide quais certificados são aceitos; os samples usam `LacunaTest` nos builds de debug, para aceitar os
  [certificados de teste](https://docs.lacunasoftware.com/articles/pki-guide/test-certs), e `PkiBrazil` nos demais. Veja [Contexto de segurança](https://docs.lacunasoftware.com/articles/rest-pki/validate-signatures#contexto-de-segurança). 
* Para ignorar erros por status de revogação desconhecido, inicie com um `AuthenticationOptions` cujo `IgnoreRevocationStatusUnknown` seja
  `true` (desde o Rest PKI 1.16.0); o sample não faz isso. 

## 2. Assinar o token no navegador

A página guarda o token em um campo oculto, com um `<select>` para os certificados e um botão **Sign In** que não é de envio: o formulário
é enviado por script quando o Web PKI termina. 
O script inicializa o Web PKI com o endpoint do seu Rest PKI em `restPkiUrl`: 

```js
var pki = new LacunaWebPKI(_webPkiLicense);

pki.init({
	ready: loadCertificates,        // As soon as the component is ready we'll load the certificates.
	defaultError: onWebPkiError,    // Generic error callback defined below.
	restPkiUrl: _restPkiEndpoint    // REST PKI endpoint to communication between Web PKI.
});
```

Quando o usuário clica em **Sign In**, o script chama `signWithRestPki()` com o token e o certificado escolhido e depois envia o
formulário: 

```js
var selectedCertThumbprint = formElements.certificateSelect.val();
pki.signWithRestPki({
	token: formElements.token,
	thumbprint: selectedCertThumbprint
}).success(function () {
	formElements.form.submit();
});
```

* `_webPkiLicense` e `_restPkiEndpoint` vêm das configurações `WebPkiLicense` e `RestPkiEndpoint`. `RestPkiEndpoint` só é necessário
  on-premises, e uma licença do Web PKI só para rodar em um host diferente de `localhost`. 
  Veja também [Especificando a URL do Rest PKI](https://docs.lacunasoftware.com/articles/web-pki/customizing-restpki-url).
* O Web PKI troca os dados da assinatura diretamente com o Rest PKI. 

## 3. Concluir a autenticação

De volta ao servidor, conclua a autenticação com o token. Se os resultados não forem válidos, mostre o que falhou; caso contrário, leia o
certificado do usuário: 

```cs
var auth = Util.GetRestPkiClient().GetAuthentication();
var validationResults = await auth.CompleteWithWebPkiAsync(model.Token);

if (!validationResults.IsValid) {
	return View("Failed", validationResults);
}

return View("Success", new AuthenticationInfoModel() {
	UserCert = auth.GetCertificate()
});
```

* O Rest PKI responde HTTP 200 tenha a autenticação dado certo ou não: verifique `IsValid`. `ValidationResults.ToString()` lista todas as
  verificações, e o sample a mostra na página de falha. 
* A conclusão remove a autenticação: uma segunda chamada com o mesmo token falha. 
* Se o navegador não assinou, a conclusão falha com `ClientSignatureNotSet` (HTTP 422). Veja os [códigos de retorno](https://docs.lacunasoftware.com/articles/rest-pki/return-codes). 
* `GetCertificate()` só pode ser chamado depois de um método de conclusão. 

## 4. Fazer o login do usuário

Quando os resultados são válidos, o comentário do sample diz que o certificado é válido segundo o contexto de segurança escolhido no início
e que o usuário é o titular do certificado. Procure o seu usuário por um dos campos do certificado, como `EmailAddress` ou, em certificados ICP-Brasil,
`PkiBrazil.Cpf`; qual campo usar depende da sua aplicação. 

O certificado (`PKCertificate`) tem `SubjectName`, `EmailAddress`, `IssuerName`, `SerialNumber`, `ValidityStart`, `ValidityEnd`,
`ThumbprintSHA256` e, em certificados ICP-Brasil, `PkiBrazil` com `CertificateType`, `Cpf`, `Cnpj`, `Responsavel`, `CompanyName`,
`DateOfBirth` e os campos de RG e OAB. 

TODO(docs): o que o Rest PKI verifica na conclusão, além da confiança no certificado segundo o contexto de segurança.

## Erros

* Quando um limite da conta está definido e é excedido, o Rest PKI responde HTTP 429 com os headers `X-RateLimit-Limit` e
  `X-RateLimit-Remaining`. 
* Para os demais códigos, veja os [códigos de retorno](https://docs.lacunasoftware.com/articles/rest-pki/return-codes) e a [referência rápida](https://docs.lacunasoftware.com/articles/rest-pki/quick-reference).

## Veja também

* [Validar assinaturas](https://docs.lacunasoftware.com/articles/rest-pki/validate-signatures)
* [Projeto de exemplos em ASP.NET MVC](https://docs.lacunasoftware.com/articles/rest-pki/dotnet/mvc#auth)
* [Web PKI](https://docs.lacunasoftware.com/articles/web-pki)

**Demonstrações e exemplos**

- Demonstração: [Your certificates in the browser](https://try.lacunasoftware.com/pt/web-pki/certificates-in-the-browser)
- Authenticate with a digital certificate using Rest PKI: [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/mvc/PkiSuiteAspNetMvcSample/Controllers/AuthenticationRestController.cs) · [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/AuthenticationRestController.java) · [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/authentication-restpki.js) · [PHP](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/php/plain/public/authentication-rest/index.php) · [Python](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/python/flask/sample/views/authentication_rest.py) · [Ruby](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/ruby/rails/app/controllers/authentication_rest_controller.rb)