Back-end integration

Workflow Description

Workflow of identification is pretty simple:

• User requests access to an operation which demands identification (for example, on your website).
• Website shows a dialog with QR code (format and content are below).
• User starts a mobile application (with Mob.id SDK library inside) to scan QR code.
  • QR code is converted to an operation which starts the identification process on the smartphone.
  • Identification process is finished successfully.
  • mob.id sends identification results and user data to your software to a specified endpoint (for example, REST request with JSON).
  • Your software parsing received data and got the information about the user and his current information.
• The operation proceeds further according to your business logic.

QR Code Requirements

QR Code description is here: https://en.wikipedia.org/wiki/QR_code
You can generate your own QR-code with Mob.id service. 

QR Code body should have this format (JSON document):

{

}

So mobile application can scan QR code and run simple checks:

1. QR code is correct
2. QR code contains JSON
3. JSON has fields mentioned above
4. JSON has correct types of that fields (i.e. values are strings)
5. Header has correct value (above)
6. Command is the one of: REGISTER, LOGIN, CONFIRM, AGE_VERIFICATION
7. OrgId and SubOrgId have values of your company
8. Data64 is not empty
9. Data64 has base64 format (you should not decode binary data inside)

If any of these checks fail, this means that QR code does not belong to your web-site or it is wrong.

The picture of QR code can be received with Mob.id service by URL according these rules:

 

GET	HTTP method
https://	The protocol
<orgId>.api.mob.id:	Domain name for your organization
<qr code service port>	Port of QR Code service (ex: 9013)
/api/v1/qrcodes	URL prefix of QR Code service
/<command>	Command (list is above)
?session=<session id>	Session Id – unique id of your client web page generated by FE/BE of your organization, for example random int or current UNIX timestamp, etc. Session Id allows making a match between a web page and request from Mob.id BE to your BE after the user was identified successfully.
&token=<access token>	Secret access token
&size=<needed size>	Needed size of the picture in pixels (ex: 400, 600)

 

For example:

https://myorg.api.mob.id:9013/api/v1/qrcodes/register?session=1234567890&token=secret-token&size=400

According to the latest Chrome security rules, it is recommended that your BE will get this picture and transfer it to your FE to show QR code on a web page.

Customer Software Synchronization Endpoint

The goal of this endpoint is to get notification that some operation is started by a relevant user.

Sample login workflow can be like this:

1. User wants to login on your website using Mob.id.
2. Web site asks your BE to create a temporary data object with TTL 10 minutes and these fields:
   • operationId – unique id of this data object – filled by BE
     • It plays as bridge between web site and identification process
   • operationName – name of the operation: LOGIN – filled by FE
   • additional information (if needed) – filled by FE
3. Your BE creates that data object and returns the operationId to the web site.
4. QR code is received by BE and transferred to the website together with operationId or as a separate request to BE. The picture can be embedded into the web page if needed.

Example of embedding a Base64 encoded image into HTML:

<img src = "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==" alt="Red dot" />

1. Website receives QR code and shows it in a dialog for the User.
2. Website starts an idle thread to check operation status by operationId every 5 seconds.
   1. Long polling requests are better – BE load is less.
   2. BE responses are:
      1. WAITING – still waiting for identification process ends
      2. SUCCESS – operation succeed
      3. FAIL – operation failed
      4. TIMEOUT – TTL of data object is exceeds (or not exists), data object is deleted, the entire operation should be canceled andQR code dialog should be closed
3. When the identification process on the smartphone is finished successfully, the callback endpoint is called and BE receives the status with operationId. User information is transferred together with status.
4. BE finds the user auth info in its own database by user info from callback.
5. Temporary data object is marked with successful status on the BE side and with user auth info.
6. Website receives successful status for this operationId in idle thread together with user auth info.
7. Current operation on the website is assumed authenticated and can proceed.
8. Website terminates the idle thread.

Customer Software Account Endpoint

The goal for this endpoint is to receive the internal user information you need during registration. This goal is accomplished using the Mob.id services installed on the server. 

The first step for the user is to install the app on his phone. Then the user consents in authenticating his legal identity (passport or ID card). After consenting the user is asked to present his passport/ID-card to his phone and a picture is taken automatically. Then the user is asked to place the phone on the passport or ID-card and the NFC is read. After the user has made a selfie to verify if the right user is present at that time, this data is sent to the Mob.id back-end for verification of the authenticity and integrity. When everything checks out, an attest is generated holding all this data and stored on the phone of the user for re-use and proof the legal identity is authentic and not compromised and during registration the user was actually present. for liveness detection When a User creates a derived identity (i.e. identity for your company only, with needed fields), we fill the derived identity with user id received from your system.

The first step for the organization is to define a specific derived identity for the organization. See “Data structures”. This derived identity is unique to the user and the organization. The derived identity will contain attributes the organization needs to onboard the person. 

When the user requests access for the first time to login using the QR code the user is asked consent to share curtain information with the organization. When consented the pre-defined attributes will be collected and if needed the user will input attributes manually on his phone and security features can be added like liveness check to verify the user is genuinely present at that time. When collection is finished, it will be sent to the backend of the organization. The organization will onboard the person using its own Customer Due Diligence policies and processes. 

When verification is successful and the organization consents, it provides access to the user. All the necessary attributes are collected, including the organization specific attributes, like customer number or account number or fingerprints, etc and stored securely on the phone of the user. The user can from then on use the credentials to access the organization’s infrastructure using his derived identity stored on his phone.

Derived identity can contain these types of fields: 

• documentType,
• documentCode,
• issuingState,
• primaryIdentifier,
• secondaryIdentifier,
• nationality,
• documentNumber,
• dateOfBirth,
• gender,
• photo,
• dateOfExpiry

Assuming, these fields should be enough to find this into your system.

So, when user want to scan QR code and run some operation which demands an identification, this data will be send to your endpoint:

BankAccountRequest:

    String derivedIdentityId – unique identifier of the user in Mob.id (GUID)

    String sessionId – unique user session id from QR code

    String data – additional data

    List<PassportField> passportFields – list of Passport Fields

    List<CustomField> customFields – list of Custom Fields

    PassportVerificationData passportVerificationData – data of passport validation

The answer should contain operation status.

BankAccountResponse:

    BankIdentityStatus status – allowed statuses are: 

    ACTIVE – user is found in your database and his account is activated, so user can proceed

    SUSPENDED – user is found in your database but his account is disabled, so user cannot proceed

    REVOKED – user is found but his account is blocked, so user cannot proceed

Any other response status or non-200 HTTP status of the response will break identity operation and the user will not proceed.