When implementing a solution that handles official documents, it is of great importance to identify the persons interacting with the software, to ensure the confidentiality of the information. On the other hand, official documents require signatures frequently, so an electronic signing functionality highly improves the user experience.
Choosing the right solution for the aforementioned necessities includes the need for establishing the countries in which the project will be operational, as the implementations for these electronic identification mechanisms can differ from country to country. As we work exclusively with nordic countries, a perfect fit for us was Dokobit, since they provide, for both scenarios, solutions that can be easily integrated.
Their services can be tested by requesting test access tokens for free – separate access tokens are required for electronic identification and electronic document signing.
To identify the persons that would like to interact with our software, we decided to use the embeddable integration of Dokobit’s Identity Gateway, both in the users’ registration process and the login process. Dokobit also offers a redirect based integration, but we wanted to keep our login/registration flow consistent, without the need to redirect the user to another website.
Once we got the test access token for the electronic identification, we first had to make sure that we add the Dokobit Integration script to the bottom of the page (the URL of the script for testing is https://id-sandbox.dokobit.com/js/dokobit-integration.min.js), and a container having id=”Dokobit-identity-container”, where the gateway’s controls will be injected after the session is initialized.
Next, we needed to get a token to be able to initialize the session. This takes us to the back-end, where we had to make a POST request to https://id-sandbox.dokobit.com/api/authentication/create, with the “access_token” URL parameter set to the value of the test access token, and with “origin_host” in the body, set to the URL of our website. This request would return an object containing the “session_token” which will be used to initialize the gateway in the front-end.
After we got the session token from our back-end, we created an instance of DokobitIdentity defined in the dokobit-integration.min.js script. The constructor needs an options object as parameter, where we can provide the sessionToken that we just got from the previously described request, optionally, a locale (two-letter name of the desired language), which will set the gateway’s language to match the site’s language, and a callback function that will be executed after the user successfully logs in with their Electronic ID. A promise is returned from this function, so when resolve is called in the callback function, some additional logic can be executed in the initializeDokobitIdentityGateway(token, locale).then handler.
Following the call of the initializeDokobitIdentityGateway function, the gateway should be initialized in the Dokobit-identity-container, having 3 login methods (for the test access token). For purchased access tokens, there is a possibility to customize the list of login methods, so that only the desired ones are displayed. We will only focus on the Mobile ID login in the next steps.
After the user inputs their phone number, (and social security number, for some countries), they will get a code on their phone which has to be input on the verification screen.
If the code is correct, the callback function provided in the options parameter of the DokobitIdentity constructor will be executed, triggering the .then handler, where we want to check the data of the person that signed in, by calling their API method.
The data returned by Dokobit’s API will contain the personal code (social security number), the person’s country’s code, and their full name. To retrieve this, we executed a GET request to https://id-sandbox.dokobit.com/api/authentication/sessionToken/status from the back-end, with the “access_token” URL parameter set to the value of the test access token and the sessionToken from the URL set to the token that we used to initialize the gateway with, previously. After the request completes, we first need to check its status. If it is not “ok”, then the token is not valid (or it has already been used previously and is expired – only the first GET request executed with a session token will return “ok”, after that, the token will be marked as expired, by having its code set to 1005 – session closed). If the request’s status is “ok”, it means that we got the person’s data, so we can do additional checks to make sure this person can be authorized to log (or register) into our system. From this point, the electronic ID validation is complete, and we have a fully functional integration with Dokobit’s Identity Gateway.
As mentioned before, we also needed a user-friendly solution for document signing, and the one offered by Dokobit was the choice in this case as well.
After getting the test access token for the Documents Gateway, the first step was to upload the document to their server by executing a POST request to https://gateway-sandbox.dokobit.com/api/file/upload.json with the “access_token” URL parameter set to the value of the test access token, and the request’s content set to contain the following data:
- file[name] – the name of the document
- file[digest] – the digest of the document
- file[content] – the document as a byte array encoded in base 64
If the call executes successfully, it will return the token which will be used next to define the data required to enable the signing for the document. To do this, another POST request https://gateway-sandbox.dokobit.com/api/signing/create.json has to be executed with the “access_token” URL parameter set to the value of the test access token, and by providing the following data in the content of the request:
- type – the type of the document (usually pdf, but it can be set to a list of predefined values)
- name – the name of the document
- files[token] – the token returned by the previously described upload request (signing can be defined for multiple documents at once, but we handled only the single document signing)
- postback_url – the URL to which Dokobit will send a POST request each time a signer signs the document
- for each person that needs to sign the document (i is the index of the signer)
- signers[i][id] – the unique identifier (social security number) of the signer
- signers[i][name] – the name of the signer
- signers[i][surname] – the surname of the signer
- signers[i][signing_purpose] – the reason why the signer has been chosen (the value for this field has to be set from a predefined list)
- additional, optional information can be provided about each signer
Details about predefined values and optional information can be found on their official documentation page: https://gateway-sandbox.dokobit.com/api/doc.
Upon successful execution, the response will contain a token for the document’s signing page and a list of tokens mapped to the social security number of each signer, so we can build the “personalized” signing URL for every signer: https://gateway-sandbox.dokobit.com/signing/documentSigningPageToken with the “access_token” URL parameter set to the value of the signer’s token and optionally, the _locale URL parameter set to the two-letter name of the desired language. After the URLs are built, they can be sent to the matching signer in the desired way, for example, by email, and when the signer will click the URL, the Document Gateway will be presented with all the needed information.
In the example presented in the image below, I configured the Test document’s signing with the 2 signers provided by Dokobit as testing data (they have the same names, but different social security numbers), and I gave different signing purposes: signature and acknowledgment.
When the signer opens the Gateway, he needs to input his phone number and social security number (personal code) in the fields from the bottom of the page, and after clicking the SIGN button, they will receive a code on their phone which has to be input on the verification field. If everything is correct, a success page will be presented to the signer:
When the document is successfully signed by someone, Dokobit sends a POST request to the postback_url we provided when creating the Document Gateway session, having set in its body a status with the value “signer_signed” and the download URL of the updated document which will contain the signatures of all signers that already signed it.
When the last signer from the list finished their signing, an additional POST request will be sent to the postback_url, this time with the status “signing_completed”, so additional logic can be implemented, if needed, to handle the completion of the document’s signing process.
And we are done. These steps describe a basic integration for Dokobit’s Identity and Documents Gateways, but with just a few lines of code, we increased significantly our software’s value brought to the user. Dokobit offers lots of configuration options, especially on the Documents Gateway, so the integration can be customized to a lot more detailed level.