---
title: "BrazilTrustServices"
description: "The Lacuna.Pki.BrazilTrustServices nuget package, which accesses cloud digital certificates: ClientID and ClientSecret credentials and service configuration."
canonical: "https://docs.lacunasoftware.com/en-us/articles/pki-sdk/cloud-certificates/brazil-trust-services"
locale: "en"
product: "PKI SDK"
last_updated: "2026-10-12"
---

# 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](https://demos.lacunasoftware.com/tsp-app-registration)
(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.
```C#
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.
```C#
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).
    ```C#
    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.
    ```C#
    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).
    ```C#
    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.
    ```C#
    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();
    ```