QES

Introduction

ITSME® is a trusted identity provider allowing partners to use verified identities for authentication and authorization on web desktop, mobile web and mobile applications.

The objective of this document is to provide all the information needed to integrate the Sign service. The implementation of the Sign service is based on Oasis Digital Signature Services protocol.

At this moment only the Hash Signing variant is available and documented. In this variant, a remote Signature Creation Application (SCA) will provide the What You See Is What You Sign (WYSIWYS) experience to the User, provide the hash of the data to be signed to the ITSME® service and use the returned digital signature value to format the signature in one of the AdES formats.

Audience

This document is intended to be read by developers of any Signature Creation Application party. Partners who wish to use the ITSME® sign service through an existing SCA should refer to this SCA instead.

Prerequisites

Before you can integrate your application with ITSME® Sign service, you MUST set up a project in the ITSME® B2B portal to obtain all the needed information.

Integrating Sign services

The ITSME® Sign flow goes through the steps shown in the sequence diagram below.

Sequence diagram describing the QES Hash Signing flow

  • The User indicates on your end he wishes to sign a document with ITSME®
  • Your web desktop, mobile web or mobile SCA application sends a request to ITSME® Integration Layer Back-End in order to create the User’s Identification session and obtain the User’s signing certificate to be include in the data to be signed.
  • ITSME® returns the session id and the redirect URL specific to the User to your SCA Back-End.
  • Your SCA Front-End redirects the User to the Integration Layer Front-End of ITSME®, meaning that the User will be identified in the meanwhile (in case the "userCode" is transmitted by the SCA, this step will be skipped as the user will already be identified). If the User has no signature certificate yet, the certificate creation process will be initiated automatically.
  • Finally, when the User is authenticated and has a signature certificate, he is redirected to the your SCA Front-End. The redirection to your SCA Front-End SHOULD be (almost) transparent to the User (with a possible displaying of a spinner) as the laps of time between step 5 and step 11 of this diagram SHOULD be extremely short.
  • Your SCA Back-End contacts the ITSME® Integration Layer Back-End to get the signature certificate of the User.
  • The ITSME® Integration Layer Back-End returns your SCA Back-End the signer information as well as the signature certificate of the User.
  • Your SCA Back-End constructs the data to be signed and the hash of the signature will be computed by yourself. The value of this hash MUST be base64url encoded.
  • Your SCA Back-End will provide the hash to the ITSME® Integration Layer Back-End to request the digital signature value.
  • A session id and redirect URL are returned by ITSME® to your SCA Back-End.
  • Your SCA frontend will then redirect the User to the signature webpage of ITSME®, where he is guided through the ITSME® part of the signing flow.
  • The session of the User at ITSME® side ends as the process is finished and the User is redirected to your SCA Front-End.
  • Your SCA Back-End will contact the ITSME® Integration Layer Back-End to check the signature status.
  • ITSME® then returns the signature completion status and the digital signature value.
  • At this stage, your SCA is able to confirm the success of the operation and display a success message.

Checking ITSME® Sign configuration

Two JSON documents are available to ease the integration of ITSME® sign service:

  • The discovery document
  • The swagger of the B2B interface

Discovery document

To simplify implementations and increase flexibility, the following key-value pairs about ITSME® configuration can be retrieved from a JSON document:

  • the signature policies
  • commitment types
  • supported languages

The JSON document for ITSME® Sign service may be retrieved from https://b2b.sign.itsme.be/qes-partners/1.0.0/.well-known/configuration. Please note we are using SSLMA as authentication method, combined with IP filtering, as specified in SSLMA Authentication. If you need to access the discovery document before setting up the connectivity, you can use the public version here (this one is updated manually, while the previous one is automatically generated): https://belgianmobileid.github.io/slate/qesdiscovery.json

B2B interface swagger

The swagger of the B2B interface (for the back-end to back-end calls) may be retrieved from https://belgianmobileid.github.io/slate/qesB2B.json

Starting a new User identification session

This section relates to the step 2 of the sequence diagram.

First, you will forge a HTTPS POST request that MUST be sent to the ITSME® User Identification Endpoint, which is https://b2b.sign.itsme.be/qes-partners/1.0.0/user_identification. Please note we are using SSLMA as authentication method, combined with IP filtering, as specified in SSLMA Authentication.

Below you will find the mandatory and optional parameters to integrate in the HTTPS POST request body formatted as application/json:

POST /https://b2b.sign.itsme.be/qes-partners/1.0.0/user_identification HTTP/1.1 { "partnerCode":"myClientID", "serviceCode":"myServiceCode", "redirectUrl":"myServiceRedirectUrl", "userCode":"endUserUserCode", "lang":"FR" }
Parameter
partnerCode
String
required
This MUST be the client identifier you received when registering your application during the onboarding process. This parameter will be translated to a label describing the customer for whow the User is signing the document.
userCode
String
optional
The userCode is the unique identifier created by ITSME® for a user connecting with a Service Provider. A user has a different user code at each Service Provider. You SHOULD provide a "userCode" known by ITSME® if you already have authenticated the User who needs to sign the document. Providing a userCode will bypass the identification screen (user won't have to enter his phone number).
serviceCode
String
required
It MUST contain the value "service:service_code", the ITSME® service you want to use as defined for your application during the onboarding process.
lang
String
required
This parameters defines the recommended language to be used for GUI interaction.
redirectUrl
String
required
This is the URL to which the User will be redirected to your remote SCA. This MUST exactly match the redirect URL of the specified service defined when registering your application during the onboarding process.

Capturing the Identification Response

This section relates to the step 3 of the sequence diagram.

Capturing a successful Identification Code

If the User is successfully authenticated and authorizes access to the Identification Request, ITSME® will return a response to your server component. This is achieved by returning an Identification Response to the “redirectUrl” specified previously in the Identification Request.

{ "status": "OK", "asyncRespId": "4kpr55zdi2mk9ns27awgngkltoenfy04gi9b", "identificationUrl": "https://uatmerchant.itsme.be/qes/identify_yourself?language=FR&q=ss4liz8kjk1xxz8taj3nbxae7zqty6eq" }

The response will contain:

Values
status
String
always
It is the status of User Identification Request.
statusReason
String
conditional
It explains the reason of a failure. No reason is given in case the request status is pending or success.
asyncRespId
String
always
This parameter is the identifier of a User identification session.
identificationUrl
String
always
This is the ITSME® URL of the signature welcome page. On this webpage the User will identify himself by entering his mobile phone number.

Handling Error Response

See Appendixes to get more information on the error codes.

Redirecting the end user

This section relates to the step 4 of the sequence diagram.

The next step is to redirect the end user to our Front-End, so that we can process the identification session. You must do that by forging a GET request towards the url specified at previous step, in the parameter identificationUrl.

Requesting the User identification session status

This section relates to the step 6 of the sequence diagram.

By calling the Identification Session Status Endpoint, you are checking the status of the User identification session. This endpoint is https://b2b.sign.itsme.be/qes-partners/1.0.0/user_identification/status. Please note we are using SSLMA as authentication method, combined with IP filtering, as specified in SSLMA Authentication.

Below you will find the mandatory and optional parameters to integrate in the HTTPS POST request body formatted as application/json:

POST /https://b2b.sign.itsme.be/qes-partners/1.0.0/user_identification/status HTTP/1.1 { "partnerCode":"myPartnerCode", "serviceCode":"myServiceCode", "asyncRespID":"4kpr55zdi2mk9ns27awgngkltoenfy04gi9b" }
Values
partnerCode
String
required
This MUST be the client identifier you received when registering your application during the Onboarding. This parameter will be translated to a label describing the customer for whow the User is signing the document.
serviceCode
String
required
It MUST contain the value "service:service_code", the ITSME® service you want to use as defined for your application during the onboarding process.
asyncRespId
String
required
This parameter is the identifier of a User identification session. This value MUST be retrieved from the Identification Response.

Capturing the User identification status info

This section relates to the step 7 of the sequence diagram.

If the Identification Session Status Request has been sucessfully validated we will return an HTTP 200 OK response as in the example aside. In other words, you will get the confirmation that the User can perform a Sign transaction with ITSME® and retrieve the User certificate reference value.

The response body will include the following values:

{ "status": "OK", "userCode": "9o8f04wm1g0bdc8gmgcuxp2ehgn7txh0x2kq", "certificate": "user-certificate" }
Values
status
String
always
It is the status of User Identification Request.
userCode
String
optional
The userCode is the unique identifier created by ITSME® for a user connecting with a Service Provider. A user has a different user code at each Service Provider.
certificate
String
always
The certificate created for the User, under PEM format.

Handling Error Response

See Appendixes to get more information on the error codes.

Starting a new Sign session

In order to intiate the Sign session, you will forge a POST request towards this endpoint: https://b2b.sign.itsme.be/qes-partners/1.0.0/sign_document. Please note we are using SSLMA as authentication method, combined with IP filtering, as specified in SSLMA Authentication.

Below you will find the minimal set of parameters required for processing the HTTPS POST query string:

POST /https://b2b.sign.itsme.be/qes-partners/1.0.0/sign_document HTTP/1.1
{ "inDocs": { "docHash":[ { "di":[ { "alg":"http://www.w3.org/2001/04/xmlenc#sha256", "value":"f4OxZX/x/FO5LcGBSKHWXfwtSx+j1ncoSt3SABJtkGk=" } ], "id":"ContractCar20180914u89236456.pdf" } ] }, "reqID": "ReqID4va0acsef3mv5ft1dp71", "asyncRespID": null, "optInp": { "lang": "FR", "ITSME®": { "signer": { "userCode": "9o8f04wm1g0bdc8gmgcuxp2ehgn7txh0x2kq" }, "partnerCode": "myPartnerCode", "serviceCode": "myServiceCode", "description": [ { "lang": "EN", "value": "Car insurance contract" }, { "lang": "FR", "value": "Contrat d'assurance voiture" }, { "lang": "NL", "value": "Contract verzekering auto" }, { "lang": "DE", "value": "Kfz-Versicherungsvertrag" } ], "redirectUrl": "myServiceRedirectUrl", "signPolicy": { "signPolicyRef": "ITSME®_DEFAULT", "commitmentTypeRef":"1.2.840.113549.1.9.16.6.5", "signerRole": [ { "lang": "EN", "value": "General Manager" }, { "lang": "FR", "value": "Gestionnaire" }, { "lang": "NL", "value": "Zaakvoerder" }, { "lang": "DE", "value": "Manager" } ] } } } }
Values
inDocs
String
Required
This contains the element to be signed.
docHash
String
Required
This parameter defines the list of hashes to be signed by ITSME®, one item per hash.
id
String
Required
This is the ID of the hash(es) to be signed. You SHOULD provide us this information when registering your application during the onboarding process. Currently, only single hash signing is allowed.
di
Array
Required
This is the Table of hashes to be signed during the signature process.
alg
String
Required
Only the SHA256 algorithm is supported. See http://www.w3.org/2001/04/xmlenc#sha256 for more information.
value
Array
Required
This is the hash to be signed during the signature flow. The value of the hash computed must be given in Base64.
reqID
String
Required
This is the ID of the request that you transfer.
asyncRespId
String
Required
This parameter is the identifier of a User identification session. This value can be retrieved from the values obtained in the Identification Response. In case no "asyncRespID" is given in the request, a new session is created.
optInp
String
Required
Those are additional information needed for the signature request.
lang
String
Required
This parameters defines the recommended language to be used for GUI interaction. If the parameter is not defined in the request, then the language that will be used is the one of the cookie. This defaults to the language used in the browser if there is no cookie.
ITSME®
String
Required
This parameter contains all the information related to ITSME® context.
signer
DssISigner
Required
This is all the information that allows identification of the User in itsme.
partnerCode
String
Required
This MUST be the client identifier you received when registering your application during the onboarding process. This parameter will be translated to a label describing the customer for whow the User is signing the document.
serviceCode
String
Required
It MUST contain the value "service:service_code", the ITSME® service you want to use as defined for your application during the onboarding process.
redirectUrl
String
Required
This is the URL to which the User will be redirected to your remote SCA. This MUST exactly match the redirect URL of the specified service defined when registering your application during the onboarding process.
signPolicy
String
Required
This is the object of the Signature policy to be used during the Signature. This parameter contains all the information related to the signature policy.
signPolicyRef
String
Required
This defines the reference of the signature policy to be used during ITSME® Signing flow. In case no specific signature policy is applicable for that specific use case, the ITSME® generic qualified signature policy SHOULD be used. The signature policy has to be indicated in the SCA Front-End to the User. The list of available codes can be retrieved from the JSON document.
The signature policies used SHOULD be defined during the onboarding process. It is up to you to choose your signature policies within the list given by itsme. If you want to add new signature policies to your list, please ask the ITSME® Onboarding team.
commitmentTypeRef
String
Required
This defines the reference of the commitment type to be used during ITSME® Signing flow. This parameter is used to display (in the ITSME® App) the commitment type of the signature to the User. There is no commitment type by default. If the parameter is not given by the SCA, then nothing is displayed in the ITSME® App. You SHOULD use a code that corresponds to a specific commitment type. The list of available codes can be retrieved from the JSON document.
The commitment types used SHOULD be defined during the onboarding process. It is up to you to choose your commitment types within the list given by itsme. If you want to add new commitment types to your list, please ask the ITSME® Onboarding team.
signerRole
Array
Required
This defines the role of the signer. This information is displayed in the ITSME® App to show to the signer under which role he will sign the document. If no signer role is provided nothing will be displayed in the ITSME® App. This parameter is optional and freely defined in a free text of maximum 50 characters by yourself. You SHOULD provide this free text in all supported languages. The characters used to define the Signer Role MUST be ISO-8859-1 compatible. The signer role SHOULD be provided in all languages supported by itsme.

Managing the Sign Response

Getting a successful Sign Response

If the Sign Request has been sucessfully validated we will return an HTTP 200 OK response as in the example aside.

The response body will include the following values:

{ "result": { "maj": "urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:resultmajor:Pending" }, "reqID": "ReqID4va0acsef3mv5ft1dp71", "respID": "hjg3ngu3tvvv71k9qg1vyokc2mwmqgqk43iv", "optOutp": { "ITSME®": { "signingUrl": "https://uatmerchant.itsme.be/qes/prove_its_you_poka?q=34u5jh2dltb1xhsu0g4bshnlziycdhow&language=FR" } } }
Values
result
String
always
This is the status of the request (pending, success or failure).
maj
String
always
This is a general message that will give the status of the request, pending, success or error. In case of failure, the root cause is given.
min
String
always
This is a specific message that, in case of failure, identifies the root cause of the failure.
msg
String
always
This indicates the origin of the error.
reqID
String
always
This is the ID of the request that you transfer.
asyncRespId
String
always
This parameter is the identifier of a User identification session.
optOutp
String
always
Those are additional information needed for the signature request.
ITSME®
String
always
This value contains all the information related to ITSME® context.
signigUrl
String
always
This signing URL is the link to redirect the User from the SCA frontend to the ITSME® Signing Page.
userCode
String
always
An identifier for the User, unique among all ITSME® accounts and never reused. Use "userCode" in the application as the unique-identifier key for the User.
sigObj
Array
always
This is the signature object. Currently this is the hash to be signed.

Handling Error Response

See Appendixes to get more information on the error codes.

Redirecting the end user

The next step is to redirect the end user to our Front-End, so that we can process the identification session. You must do that by forging a GET request towards the url specified at previous step, in the parameter signingUrl.

Requesting the Sign session status

This request has to be created in order to get the information about the Sign session. In order to do so, you will forge a POST request towards https://b2b.sign.itsme.be/qes-partners/1.0.0/sign_document. Please note we are using SSLMA as authentication method, combined with IP filtering, as specified in SSLMA Authentication.

Below you will find the minimal set of parameters required for processing the HTTPS POST query string:

POST https://b2b.sign.itsme.be/qes-partners/1.0.0/sign_document HTTP/1.1 { “inDocs”: null, “reqID”: “ReqIDv1prg8pmn9mtive3otsc”, “asyncRespID”: “b99a7d03acb94ea5a4d972aa31bb1c36”,   ”optInp”: { “ITSME®”: { “partnerCode”:“myPartnerCode”, “serviceCode”:“myServiceCode” }   } }

Parameter
inDocs
String
required
This MUST be 'null'.
reqID
String
required
This is the ID of the request that you provide to us.
asyncRespId
String
optional
This parameter is the identifier of a User identification session. This value can be retrieved from the values obtained in the Identification Response. In case no "asyncRespID" is given in the request, a new session is created.
optInp
Json
required
Those are additional information needed for the signature request.
ITSME®
Json
required
This parameter contains all the information related to ITSME® context.
partnerCode
String
required
This MUST be the client identifier you received when registering your application during the onboarding process. This parameter will be translated to a label describing the customer for whow the User is signing the document.
serviceCode
String
required
It MUST contain the value "service:service_code", the ITSME® service you want to use as defined for your application during the onboarding process.

Managing the Sign Status Response

Getting a successful Sign Status Response

HTTP 200
{ "result": { "maj": "urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:resultmajor:Pending" }, "reqID": "ReqIDv1prg8pmn9mtive3otsc", "respID": "8lycz0t07bh1q8nz41fcwg21s9k8jd217vtp", "optOutp": { "ITSME®": { "signingUrl": "http://itsme.labo.sixdots.be/qes/index.php?q=gjs57sq7w72eme0yg9ufufdfae98bcj6" } } }
Parameter
result
String
always
This is the Oasis DSS compliant status of the sign session
reqID
String
always
This is the ID of the request that you provide to us.
respId
String
always
Needs to be reused later to check status of signature as asyncRespID value.
optOutput
String
always
Those are additional information needed for the signature request.
ITSME®
Json
always
This parameter contains all the information related to ITSME® context.
signingUrl
Json
always
signingUrl is the link where you must redirect the end user. He will receive there BMID instructions and poka yoke code

Handling Error Response

See Appendixes to get more information on the error codes.

Appendixes

Handling Error Response

If one of the above request is invalid or unauthorized an error code will be returned to the User using the appropriate HTTPS status code, as listed in the table below:

Status code
400 Returned in case of invalid Request Object.
409 Returned in case the User identification flow has been interrupted.
500 Internal Server Error.

The Error Response will contain the “status” and the statusReason value. The following table describes the various error types that can be returned in the statusReason value of the error response:

Error
NO_REQUEST user_identification is a POST service. A body SHOULD be inserted into the request. For more information on the structure of this request, you can go to the section related to /user_identification.
MISSING_PARTNER_CODE In this case, the body request does not contain the field "partnerCode". This field corresponds to the "Partner Code/Client ID" referenced in your onboarding file.
MISSING_SERVICE_CODE The body request does not contain the field "serviceCode". This field corresponds to the "Service Code" referenced in your onboarding file.
INVALID_URL The field "redirectUrl" is null or its syntax is not correct, URL is invalid. This field corresponds to the "Redirect URL" referenced in your onboarding file.
INVALID_REQUESTOR The "partnerCode" and/or "serviceCode" referenced into the body do not reference an existing partner and/or service. The "partnerCode" corresponds to the "Partner Code/Client ID" referenced in your onboarding file. The "serviceCode" corresponds to the "Service Code" referenced in your onboarding file for a SIGN service.
UNAUTHORIZED_URL The partner and its service have been correctly found by ITSME® following referenced "partnerCode" and "serviceCode", but the given "redirectUrl" is not authorized for the partner and/or service mentioned. You did not provide a valid redirectUrl. The "redirectUrl" used here corresponds to the "Redirect URL" referenced in your onboarding file.
INVALID_LANG The "lang" field does not reference a language supported by itsme. You can consult "BMID Well-Known Configuration" to check which are the languages supported by ITSME®, /well-known/configuration.
UNEXPECTED_ERROR An error occurred during the validation of partner information. You SHOULD try again later. If the error persists, then you SHOULD contact ITSME® support team for investigation.
UNKNOWN An unknown error occurred during the request. You SHOULD contact ITSME® support team for investigation.
PENDING The User Identification Session you created is pending. The User is currently following the User Identification flow at ITSME® side (web and mobile).
REJECTED The User had to create a certificate in order to make a signature. However, he rejected his CREATE_CERT action in the ITSME® App. A new User Identification session must be initialized. During that session, User has to confirm the CREATE_CERT action.
EXPIRED The User had to create a certificate in order to make a signature. However, he waited too long (more than three minutes) before confirming his CREATE_CERT action in the ITSME® App and his action expired. A new User Identification Session must be initialized. During that session, User has to confirm the CREATE_CERT action in time.
UNEXPECTED_ERROR An unexpected error occurred during User’s Identification flow. You SHOULD try again later. If the error persists, then you SHOULD contact ITSME® support team for investigation.

SSLMA Authentication

We make use of SSLMA Authentication with our b2b interface https://b2b.sign.itsme.be/qes-partners/1.0.0. This means that the SSL certificate you present upon each call towards this interface must be the one whitelisted in our systems as part of the onboarding process. We combine this authentication with IP filtering, meaning that we need to whitelist the IP address of your server. This is also part of the onboarding process.