API security issues

In the majority of cases one may want to insert the web forms provided by docusuit_ in a web environment with independent access control.

As we will see in the following text, to integrate the docusuit_ forms in such an environment will be a breeze!!

With no further action the access to the docusuit_ web form is (potentially) public and it is available to anyone.

One may think that it could be in principle enough to restrict the public access to the pages where the web forms are inserted, and although this may be true for most users we have to take special care with potential hackers that may get hold of the corresponding API keys.

In order to avoid the possibility that an unathorized user, that has got access to the API keys, inserts the web forms generated by docusuit_ in a different website we have established different protection mechanisms:

  • URL referer control: the web forms may not be inserted in a domain not associated with the corresponding API keys.
  • SESSION control: you may control the access through the “SECURE_API” variable.
  • docusuit_ SECRET_API_CODE: that is generated automatically by docusuit_ for each domain.

The first protection mechanism is automatic and it is incorporated in the tool. It checks that the document generation request comes from an authorized domain.

If SECURE_API is set to true in the configuration file (includes/parameters.php) the session control functionality will be activated.

In order to correctly deal with this protection mechanism and take full control of all the session parameters we should distinguish the cases where the web form and document generation requests are generated in the server where docusuit_ is installed or they are coming from an external server.

Requests from the same server

As docusuit_ is written in PHP we are here assuming that the requests are coming from a web page that has been generated with PHP (otherwise you should treat the petitions as coming from an external server).

All docusuit_ requests are processed by api.php. All access control in this case is carried out by the session variable: $_SESSION['docusuit__API']

If this session variable is not set to the web form API key and the “SECURE_API” parameter is set to true the petition will be rejected.

Requests from a different server

If the request is coming from a server other that the one hosting the docusuit_ installation (or from a web page not generated with PHP) we can not count on the session control mechanism described above.

To avoid illegal requests to docusuit_ we should use another secret key (remember that the web form API key needs to be public).

In order to do create this secret key you should:

  • 1. Go to ManageUsers > Manage Api keys
  • 2. Edit the corresponding record or add a new one. Submit.
  • 3. The secret key in the field “Secure API” will be generated automatically.

docusuit_ - Secure API

Now you have to make sure that the scripts that control the remote interaction with docusuit_ shoul includes the “Secure API” key.

The corresponding variable is denoted:

  • PHP: $secure_api
  • JSP and ASP: secure_api