Skip to content

Latest commit

 

History

History
507 lines (362 loc) · 21.8 KB

netverify-authentication.md

File metadata and controls

507 lines (362 loc) · 21.8 KB

Jumio

Authentication for Web

This is a reference manual and configuration guide for Jumio Authentication for Web. It describes how to initiate a transaction, how to customize your settings and branding, and how to display Authentication to your users.

Biometric-based Jumio Authentication establishes the digital identities of your users through the simple act of taking a selfie. Our liveness technology quickly and securely authenticates users and unlocks their digital identities.

Revision history

Information about changes to features and improvements documented in each release is available in our Revision history.

Table of contents


Initiating an Authentication transaction

Call the RESTful API POST endpoint /initiate with a JSON object containing the properties described below to create a transaction for each user. You will receive a JSON object in the response containing a timestamp, a Jumio transaction reference and a URL which you can use to present Authentication to your user.

⚠️ A new transaction will be created and the facemap will be temporarily stored until the transaction reaches a final state (max. 15 minutes).
⚠️ If multiple transactions has been created for the same enrollmentTransactionReference within 15 minutes only the last one will successfully work. For the first ones the user will not be able to finish them, they will get a final state of EXPIRED.

HTTP Request Method: POST
REST URL (US): https://netverify.com/api/authentication/v1/web/initiate
REST URL (EU): https://lon.netverify.com/api/authentication/v1/web/initiate
REST URL (SGP): https://core-sgp.jumio.com/api/authentication/v1/web/initiate


Authentication and encryption

Authentication API calls are protected using HTTP Basic Authentication. Your Basic Auth credentials are constructed using your API token as the user-id and your API secret as the password. You can view and manage your API token and secret in the Customer Portal under Settings > API credentials.

⚠️ Never share your API token, API secret, or Basic Auth credentials with anyone — not even Jumio Support.

The TLS Protocol is required to securely transmit your data, and we strongly recommend using the latest version. For information on cipher suites supported by Jumio during the TLS handshake see Supported cipher suites.

Request headers

The following fields are required in the header section of your request:

Accept: application/json
Content-Type: application/json
Content-Length: (see RFC-7230)
Authorization: (see RFC 7617)
User-Agent: YourCompany YourApp/v1.0

ℹ️ Jumio requires the User-Agent value to reflect your business or entity name for API troubleshooting.

Request body

The body of your initiate API request allows you to

  • provide your own internal tracking information for the user and transaction.
  • indicate where the user should be directed after the user journey.
  • select the language to be displayed.
ℹ️ Values set in your API request will override the corresponding settings configured in the Customer Portal.

Required items appear in bold font.

Name Type Max. length Description
enrollmentTransactionReference string 36 The transaction reference from the onboarding ID verification to be used for authentication.

ℹ️ Transaction has to be
• verificationStatus = APPROVED_VERIFIED
• similarity = MATCH
• validity = TRUE
callbackUrl1 string 255 Sends verification result to this URL upon completion.
Overrides Callback URL in the Customer Portal.
successUrl1 string 2047 Redirects to this URL after a successful transaction.
Overrides Success URL in the Customer Portal.
errorUrl1 string 255 Redirects to this URL after an unsuccessful transaction.
Overrides Error URL in the Customer Portal.
userReference2 string 100 Your internal reference for the user.
locale string 5 Renders content in the specified language.
Overrides Default locale in the Customer Portal.
See supported locale values.
tokenLifetimeInMinutes number Max. value: 86400 Time in minutes until the authorization token expires. (minimum: 5, maximum: 86400)
Overrides Authorization token lifetime in the Customer Portal.

1 See URL constraints for Callback, Error, and Success URLs.
2 Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses.


Supported locale values

Hyphenated combination of ISO 639-1:2002 alpha-2 language code plus ISO 3166-1 alpha-2 country (where applicable).

Value Locale
bg Bulgarian
cs Czech
da Danish
de German
el Greek
en American English (default)
en-GB British English
es Spanish
es-MX Mexican Spanish
et Estonian
fi Finnish
fr French
hu Hungarian
hy Armenian
it Italian
ja Japanese
ka Georgian
ko Korean
lt Lithuanian
nl Dutch
no Norwegian
pl Polish
pt Portuguese
pt-BR Brazilian Portuguese
ro Romanian
ru Russian
sk Slovak
sv Swedish
tr Turkish
vi Vietnamese
zh-CN Simplified Chinese
zh-HK Traditional Chinese

Response

Unsuccessful requests will return the relevant HTTP status code and information about the cause of the error.

Successful requests will return HTTP status code 200 OK along with a JSON object containing the information described below.

Required items appear in bold type.

Name Type Max. length Description
timestamp String 24 Timestamp (UTC) of the response.
Format: YYYY-MM-DDThh:mm:ss.SSSZ
redirectUrl String 255 URL used to load Authentication client.
transactionReference String 36 Jumio reference number for the Authentication transaction.

Examples

Sample request

POST https://netverify.com/api/authentication/v1/web/initiate HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 1234
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{
	"enrollmentTransactionReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"userReference": "transaction_1234",
	"callbackUrl": "https://www.yourcompany.com/callback",
	"successUrl" : "https://www.yourcompany.com/success",
	"errorUrl" : "https://www.yourcompany.com/error",
	"tokenLifetimeInMinutes": 5,
	"locale": "de"
}
⚠️ Sample requests cannot be run as-is. Replace example data with your own values.

Sample response

{
  "timestamp": "2019-07-12T08:23:12.494Z",
  "transactionReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "redirectUrl": "https://yourcompany.netverify.com/web/v4/app?authorizationToken=xxxxxxxxxxxxxxlocale=en-GB"
}

Configuring settings in the Customer Portal

In the Settings screen of the Customer Portal you can customize your settings and brand your Authentication page.
Save changes using your Customer Portal password to activate them.

ℹ️ Values set in your API request will override the corresponding settings configured in the Customer Portal.

Application settings — General

Callback, Error, and Success URLs

Define a Callback URL to receive verification results and extracted user data from Jumio when a transaction is completed. For more information, see our Callback documentation.

Define a Success URL to direct the user after images are accepted for processing. If no Success URL is specified in the Customer Portal or the initiate API request, the Jumio default success page will be displayed, including any custom images you have specified.

Define an Error URL to direct the user when the verification process ends with an error or a failure after 3 submission attempts. If no Error URL is specified in the Customer Portal or the initiate API request, the Jumio default error page will be displayed, including any custom images you have specified.

URL requirements:

URL restrictions:

  • IP addresses, ports, certain query parameters and fragment identifiers are not allowed.
  • Personally identifiable information (PII) is not allowed in any form.

Jumio appends the following parameters to your Success or Error URL to redirect your user at the conclusion of the user journey. These cannot be used as part of your Success or Error URL:

Name Description
transactionStatus • SUCCESS for successful submissions.
• ERRORfor errors and failure after 3 attempts.
transactionReference Jumio reference number for the transaction.
errorCode Displayed when transactionStatus is ERROR.

1 Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses.

Authorization token lifetime

Specify the duration of time for which your redirectUrl will remain valid. Enter the value in minutes (minimum 5, maximum 86400). The default value is 30 minutes.


Application settings — Redirect

Domain name prefix

You can optionally define a domain name prefix (https://yourcompany.netverify.com) for the URL of your Authentication page.

  • Allowed characters are letters a-z, numbers 0-9, -
  • Must not start or end with -
  • Max. 63 characters

Default locale

Select a language from the dropdown list to set your display language for Authentication. If no language is selected, Authentication will be displayed in English (US).

Choose from:

  • English
  • English (United Kingdom)
  • German
  • Turkish
  • Finnish
  • Norwegian
  • Polish
  • Swedish
  • Russian
  • Portuguese
  • Portuguese (Brazil)
  • Spanish
  • Spanish (Mexico)
  • Italian
  • French
  • Dutch
  • Bulgarian
  • Chinese (China)
  • Chinese (Hong Kong)
  • Czech
  • Danish
  • Greek
  • Hungarian
  • Japanese
  • Korean
  • Romanian
  • Slovak
  • Vietnamese
  • Lithuanian
  • Estonian

Customize client

Colors

Specify primary and secondary colors for each locale to give Authentication your own look and feel.

Any locale which is not configured will first default to the root language (e.g. EN_GB to EN), then to your default configuration, and finally to the Jumio default.

You can also reset all colors to the Jumio default.


Displaying Authentication

The redirectUrl returned in the response to your initate API call, which loads your customized Authentication page, can be used in several ways:

  • within an iFrame on your web page
  • as a link on your web page
  • as a link shared securely with a user

Using Authentication in an iFrame

If you want to embed Authentication on a web page, place the iFrame tag in your HTML code where you want the client to appear. Use the redirectUrl as value of the src attribute.

⚠️ The allow="camera;fullscreen" allowfullscreen attributes must be included to enable the camera for image capture in supported browsers in full screen mode.
⚠️ In case you are nesting the iFrame in another iFrame the allow="camera;fullscreen" allowfullscreen attribute must be added to every iFrame.

Width and height

We recommend adhering to the responsive breaking points in the table below.

Size class Width Height
Large ≥ 900 px ≥ 710 px
Medium 640 px 660 px
Small 560 px 600 px
X-Small ≤ 480 px ≤ 535 px

Note: When specifying the width and height of your iFrame you may prefer to use percentage values so that the iFrame behaves responsively on your page.

⚠️The Authentication client itself will responsively fill the iFrame that it is loaded into.

Example HTML

Absolute sizing example

<iframe src="https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx" width="930" height="750" allow="camera;fullscreen" allowfullscreen></iframe>

Responsive sizing example

<iframe src="https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx" width="70%" height="80%" allow="camera;fullscreen" allowfullscreen></iframe>

Optional iFrame logging

When the Authentication client is embedded in an iFrame1, it will communicate with the containing page using the JavaScript window.postMessage() method to send events containing pre-defined data. This allows the containing page to react to events as they occur (e.g., by directing to a new page once the success event is received). Events include data that allows the containing page to identify which Authentication transaction triggered the event. Events are generated in a stateless way, so that each event contains general contextual information about the transaction (e.g., transaction reference, authorization token, etc.) in addition to data about the specific event that occurred.

Using JavaScript, the containing page can receive the notification and consume the data it contains by listening for the message event on the global window object and reacting to it as needed. The data passed by the Authentication client in this notification is represented as JSON in the data string property of the listener method's event argument. Parsing this JSON string results in an object with the properties described below.

All data is encoded with UTF-8.

1 This functionality is not available for instances of Authentication running in a standalone window or tab.

event.data object

Required items appear in bold type.

Property Type Description
authorizationToken string Authorization token, valid for a specified duration.
transactionReference string Jumio reference number for the transaction.
eventType integer Type of event that has occurred.
Possible values:
• 510 (application state-change)
dateTime string UTC timestamp of the event in the browser.
Format: YYYY-MM-DDThh:mm:ss.SSSZ
payload JSON object Information specific to the event generated.
(see event.data.payload object)

1 Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses.


event.data.payload object

Required items appear in bold type.

Name Type Description
value string Possible values:
• loaded (Authentication loaded in the user's browser.)
• success (Images were accepted for verification.)
• error (Verification could not be completed due to an error.)
metainfo JSON object Additional meta-information for error events.
(see metainfo object)

event.data.payload.metainfo object

Required items appear in bold type.

Property Type Description
code integer see errorCode values

Example iFrame logging code

function receiveMessage(event) {
	var data = window.JSON.parse(event.data);
	console.log('ID Verification Web was loaded in an iframe.');
	console.log('auth token:', data.authorizationToken);
	console.log('transaction reference:', data.transactionReference);
	console.log('event type:', data.eventType);
	console.log('date-time:', data.dateTime);
	console.log('event value:', data.payload.value);
	console.log('event metainfo:', data.payload.metainfo);
}
window.addEventListener("message", receiveMessage, false);

After the user journey

At the end of the user journey, the user is directed to your Success URL if the images they submitted were accepted for processing. If no Success URL has been defined, the Jumio default success page will be displayed, including any custom success image you have specified in the Customer Portal.

If acceptable images are not provided after three attempts (see Reject reasons), the user is directed to your Error URL. If no Error URL has been defined, the Jumio default error page will be displayed, including any custom error image you have specified in the Customer Portal.

To display relevant information on your success or error page, you can use the following parameters which we append when redirecting to your successUrl or errorUrl as HTTP GET query string parameters1. It is also possible to set successUrl and errorUrl to the same address, by using the query parameter transactionStatus.

Required items appear in bold type.

Name Description
transactionStatus Possible values:
• SUCCESS for successful submissions.
• ERRORfor errors and failure after 3 attempts.
transactionReference Jumio reference number for the transaction.
errorCode Displayed when transactionStatus is ERROR.
Possible values:
• 9100 (Error occurred on our server.)
• 9200 (Authorization token missing, invalid, or expired.)
• 9210 (Session expired after the user journey started.)
• 9300 (Error occurred transmitting image to our server.)
• 9400 (Error occurred during verification step.)
• 9800 (User has no network connection.)
• 9801 (Unexpected error occurred in the client.)
• 9810 (Problem while communicating with our server.)
• 9820 (Camera unavailable.)
• 9821 (The Authentication capture process failed after 3 attempts.)
• 9836 (No acceptable submission in 3 attempts.)

1 Because HTTP GET parameters can be manipulated on the client side, they may be used for display purposes only.
2 Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses.

Sample success redirect

https://www.yourcompany.com/success/?transactionStatus=SUCCESS&transactionReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Sample error redirect

https://www.yourcompany.com/error/?transactionStatus=ERROR&transactionReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&errorCode=9820

Supported browsers

Jumio offers guaranteed support for Authentication on the following browsers and the latest major version of each operating system.

Desktop

Browser Major version Operating system Supports
Authentication
Google Chrome current +
1 previous		 Windows + Mac X
Mozilla Firefox current +
1 previous		 Windows + Mac X
Apple Safari current Mac X
Microsoft Internet Explorer current Windows
Microsoft Edge current Windows X

Mobile

Authentication does not support WebViews.

Browser name Major browser version Operating system Supports
Authentication
Google Chrome current Android X
Samsung Internet current Android X
Apple Safari current iOS X1

1Partial support refers to supporting only iPad, not iPhone. Shows an overlay button which can not be disabled.

© Jumio Corporation, 395 Page Mill Road, Suite 150 Palo Alto, CA 94306