Quick integration examples

Note: All references to Base64-encoded files or documents are truncated to make this documentation easier to read.

User authentication, query operations

The third application"SAMPLE APP"wants to authenticate a user to query the user data, whose code issample_user.

Previous requirements:

The application must be registered as a client system in Viafirma Fortress
You must have been provided with aclient_id. In this example it will besample_app
You must have been provided with aclient_secret. In this example it will be12345
You must have an allowed return URL configured:http://www.example.com/auth

When the"SAMPLE APP"application wants to authenticate the user against Viafirma Fortress, it will redirect the user to a URL:

{viafirma_fortress_url}/oauth2/v1/auth?
scope=profile&
state=&
redirect_uri=http://www.example.com/auth&
response_type=code&
client_id=sample_app&
user_code=sample_user

In this URL the user will be presented with the different Viafirma Fortress authentication factors in which they are enrolled. You will use one of them to authenticate and authorize the operation. Once the process is finished, Viafirma Fortress will return control to the"SAMPLE APP"application, redirecting to the return URL:http://www.example.com/auth?state=&code=e2470412-33cc-467a-b357-880fe621920f

This URL will be sent as a URL parameter the value of the authorization code, with which you can request an access tokenwith which to operate (e.g. obtain information about the user's status ).

To obtain this access token, the"SAMPLE APP"application will make a request to Viafirma Fortress:

Method: POST
URL: https://fortress.viafirma.com/fortress/oauth2/v1/token
Parameters:
- code: Whose value is the authorization code previously obtained:"e2470412-33cc-467a-b357-880fe621920f"
- client_id: Whose value is the one determined in Viafirma Fortress for the application"SAMPLE APP":"sample_app"
- client_secret: Whose value is the one determined in Viafirma Fortress for the application"SAMPLE APP":"12345"
- redirect_uri: whose value is the return URL for which the authorization request was made:"http://www.example.com/auth"
- grant_type: This value is fixed:"authorization_code"

The result of thisPOSTrequest will be:

{
 "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
 "expires_in": 3920,
 "token_type":"Bearer"
}

Once these values are obtained, we can consider that the user has been correctly authenticated. We can also use the value ofaccess_tokento perform query operations on the Viafirma Fortress API (for example, obtain the user's status, the certificates of a user "scope=CERTIFICATES" or the detail of a certificate "scope=CERTIFICATE").

Signing a PDF document

The third application"SAMPLE APP"wants the usersample_userto sign a PDF document.

Previous requirements:

The application must be registered as a client system in Viafirma Fortress
You must have been provided with aclient_id. In this example it will besample_app
You must have been provided with aclient_secret. In this example it will be12345
You must have an allowed return URL configured:http://www.example.com/sign

Get client token

At the time when the"SAMPLE APP"application wants to start the PDF document signing operation, it must obtain a client system token.

To obtain this access token, the"SAMPLE APP"application will make a request to Viafirma Fortress:

Method:POST
URL:https://fortress.viafirma.com/fortress/oauth2/v1/token
Parameters:
- client_id: Whose value is the one determined in Viafirma Fortress for the application "SAMPLE APP":"sample_app"
- client_secret: Whose value is the one determined in Viafirma Fortress for the application "SAMPLE APP":"12345"
- redirect_uri: whose value is the return URL for which the authorization request was made: "http://www.example.com/auth/response"
- grant_type: This value is fixed: "client_credentials"

https://fortress.viafirma.com/fortress/oauth2/v1/token?
grant_type=client_credentials&
redirect_uri=http://www.example.com/auth/response&
client_id=sample_app&
client_secret =12345

The result of thisPOSTrequest will be:

{
  "access_token":"666b3b58ecb54db784e2eafdfc66e113",
  "expires_in": 3920,
   "token_type":"Bearer"
}

Signature Request

With the access_token resulting from the call, the client system will call the signature method :

Method:POST URL:https://fortress.viafirma.com/fortress/api/v1/signature Request header :Authorization : Bearer 666b3b58ecb54db784e2eafdfc66e113

{
  "userCode":"abcde",
  "redirectUri":"http://localhost:8080/fortress-demo/sign",
  "signatureConfigurations": [
    {
      "signatureType":"PADES_B",
      "signatureAlgorithm":"RSA_SHA256",
      "packaging":"ENVELOPED",
      "document": {
        "name":"example.pdf",
        "bytesB64":"JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPDwgL0xlbmd0aC..."
      },
      "padesConfiguration": {
        "stamper": {
          "csvPath":"http://localhost:7080/fortress/v#",
          "logoB64":"iVBORw0KGgoAAAANSUhEUgA...",
          "page": 1,
          "type":"QR_BARCODE128",
          "xAxis": 80,
          "yAxis": 700
        }
      }
    }
  ]
}

In the body of the method the system must include a json with the following format:

userCode : user code
redirectUri : Uri where you should redirect the operation once it is finished
signatureConfigurations : for each document to be signed, the document, the type of signature and the signing policies must be indicated.

The result of thisPOSTrequest will be:

{
  "authCode":"d8e3d98dc20e46188fd067df28048934",
  "exeCode":"cae2c9fe4f4b41888d42ac18a88096a2"
}

Signature Request Authorization

When the"SAMPLE APP"application wants to begin the signing operation of the PDF document, it will redirect the user to a URL to authorize the signing operation and select the certificate to use:

https://sandbox.viafirma.com/fortress/oauth2/v1/auth?signature_code=7b3e77ad2aef4e479c2ae39f497cfe0c&scope=signature&client_id=fortress-dem&redirect_uri=https%3A%2F%2Fsandbox.viafirma.com%2fortress-demo%2Fsign%2Fresponse

In this URL the user will be presented with the different Viafirma Fortress authentication factors in which they are enrolled. You will use one of them to authenticate and authorize the signing operation. Once authenticated, you will be shown the different certificates that Viafirma Fortress is holding for this user, so you can select which one you want to sign with.

Execute Signature

Once these values are obtained, we can consider that the user has been correctly authenticated and has authorized the signing operation, so the signing service can be called. To do this, a request is made to Viafirma Fortress, including the access token and certificate identifier obtained in the previous step:

HTTP method:POST
URL:https://fortress.viafirma.com/fortress/api/v1/signature/cae2c9fe4f4b41888d42ac18a88096a2/execute Request header :Authorization : Bearer 666b3b58ecb54db784e2eafdfc66e113

The response of this service will be:

{
  "documentB64":"LjMKJcTl8u...",
  "mimeType":"application/pdf",
  "signatureCode":"TFOR-TRES-SOAK-OF1O-TXFR-5151-8007-9109-77"
}

In thedocumentB64attribute we will have the signed document (encoded in Base64), and insignatureCodethe signature identifier.

Signature Extension

With the access_token resulting from the call, the client system will call the extend method:

Method:POST URL:https://fortress.viafirma.com/fortress/api/v1/signature/extend Request header :Authorization : Bearer 666b3b58ecb54db784e2eafdfc66e113

{
  "extendSignatureConfigurations": [
    {
      "document": {
        "bytesB64": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQ...",
        "name": "contrato.pdf"
      },
      "signatureType": "PADES_LTA",
      "signatureAlgorithm": "RSA_SHA256",
      "packaging": "ENVELOPED",
      "tsa": {
        "type": "URL",
        "url": "https://testservices.viafirma.com/via-tsa/tsa"
      }
    }
  ]
}

In the body of the method the system must include a json with the following format:

userCode : user code
redirectUri : Uri where you should redirect the operation once it is finished
extendSignatureConfigurations : for each document to be signed, the document, the type of signature and the signing policies must be indicated.

The result of thisPOSTrequest will be:

{
"ref":"d8e3d98dc20e46188fd067df28048934",
"bytesB64":"MIMBKM8GCSqGSIb3DQEHAqCDASi/MIMBKLoCAQUxDzANBglghkgBZQMEAgEFADCC1QsGCSqGSIb3DQEHAaCC1PwEgtT4JVBERi0xLjMKJcTl8uXrp..."
}

results matching ""

No results matching ""