About esignering.no
Esignering.no is a generic stand-alone application for signing and authenticating with BankID. It has an assignment-centric design, so every signing happens in context of an assignment (oppdrag).
To get a document signed, you must create an assignment. This is the placeholder for a set of documents and their signees. Once the assignment is created, you can submit documents and add
signers.
Esignering can be integrated both for administrative and signing purposes, but it also has GUI.
For example you could automate creating the assignment, but make the signee sign the documents in our signing portal with custom layout for branding. Otherwise you could integrate the signing inside your own pages.
The model
The model used for creating an assignment is shown below.
There will generated n*m signatures (placeholders for signatures) based on how many documents and signers that are available, i.e. it is expected that all signers should sign every document in assignment.
States
The assignment has a life cycle and can have these states:
NY (new)
The oppdrag may be edited.
You may add and remove signers and documents.
You may request startOppdrag, which will change the state to
KLAR_TIL_SIGNERING
KLAR_TIL_SIGNERING (ready to be signed)
Editing is complete.
Mail has been sent to the signers.
Signing is allowed.
None has yet signed.
You may go back to state NY by requesting stopOppdrag
UNDER_SIGNERING (signing in process)
One or more persons have signed.
But not all.
SIGNERT (signed)
Alle signers have signed.
You may request getSdo.
You may add signers. Then the state will return to UNDER_SIGNERING.
FERDIGBEHANDLET (complete)
The oppdrag is closed for further change.
ARKIVERT (achived)
The oppdrag is archived. This is a separat service.
AVBRUTT
The oppdrag is cancelled. No further state transitons can be done.
Authorization
RESTful service of eSignering utilizes a standard HTTPÂ Basic Authentication or OAuth2 standard HTTP Bearer token Authentication.
Basic authentication:
In order to authenticate your requests you need to add a HTTP header
'Authorization'. Value of it constructed in the following way: 'Basic '+Base64.encode(<user_name>+':'+<password>)
Example: Basic bmVfcm9sZjpldGluZzIzÂ
Bearer token authentication:
In order to authenticate your requests you need to fetch a token from Ambitas authentication REST service. Then add a HTTP header 'Authorization' with value "Bearer <token-fetched-from-authentication>"
Example of value: Bearer 4kkgfua99rudklkowp90
Authentication
This is a short how-to on how to integrate eSignering.no authentication mechanisms into your application.
The authentication service is wrapped around BankID and makes it simple to add BankID login/authentication to your application.
The API
eSignering.no offers a REST API for administration of both signing and authentication. Authentication is the simplest one, so basically the application can order a authentication session and verify the result
after authentication is performed.
Start a session
POST |
|---|
/rest/v1/autentisering |
Query parameters: retur – a call-back url to redirect after authentication (Mandatory) Optional parameters: err – a separate url for error handling fnr – to specify the SSN to expected (will not be asked for). This will guarantee that the authenticated person has such a SSN otherwise the result will be false. height – The height of the BankID client (Default: 300) width – The width of the BankID client (Default: 400) confirm – Should the BankID dialogue ask the user to confirm? (Default: true) understand – Should the BankID dialogue ask the user to click “I understand” (Default: true) Headers: Basic authentication header with your username and password or Bearer token header with token fetched from Ambitas authentication REST service |
Description Creates a authentication session for your user. |
Response: The details on the authentication as JSON Example: {
"retururl": "https://beta.esignering.no/bankid/selector?sid=ac85e47d-7fe8-457b-987b-5cf10c55966a",
"uuid": "ac85e47d-7fe8-457b-987b-5cf10c55966a",
"sid": "ac85e47d-7fe8-457b-987b-5cf10c55966a"
}
The retururl is the gui client (to be embedded or redirected to) The sid is the unique reference to this session, to be used to get the result of the authentication session. |
Embedd the BankID client into your pages
The retururl represents the BankID client, and must be sourced and displayed to your customer. This could be done by redirecting to this url, or to embed it into an iframe or similar to make it look as a
integral part of your application.
The session can be used only ones.
After the last page, the service will redirect to the given call-back URL.
Get the result
GET |
|---|
/rest/v1/autentisering/:sid |
Headers: Basic authentication header with your username and password or Bearer token header with token fetched from Ambitas authentication REST service |
Description: Fetch the result from the authentication session. |
Result: The outcome from the session as json The ok field will specify if the session was successful or not. The name, unique id and fnr (ssn) will be collected if the certificate/user has rights to collect this from the certificate of the user. If there are no rights to see social security number, the birth date is shown instead. |
Variation in usage
As some customers may not have the right to store social security numbers, the solution would be to ask the customer for the ssn in advance to make the authentication process more secure. If you would like the user to be exactly one person/ssn, the setup of the session takes the ssn as input. Then only the given ssn will be legal, hence other authenticated persons will be treated as false.
Signing
Resource: Oppdrag (Assignment)
Method | POST |
|---|---|
URI | /rest/v1/oppdrag |
Parameters | Query Parameters For special cases you can create the whole oppdrag in one post. JSON body (optional): Example { "navn":<name of assignment>, "beskrivelse":<description of assignment>, "purre_perriode_som_dager":<number of days before recurrent mail reminder will be sent>, "layout_id":<ID of a layout assigned to customer organisation/branch>, "sdo":<SDO object's XML>, "signerere":[ { "navn":<signer's name, will appear in email> "offisiell_id":<FNR>, "epost":<signer's email> }] } |
Description | Creates a new oppdrag. If body is added (only for special cases): |
Result | Oppdrag data as JSON (201) Example { "navn": "DLE 22.11/1", "state": "Ikke startet", "uuid": "f700b8d2-6de6-43fe-9577-360e3c3110c7", "opprettet": "2016-11-22T10:12:15.019+01:00", "beskrivelse": "some description and etc", "oppdragstypebeskrivelse": "Vanlig oppdrag med dokumenter og signerere", "layout": "DNB Eiendom AS_", "signerere": [ { "signererUuid": "f9baedbc-f13e-4555-8377-63d48a4ba5cc", "epost": "dle@ambita.com", " "fnr": "12345678901", "signerernavn": "Terje", "signererstate": "Ikke signert" } ] } |
Method | GET |
|---|---|
URI | /rest/v1/oppdrag/:id |
Parameters | |
Description | Retrieves oppdrag with an unique id :uuid |
Result | Oppdrag as JSON |
Method | PUT |
|---|---|
URI | /rest/v1/oppdrag/:id |
Parameters | besk, antall |
Description | Set description (besk). Shown to signers |
Result | Oppdrag as JSON |
Method | POST |
|---|---|
URI | /rest/v1/oppdrag/:id/dokumenter |
Parameters | |
Description | Add a new document to the assignment. Supports multipart form data in body. |
Result | Oppdrag as JSON (201) |
Method | POST |
|---|---|
URI | /rest/v1/oppdrag/:id/signerere |
Parameters | navn, ssn, epost |
Description | Add signer to the assignment. Signer can have email and/or ssn |
Result | Oppdrag som JSON (201) |
Method | PUT |
|---|---|
URI | /rest/v1/oppdrag/:id/start |
Parameters | |
Description | Start the assignment, notification (if email) are sent with links and potential layout |
Result | Oppdrag som JSON |
Method | PUT |
|---|---|
URI | /rest/v1/oppdrag/:id/oppdater |
Parameters | |
Description | Manuelt oppdater alle signeringer |
Result | Oversikt over status på alle signeringer som JSON |
Method | PUT |
|---|---|
URI | /rest/v1/oppdrag/:id/ferdigbehandle |
Parameters | |
Description | Finalise. Creates SDO's for all documents, and changes the state to "Ferdigbehandlet" |
Result | Oppdrag as JSON |
Method | PUT |
|---|---|
URI | /rest/v1/oppdrag/:id/arkiver |
Parameters | |
Description | Archive the assignement |
Result | Oppdrag as JSON |
Method | PUT |
|---|---|
URI | /rest/v1/oppdrag/:id/avbryt |
Parameters | |
Description | Cancel the assignment |
Result | Oppdrag as JSON |
Eksempel på et oppdrag som JSON
{
"beskrivelse": "Et startet oppdrag",
"dokumenter": [
{
"dokumentuuid": "f3b3a645-4d20-4ac5-912c-d7a3ff0c08d4",
"filnavn": "gurba.pdf"
}
],
"navn": "StartetOppdragNavn",
"opprettet": "2013-01-03T01:00:00.000+01:00",
"signerere": [
{
"epost": "terje@test.no",
"fnr": null,
"signererUuid": "2b1fff90-d02b-43e4-b615-625af3168000",
"signerernavn": null,
"signererstate": "Ikke signert"
},
{
"epost": "line@test.no",
"fnr": null,
"signererUuid": "2b1fff90-d02b-43e4-b615-625af3168111",
"signerernavn": null,
"signererstate": "Ikke signert"
}
],
"state": "Klar til signering",
"uuid": "StartetOppdrag"
}
Resource: Dokumenter (Documents)
–
Method | GET |
|---|---|
URI | /rest/v1/dokumenter/:id |
Parameters | |
Description | Get the sdo for document with uuid :dokumentuuid as Base64 |
Result | SDO |
Method | PUT |
|---|---|
URI | /rest/v1/dokumenter/:id |
Parameters | besk: the description |
Description | Set description :besk on dokument with uuid :dokumentuuid |
Result | Dokument as JSON |
Method | DELETE |
|---|---|
URI | /rest/v1/dokumenter/:id |
Parameters | |
Description | Delete a document with uuid |
Result | Oppdrag as JSON |
{“filnavn”: “gurba.txt”, “filtype”: “text/plain”, “filstørrelse”: “2 kB”, “beskrivelse”: “les og bli glad”}
Resource: Signerere (Signers)
Method | GET |
|---|---|
URI | /rest/v1/signerere/:id |
Parameters | |
Description | Get signer with id :id |
Result | Signerer as JSON |
Method | DELETE |
|---|---|
URI | /rest/v1/signerere/:id |
Parameters | |
Description | Delete signer with uuid |
Result | Oppdrag as JSON |
Method | GET |
|---|---|
URI | /rest/v1/signerere/:id/signeringer |
Parameters | |
Description | Get the list of signature holders for signeruuid |
Result | List of signature holders as JSON |
Resource: Handle signing
Method | GET |
|---|---|
URI | /rest/v1/signeringer/:id/sign |
Parameters | Query parameters: retur – a call-back url to redirect after authentication (Mandatory)
Optional parameters: fnr – to specify the SSN to expected (will not be asked for). This will guarantee that the authenticated person has such a SSN otherwise the result will be false. height – The height of the BankID client (Default: 300) width – The width of the BankID client (Default: 400) confirm – Should the BankID dialogue ask the user to confirm? (Default: true) understand – Should the BankID dialogue ask the user to click “I understand” (Default: true)
Headers: Basic authentication header with your username and password or Bearer token header with token fetched from Ambitas authentication REST service |
Description | Get the url to be added to the iframe for signing a document |
Result | URL as JSON |
Method | POST |
|---|---|
URI | /rest/v1/signeringer/signermange |
Parameters | Example body: { "signering_uuid":["fa9204f2-25b5-453b-8072-79da8d9d1d3e","f71bbcdc-af2d-40fd-92ec-c3ae7cfdad0e","6fbc9307-0005-4192-b383-de8a4b51fc31"], "retur":"<the retur url after finished>", "heigth":900, "width":900, "confirm":true, "understand":true } |
Description | Start a session for a chained list of signings. To be used when one person should sign many documents in a sequence |
Result | URL as JSON |
Method | GET |
|---|---|
URI | /rest/v1/signerere/:id/hent |
Parameters | |
Description | Get list of documents that is to be signed by signererUuid. |
List of documents as JSON |
Scenarios
Signing as part of process flow
This scenario is suited for integrating the signing as part of a customer process. Let’s say that the customer should fill in a form and at the end needs to sign it before completing the process by sending the
signed document to the next step.
Step 1: Authenticating using BankID
This is described in the how-to for authentication.
Step2: Fill in the form and produce the content to be signed.
The user is invited to fill out a form with the needed information to generate a document.
The document types supported by esignering.no is plain text, pdf and bidxml.
Step 3: Register the document and present it to the customer for signing.
First we need to create an assignment.
Create the assignment
POST https://beta.esignering.no/rest/v1/oppdrag?navn=Form to sign
Response:
{
"beskrivelse": "Mangler beskrivelse",
"layout": "NewCo",
"navn": "Form to sign",
"oppdragstypebeskrivelse": "Vanlig oppdrag med dokumenter og signerere",
"opprettet": "2016-11-23T21:32:54.743+01:00",
"state": "Ikke startet",
"uuid": "68c80daa-5af9-49a8-b856-6c6263efcb95"
}
Add description and notification interval:
PUT /rest/v1/oppdrag/68c80daa-5af9-49a8-b856-6c6263efcb95?besk=Please
sign this document&antall=2
Response:
{
"beskrivelse": "Please sign this document",
"layout": "NewCO",
"navn": "Form to sign",
"oppdragstypebeskrivelse": "Vanlig oppdrag med dokumenter og signerere",
"opprettet": "2016-11-23T21:32:54.743+01:00",
"state": "Ikke startet",
"uuid": "68c80daa-5af9-49a8-b856-6c6263efcb95"
}
Add document
Add the document key with the file as value:
POST /rest/v1/oppdrag/68c80daa-5af9-49a8-b856-6c6263efcb95/dokumenter
Content-Type: multipart/form-data;
Response:
{
"beskrivelse": "Please sign this document",
"dokumenter": [
{
"dokumentuuid": "769b13dc-f8df-4b2c-ab38-e240b2239ab9",
"filnavn": "How to sign using esignering REST_API_V1.pdf"
}
],
"layout": "DNB Eiendom AS_",
"navn": "Form to sign",
"oppdragstypebeskrivelse": "Vanlig oppdrag med dokumenter og signerere",
"opprettet": "2016-11-23T21:32:54.743+01:00",
"state": "Ikke startet",
"uuid": "68c80daa-5af9-49a8-b856-6c6263efcb95"
}
Add the signer
POST /rest/v1/oppdrag/68c80daa-5af9-49a8-b856-6c6263efcb95/signerere?navn=Kari Normann&fnr=12345678901&epost=kari@example.com
Response:
{
"beskrivelse": "Please sign this document",
"dokumenter": [
{
"dokumentuuid": "769b13dc-f8df-4b2c-ab38-e240b2239ab9",
"filnavn": "How to sign using esignering REST_API_V1.pdf"
}
],
"layout": "NewCo",
"navn": "Form to sign",
"oppdragstypebeskrivelse": "Vanlig oppdrag med dokumenter og signerere",
"opprettet": "2016-11-23T21:32:54.743+01:00",
"signerere": [
{
"epost": "kari@example.com",
"fnr": "12345678901",
"signererUuid": "2181645e-693c-43d2-af19-73cc78478650",
"signerernavn": "Kari Normann",
"signererstate": "Ikke signert"
}
],
"state": "Ikke startet",
"uuid": "68c80daa-5af9-49a8-b856-6c6263efcb95"
}
If email is provided the service will send email automatically, this
would tell the customer to go to a URL (esignering.no) to sign the
assignment. For this scenario email should never be omitted.
Start the assignment:
PUT /rest/v1/oppdrag/68c80daa-5af9-49a8-b856-6c6263efcb95/start
Response:
{
"navn": "Form to sign",
"state": "Klar til signering",
"uuid": "68c80daa-5af9-49a8-b856-6c6263efcb95",
"opprettet": "2016-11-23T21:32:54.743+01:00",
"beskrivelse": "Please sign this document",
"oppdragstypebeskrivelse": "Vanlig oppdrag med dokumenter og signerere",
"layout": "NewCo",
"signerere": [
{
"signererUuid": "2181645e-693c-43d2-af19-73cc78478650",
"epost": "kari@example.com",
"fnr": "12345678901",
"signerernavn": "Kari Normann",
"signererstate": "Ikke signert"
}
],
"dokumenter": [
{
"dokumentuuid": "769b13dc-f8df-4b2c-ab38-e240b2239ab9",
"filnavn": "How to sign using esignering REST_API_V1.pdf"
}
]
}
Get the signature holder
For each signer n and document m the system will have n x m signature
holders.
GET /rest/v1/signerere/2181645e-693c-43d2-af19-73cc78478650/signeringer
Response:
{
"signerere": [{
"state": "Ny",
"signerer_navn": "Kari Normann",
"signerer_epost": "kari@example.com",
"signerer_fnr": "12345678901",
"signing_link":"<https://beta.esignering.no/kunde/login/2181645e-693c-43d2-af19-73cc78478650",>
"dokumentnavn": "How to sign using esignering REST_API_V1.pdf",
"oppdrag_uuid": "68c80daa-5af9-49a8-b856-6c6263efcb95",
"dokumentuuid": "769b13dc-f8df-4b2c-ab38-e240b2239ab9",
"signering_uuid": "d02d9373-55bb-4717-88d5-1ac8557f01e7"
}]
}
As you see in the response the signing link is to be used when signing in the portal. This is not used in this scenario.
Get the url for signing directly
GET /rest/v1/signeringer/d02d9373-55bb-4717-88d5-1ac8557f01e7/sign?retur=<http://www.example.com&height=900&width=600>
Response:
<<https://beta.esignering.no/bankid/selector?sid=4abcc4ab-8795-4a3f-8302-7c9272ace4b3>>
Put the url into a browser and sign
Or into an iframe
The browser loads the BankID client and follow the signing process.
Once the signing process is finished, the customer is sent to the return
URL.
After the signing is completed, you can generate the SEID-SDO for later use.
Finalize the signing process
PUT /rest/v1/oppdrag/68c80daa-5af9-49a8-b856-6c6263efcb95/ferdigbehandle**
Result: Assignment (json) is updated with new state ferdigbehandlet.
Get the SDO
GET /rest/v1/dokumenter/769b13dc-f8df-4b2c-ab38-e240b2239ab9
Response:
{
"filnavn": "How to sign using esignering REST_API_V1.pdf",
"filtype": "application/pdf",
"filstørrelse": "294 kB",
"sdo": "PD94bbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz48U0RPTGlzdCB4bWx+â€
}
Now you have the signed object to continue the process. Congrats!
After that you may archive the assignment
Archive
PUT /rest/v1/oppdrag/68c80daa-5af9-49a8-b856-6c6263efcb95/arkiver
Result: Assignment (json) is updated with new state “arkivertâ€. This means that the documents are stored for the future. This will have a cost per SDO/month.