BrazilTrustServices

O pacote nuget Lacuna.Pki.BrazilTrustServices abstrai a lógica necessária para acessar o certificado digital.

Credenciais

Para utilizar os provedores nas suas aplicações é necessário um ClientID e ClientSecret que são obtidos ao realizar o cadastro da sua aplicação no prestador.

Caso não possua estas credenciais, temos uma página em que é possível realizar este cadastro (disponível apenas para BirdID, SafeID e VIDaaS).

Configuração

Alguns serviços já vem pré-configurados no pacote - BirdId (Vault ID), ViDaaS (VALID), NeoId (Serpro), RemoteId (Certisign) e SafeId (Safeweb).

No caso desses serviços, o processo de configuração se dá como mostrado no código abaixo.

var options = new TrustServicesOptions();

options.Services.Add(new TrustServiceConfig(){
    Service = TrustServiceName.NomeDoServiçoPreconfigurado,
    ClientId = "<Client ID>",
    ClientSecret = "<Client Secret>",
});

var manager = TrustServicesManagerFactory.Create(options);

Já no caso de serviços personalizados, além do Service, ClientId e ClientSecret, o TrustServiceConfig necessita também do Endpoint utilizado para acessar o serviço.

Fora esses campos obrigatórios,TrustServiceConfig também permite a personalização de outras informações como:

Provider: nome do provedor do serviço sendo configurado (opcional)
BadgeUrl: imagem utilizada para diferencial visualmente o serviço (opcional)
ProtocolVariant: protocolo utilizado no tratamento de erros. Essa configuração é recomendada para ambientes de homologação. (opicional)

O código abaixo mostra como realizar a configuração de um serviço personalizado.

var options = new TrustServicesOptions();

options.Services.Add(new TrustServiceConfig(){
    Service = "<Nome do Serviço>",
    ClientId = "<Client ID>",
    ClientSecret = "<Client Secret>",
    Endpoint = "<Endpoint do serviço>",
    Provider = "<Nome do provedor do serviço>",
    BadgeUrl = "<URL da logo do serviço>",
    ProtocolVariant = "<Nome de um dos serviços pré-configurados>",
});

var manager = TrustServicesManagerFactory.Create(options);

O manager, produto final da configuração, implementa a interface ITrustServicesManager. Essa interface define os métodos necessários para obter os certificados digitais em nuvem a serem utilizados nas assinaturas.

Tipos de sessão

Para acessar os certificados é necessário iniciar uma sessão no serviço informando que tipo de autorização você busca, para que o usuário autorize.

Os tipos de sessão disponíveis são:

SingleSignature: permite apenas uma requisição para assinatura de apenas um hash;
MultiSignature: permite apenas uma requisição para assinatura de múltiplos hashes;
SignatureSession: permite várias requisições para várias assinaturas dentro do prazo de validade ou até a revogação pela aplicação ou pelo usuário;
AuthenticationSession: não permite a realização de assinaturas, apenas a autenticação do titular.

Fluxos de autorização

O acesso aos certificados digitais em nuvem podem seguir dois fluxos: OAuth e PWD.

Fluxo PWD

No fluxo PWD, o usuário fornece um código que é enviado para o serviço para autorizar a assinatura. Esse fluxo é composto de dois passos:

Discover: A aplicação buscará em todos os provedores configurados por aqueles que possuem certificado do usuário (identificado pelo CPF ou CNPJ do usuário).

var manager = TrustServicesManagerFactory.Create(options);
// Retirar a pontuação do CPF ou CNPJ.
var plainCpf = Regex.Replace(cpf, "/[.-]/", "");

// Descobre os serviços que contêm certificado vinculado
// ao CPF fornecido. No caso de busca por CNPJ, utilize 
// DiscoverByCnpjAsync.
var services = await manager.DiscoverByCpfAsync(plainCpf);

Authorize: O usuário escolhe qual serviço deseja utilizar e o código de autorização que será enviado para o serviço escolhido autorizar. Se autorizado será retornado o certificado digital.

var manager = TrustServicesManagerFactory.Create(options);
// Retirar a pontuação do CPF ou CNPJ.
var plainCpf = Regex.Replace(cpf, "/[.-]/", "");

// Autoriza a assinatura no servidor utilizando o código
// fornecido pelo usuário.
var passwordAuthorizeResult = await manager.PasswordAuthorizeAsync(
    service, // serviço escolhido pelo usuário
    plainCpf, // CPF do usuário
    password, // código de autorização fornecido
    TrustServiceSessionTypes.SignatureSession);

// Obtém o certificado digital
var certificatesWithKey = await passwordAuthorizeResult.GetCertificatesWithKeyAsync();

Fluxo OAuth

No fluxo OAuth, o usuário é redirecionado para fora da sua aplicação e depois de autorizar a assinatura é redirecionado de volta. Esse fluxo é composto de três passos:

Discover: A aplicação buscará em todos os serviços configurados por aqueles que possuem certificado do usuário (identificado pelo CPF ou CNPJ do usuário).

var manager = TrustServicesManagerFactory.Create(options);
// Retirar a pontuação do CPF ou CNPJ.
var plainCpf = Regex.Replace(cpf, "/[.-]/", "");
// Descobre os serviços que contêm certificado vinculado
// ao CPF fornecido e já inicia o processo de autorização.
// No caso de busca por CNPJ, utilize 
// DiscoverByCnpjAndStartAuthAsync.
var services = await manager.DiscoverByCpfAndStartAuthAsync(
    plainCpf,
    RedirectUrl, // URL de redirecionamento de volta para sua aplicação para retornar após a autorização.
    TrustServiceSessionTypes.SignatureSession,
    fileToSign); // customState - string contendo qualquer informação que deseje recuperar no último passo.

Redirect: Além da lista de provedores que contém aquele CPF ou CNPJ, também será fornecido um URL de redirecionamento para este usuário, onde será feito o processo de autorização do uso do certificado no ambiente do provedor escolhido. O usuário será redirecionado de volta para a aplicação.

Complete: No redirecionamento de volta, serão fornecidos dois parâmetros na URL (query parameters: 'code' e 'state'). Com estes dois valores é possível recuperar o certificado para então completar a assinatura.

var manager = TrustServicesManagerFactory.Create(options);
// Completa autorização
var completeAuthResult = await manager.CompleteAuthAsync(code, state);

// Recupera a informação enviada durante o passo de discover
var fileToSign = completeAuthResult.CustomState;
// Obtém o certificado digital
var certificatesWithKey = await completeAuthResult.GetCertificatesWithKeyAsync();