BrazilTrustServices

The Lacuna.Pki.BrazilTrustServices nuget package abstracts the logic needed to access the cloud digital certificate.

Credentials

To use the providers in your applications you need a ClientID and a ClientSecret, which you get by registering your application with the provider.

If you don't have these credentials, you can register your application on this page (available only for BirdID, SafeID and VIDaaS).

Configuration

Some services come preconfigured in the package: BirdId (Vault ID), ViDaaS (VALID), NeoId (Serpro), RemoteId (Certisign) and SafeId (Safeweb).

For these services, configure them as in the code below.

var options = new TrustServicesOptions();

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

var manager = TrustServicesManagerFactory.Create(options);

For custom services, besides Service, ClientId and ClientSecret, TrustServiceConfig also needs the Endpoint used to access the service.

Apart from these required fields, TrustServiceConfig also lets you customize other information, such as:

• Provider: name of the provider of the service being configured (optional)
• BadgeUrl: image used to tell the service apart visually (optional)
• ProtocolVariant: protocol used for error handling. This setting is recommended for staging environments. (optional)

The code below shows how to configure a custom service.

var options = new TrustServicesOptions();

options.Services.Add(new TrustServiceConfig(){
    Service = "<Service name>",
    ClientId = "<Client ID>",
    ClientSecret = "<Client Secret>",
    Endpoint = "<Service endpoint>",
    Provider = "<Name of the service provider>",
    BadgeUrl = "<URL of the service logo>",
    ProtocolVariant = "<Name of one of the preconfigured services>",
});

var manager = TrustServicesManagerFactory.Create(options);

The manager, the end product of the configuration, implements the ITrustServicesManager interface. This interface defines the methods needed to get the cloud digital certificates used in the signatures.

Session types

To access the certificates, you start a session on the service stating the type of authorization you need, for the user to authorize.

The available session types are:

• SingleSignature: allows a single request to sign a single hash;

• MultiSignature: allows a single request to sign multiple hashes;

• SignatureSession: allows several requests for several signatures until the session expires or is revoked by the application or by the user;

• AuthenticationSession: does not allow signatures, only authentication of the certificate holder.

Authorization flows

Access to cloud digital certificates can follow two flows: OAuth and PWD.

PWD flow

In the PWD flow, the user provides a code that is sent to the service to authorize the signature. The flow has two steps:

1. Discover: the application searches all configured providers for those that hold a certificate of the user (identified by the user's CPF or CNPJ).

   var manager = TrustServicesManagerFactory.Create(options);
   // Remove the punctuation from the CPF or CNPJ.
   var plainCpf = Regex.Replace(cpf, "[^0-9]", "");
   
   // Discovers the services that have a certificate linked
   // to the given CPF. To search by CNPJ, use
   // DiscoverByCnpjAsync.
   var services = await manager.DiscoverByCpfAsync(plainCpf);

2. Authorize: the user chooses which service to use and enters the authorization code, which is sent to the chosen service for authorization. If authorized, the digital certificate is returned.

   var manager = TrustServicesManagerFactory.Create(options);
   // Remove the punctuation from the CPF or CNPJ.
   var plainCpf = Regex.Replace(cpf, "[^0-9]", "");
   
   // Authorizes the signature on the server with the code
   // provided by the user.
   var passwordAuthorizeResult = await manager.PasswordAuthorizeAsync(
       service, // service chosen by the user
       plainCpf, // the user's CPF
       password, // authorization code provided
       TrustServiceSessionTypes.SignatureSession);
   
   // Gets the digital certificate
   var certificatesWithKey = await passwordAuthorizeResult.GetCertificatesWithKeyAsync();

OAuth flow

In the OAuth flow, the user is redirected out of your application and, after authorizing the signature, redirected back. The flow has three steps:

1. Discover: the application searches all configured services for those that hold a certificate of the user (identified by the user's CPF or CNPJ).

   var manager = TrustServicesManagerFactory.Create(options);
   // Remove the punctuation from the CPF or CNPJ.
   var plainCpf = Regex.Replace(cpf, "[^0-9]", "");
   // Discovers the services that have a certificate linked
   // to the given CPF and starts the authorization process.
   // To search by CNPJ, use
   // DiscoverByCnpjAndStartAuthAsync.
   var services = await manager.DiscoverByCpfAndStartAuthAsync(
       plainCpf,
       RedirectUrl, // URL that brings the user back to your application after the authorization.
       TrustServiceSessionTypes.SignatureSession,
       fileToSign); // customState - a string with any information you want to get back in the last step.

2. Redirect: besides the list of providers that hold a certificate for that CPF or CNPJ, you also get a redirect URL for the user, where the use of the certificate is authorized on the chosen provider's site. The user is then redirected back to the application.

3. Complete: on the way back, two query parameters are added to the URL: 'code' and 'state'. With these two values you can get the certificate and then complete the signature.

   var manager = TrustServicesManagerFactory.Create(options);
   // Completes the authorization
   var completeAuthResult = await manager.CompleteAuthAsync(code, state);
   
   // Gets back the information sent in the discover step
   var fileToSign = completeAuthResult.CustomState;
   // Gets the digital certificate
   var certificatesWithKey = await completeAuthResult.GetCertificatesWithKeyAsync();