NFC Process Definition Integration

Early Access

Introduction

NFC authentication can be integrated in a Process Definition with the flexibility for numerous custom configurations. This document will cover a standard NFC flow that determines whether the agent device supports NFC, enables NFC if it is not already, then performs NFC reading and matching.

The example Process Definition featured in this guide includes a standard face and document capture process that will be used to integrate the NFC capture and processing flow.

This guide is based on the 'IDV NFC & Document Processing' template found in the Backoffice.

Step One - Detect User Agent Capabilities

The first step will discuss how to check whether the agent device used to complete the flow is capable of reading NFC chips. In the event that the device does not support NFC reading, the error presented to the end-user will be handled gracefully using conditional logic

To determine whether the device is capable of scanning NFC, conditional logic will be implemented that uses the results of the 'Detect User Agent' capabilities activity.

Add the 'Detect User Agent Capabilities' activity to the Process Definition, after the 'Switch to Mobile' activity.
Connect the two activities using a sequence arrow.

Add a new gateway to the Process Definition after the 'Detect User Agent Capabilities' activity. This gateway will be used to direct the flow depending on whether NFC scanning is available.
Connect the gateway to the 'Capture Consent' activity using a sequence arrow.
Click the sequence arrow to open the contextual menu and click the spanner settings icon. Set the sequence arrow to 'Default Flow'

Add a 'Simple Decider' activity to the Process Definition and connect the gateway using a sequence flow arrow.

Click the sequence arrow that connects the gateway to the 'Simple Decider' activity. This will open the right-side contextual menu. Expand the Condition drop down and configure the following:
1. Type - Expression
2. Condition Expression - ${_capabilities.userAgent1.mobile.modules.NFC.sensorUnavailable == true}

The expression above gets the value of the sensorUnavailable result from the _capabilities table. If that value is true, then the NFC sensor is not available and the Process Instance can be completed.

Add an 'NFC Not Supported' activity and connect the new activity to the 'Simple Decider' using a sequence flow arrow.

In the example above, an 'NFC Not Supported' gateway is also added. This is used to handle the flow of both the activity and its timeout boundary event.

Add an end event and connect the event to the 'NFC Not Support' gateway. This will end the flow gracefully should NFC scanning be unsupported.

Step Two - Add NFC Instructions

After document and face capture have been performed, the NFC capture flow will begin, starting after the 'Document to Face Matching v2' activity.

The first step in the NFC flow will present an instructions screen to the end-user, describing the capture requirements required for a successful capture.

The 'NFC Instructions' activity provides a predesigned instruction screen that will display during the flow.

Create a new gateway at the end of the document capture flow. In this example, this gateway will be added to the 'Document to Face Matching v2'. This gateway will be used to specify the start of the the NFC flow.

Add the 'NFC Instructions' activity after the newly created gateway and connect them using sequence arrows.

Alternatively, a custom NFC instructions screen can be implemented using a Custom Page or Custom Form.

The default NFC Instructions page in Trust Web

Step Three - Determine if NFC is Enabled

In Step Two, the 'Detect User Agent Capabilities' activity was used to determine whether the device used to complete the flow could perform NFC scanning. In this step, the same activity will be used to determine whether NFC scanning is enabled on the user agent device. Conditional logic will be used to check whether NFC is enabled, and in the event that NFC scanning is disabled, it will be activated using the 'Enable NFC' activity.

NFC Disabled Flow

Add a 'Detect User Agent Capabilities' activity after the 'NFC Instructions' activity and connect them using a sequence flow arrow.
Add a new gateway that will be used to control the conditional logic. Connect this gateway to the 'Detect User Agent Capabilities' activity.

The first condition to handle will be to determine if NFC scanning is disabled. Add the 'Enable NFC' activity to the Process Designer and connect the activity to the 'NFC Enabled' gateway.

Select the 'NFC Disabled' sequence flow arrow to open the right-side contextual menu. Create a new Condition of type 'Expression' and configure the following:
1. Type - Expression
2. Condition Expression - ${_capabilities.userAgent1_NFC.mobile.modules.NFC.moduleDisabled == true}

The Condition Expression utilizes the moduleDisabled parameter from the _capabilities table to check whether the NFC module is enabled on the user's device. If the value is true, the NFC module is not enabled and must be enabled using the 'Enable NFC' activity.

NFC Enabled Flow

After the 'Enable NFC' activity, create a new gateway. This will be used to connect the 'NFC Enabled' gateway in the event that the module is already enabled.

Connect the 'NFC Enabled' gateway to the newly created gateway. This will bypass the 'Enable NFC' activity if the NFC module is already enabled on the device.

Step Four - Capture & Process NFC

The 'Capture & Process NFC' activity is used to complete the capture and process the NFC data associated with the document. Note that the NFC module must be enabled on the device to perform the capture.

The activity includes two error boundary events for failed NFC capture; a retryable event where NFC capture can be performed again, and a non-retryable event where NFC capture cannot be attempted again.

After the gateway created in Step Three, add a 'Capture & Process NFC' activity and connect them using a sequence flow arrow.

The client times out 10 seconds before the time configured in the timer boundary event that is associated with the 'Capture & Process NFC' activity.

For example, if the timer is set to PT30s (30 seconds), the activity will timeout after 20 seconds. This allows the application time to make the timeout call before the server marks the operation as abandoned.

The timeout error can be retryable or non-retryable depending on the configuration of the activity. If the 'NFC_READER NATIVE_TIMEOUT' and 'CLIENT_TIMEOUT'_ are configured on the 'Retryable Client Error Statuses' input parameter, then the timeout error will be retryable and will follow the flow of the retryable boundary event.

The 'Capture & Process NFC' activity provides a number of customizable input parameters. For a full list of parameters, including their explanations, see the NFC Activity Parameters guide.
It is important to set the "NFC Configuration Name" and "NFC Configuration Version" parameters. These parameters relate to the NFC Certificates list used as part of the capture and processing step. For more information on NFC Certificates, see the NFC Certificates guide.
In the example above, the 'Retryable' error boundary event is connected to the 'NFC Error' activity. This activity is used to display a generic error to the user in instances where an error has occurred during NFC capturing.

The 'Failed NFC (Non Retryable)' error boundary event is connected to the 'Switch to Desktop Entry Gateway'

The 'NFC Error' activity is connected to the initial gateway at the beginning of the NFC capturing flow so that end-users can retry the NFC capture process.
In the example above, the 'NFC Error' timeout boundary is connected to a gateway at the end of the Process Definition.

Step Five - NFC Face Matching

After NFC capture and processing has been completed, the resulting face can be compared to a face captured earlier in the ID&V flow. This will compare the face images to ensure that the NFC data retrieved from the document matches the capture face image.

After the 'Capture & Process NFC' activity, add the 'NFC Face Match v1' activity and connect them using a sequence flow arrow.

The 'NFC Face Match v1' activity provides two error boundary events.
1. Failed document to face match - This error is triggered if the face image retrieved from the NFC data does not match the face image captured as part of the face capture process. In the example above, the end-user is redirected back to the face capture process to try again.
2. Failed document image template generation - This error is triggered when document image template generation has failed. In the example above, the end-user is directed to the switch-to-desktop gateway, and the process will end.

The 'NFC Face Match v1' activity provides various customizable input parameters. For more information, see the NFC Activity Parameters guide.

Step Six - Add a Simple Decider

At the end of the Process Definition, a decision can be determined based on the outcome of each test by adding a 'Simple Decider' activity to the flow.

After the end-user has switched to desktop using the 'Switch to Desktop' activity, add a 'Simple Decider' and connect to the device 'switch gateway' and final gateway of the Process Definition.

In the example above, the final gateway is connected to the 'NFC Error' activity's timeout event.

Viewing Results

Results of the NFC capture can be viewed in the Process Instance page of the Backoffice. Results provided include the following

Viewing Results in the Backoffice

Face Match Results

If an NFC Face Match was performed during the Process Instance, the captured face image and face image derived from the NFC scan will be shown alongside the results of the test.

NFC Check Results

An overview on the checks performed as part of the NFC flow will be displayed in the in the Documents section under the NFC category:

The results are determined as follows:

NFC Face Match - The result of whether the face image retrieved from the NFC capture matches the face captured during the flow.
Overall Result - An overall result compiled from all NFC checks.
Active Authentication Challenge Signature Check - The results of a check that determines whether the document has been cloned.
Signature Checks - The results of a check which validates the digital signature.
Signing Certificate Revocation - Determines whether the certificate appears on the revocation list.
Datagroup Hash Check - An NFC chip contains a number of data groups which catalogue information about the document. This check determines that the contents of each data group is hashed and checked against the hashes in the security object.
Security Object Checks - Each NFC chip contains a security object, which includes the hashed contents of each data group digitally signed by the document issuer. The document issuer in turn is digitally signed by a country-level signing key. This check ensure that the security object is correctly formatted and consistent with the rest of the document information before all signatures are checked.

Details on each check performed during the Process Instance can be found in the documentNfc dropdown under the Checks section of the Process Instance page.

Viewing Results Using the API

NFC check results can be retrieved using the TrustX API. This section of the documentation will cover the API calls required to retrieve NFC results, including the required permissions.

NFC results are available via the following APIs

Checks API

The API GET - Get Checks returns additional checks as part of its structure:

An overall NFC validation check result and the individual checks that were performed.
An NFC face match check, provided that the NFC face match activity was included with the activity.

An example of the GET - Get Checks response can be seen below:

Request:

HTTP
    
GET https://{{tenantid}}.{{sky-region}}.trustx.com/api/userdata-server/processDefinitions/{{processDfnId}}/processInstances/{{processInstanceID}}/userdata/checks
Copy

Response:

HTTP
    
​x
    
{    "faceMatches": {        "id": "faceMatches",        "nested": {            "face1": {                "id": "face1",                "nested": {                    "documents": {                        "id": "documents",                        "nested": {                            "doc1": {                                "id": "doc1",                                "nested": {                                    "nfc": {                                        "id": "nfc",                                        "outcome": "PASS",                                        "moreInfo": "The face images match",                                        "metaData": {                                                                                }                                    }                                }                            }                        }                    }                }            }        }    },    "documentNfc": {        "id": "documentNfc",        "nested": {            "doc1": {                "id": "doc1",                "outcome": "PASS",                "nested": {                    "aaChallengeSignatureCheck": {                        "id": "aaChallengeSignatureCheck",                        "description": "Check that the challenge signature calculated using the Active Authentication private key is valid.",                        "outcome": "PASS"                    },                    "dscCscaPathRevocationCheck": {                        "id": "dscCscaPathRevocationCheck",                        "description": "Check that the Document Signer Certificate has not been revoked by the Country Signing CA.",                        "outcome": "NOT_AVAILABLE"                    },                    "dscCscaPathCheck": {                        "id": "dscCscaPathCheck",                        "description": "Check that there is a valid path from the Document Signer Certificate to a valid Country Signing CA Certificate.",                        "outcome": "PASS"                    },                    "dgHashCheck": {                        "id": "dgHashCheck",                        "description": "Check that the hashes of the supplied LDS file contents match the hashes in the LDS security object (SOd).",                        "outcome": "PASS"                    },                    "securityObjectChecks": {                        "id": "securityObjectChecks",                        "description": "Validate the signature of the LDS Security Object and check its consistency against other document data.",                        "outcome": "PASS"                    }                },                "metaData": {​                }            }        }    }}
Copy

Note that the contents of meta data may change as activities are updated.

Checks API

The API GET - Get User Data returns additional NFC data as part of it structure:

NFC data is include in the extracted text.
Additional reports are present for NFC validations that were performed.
An additional NFC face match report, provided that the NFC face match activity was included with the activity.

An example of the GET - Get Checks. response can be seen below:

Request:

HTTP
    
GET https://{{tenantid}}.{{sky-region}}.trustx.com/api/userdata-server/processDefinitions/{{processDfnId}}/processInstances/{{processInstanceID}}/userdata?optimized=true
Copy

Response:

HTTP
    
{    "documents": {        "doc1": {            "id": "doc1",            "type": "Ireland - ePassport (2013) #2",            "classification": "Passport",            "captures": {                "CROPPED": {                    "FRONT": {                        "imageHref": "/idDocs/doc1/e4ffa873-3db3-4473-85c8-9d53fddd1ccc/abac240b-5e25-420a-bff7-f7dce900cc0c/FRONT.Cropped.jpeg"                    }                },                "UNCROPPED": {                    "FRONT": {                        "imageHref": "/idDocs/doc1/e4ffa873-3db3-4473-85c8-9d53fddd1ccc/abac240b-5e25-420a-bff7-f7dce900cc0c/FRONT.Uncropped.jpeg"                    }                }            },            "segmentedImages": {                "PORTRAIT": {                    "id": "PORTRAIT",                    "capture": {                        "imageHref": "/idDocs/doc1/e4ffa873-3db3-4473-85c8-9d53fddd1ccc/img-segments/PORTRAIT.jpg"                    }                }            },            "keyBiographicData": {                "GivenNames": {                    "label": "Given Names",                    "value": "JOE",                    "fieldName": "Given Names"                }            },            "biographicData": [                {                    "label": "Given Names",                    "fieldId": "9",                    "fieldName": "Given Names",                    "values": {                        "visualZoneValue": "JOE",                        "mrzValue": "JOE",                        "nfcValue": "JOE"                    }                }            ],            "portraitImage": {                "id": "PORTRAIT",                "capture": {                    "imageHref": "/idDocs/doc1/e4ffa873-3db3-4473-85c8-9d53fddd1ccc/img-segments/PORTRAIT.jpg"                }            },            "reports": {                "reportsByCategory": {                    "visualDocumentTamper": {                        "blackAndWhiteDetection_front": {                            "id": "blackAndWhiteDetection_front",                            "name": "Black and White Copy Detection - Front",                            "description": "Check to ensure that the 'front' document image is not a black and white copy.",                            "outcome": "APPROVE"                        },                        "photoSubstitutionDetection_front": {                            "id": "photoSubstitutionDetection_front",                            "name": "Photo Substitution Detection - Front",                            "description": "Check to ensure that the 'front' document images portrait image has not been replaced.",                            "outcome": "APPROVE"                        },                        "colorDetection_front": {                            "id": "colorDetection_front",                            "name": "Color Copy Detection - Front",                            "description": "Check to ensure that the 'front' document image is not a color copy.",                            "outcome": "APPROVE"                        },                        "screenReplay_front": {                            "id": "screenReplay_front",                            "name": "Screen Replay Detection - Front",                            "description": "Check to ensure that the 'front' document image is not captured by taking a photo of a document on a screen.",                            "outcome": "APPROVE"                        }                    },                    "documentQuality": {                        "overallQuality_front": {                            "id": "overallQuality_front",                            "name": "Overall Quality - Front",                            "description": "Check to ensure that the 'front' document image meets the required standard for document processing.",                            "outcome": "APPROVE"                        }                    },                    "faceMatch": {                        "portraitFaceMatch": {                            "id": "portraitFaceMatch",                            "name": "Portrait Face Match",                            "description": "Check to ensure that the face image matches the portrait image extracted from the document.",                            "outcome": "APPROVE",                            "documentKey": "doc1",                            "faceKey": "face1"                        },                        "nfcFaceMatch": {                            "id": "nfcFaceMatch",                            "name": "NFC Face Match",                            "description": "Check to ensure that the face image matches the face image extracted from the chip on the nfc document.",                            "outcome": "APPROVE",                            "livePath": "https://skydev1.oak.trustx-dev.com/api/userdata-server/processDefinitions/KO6J6243OVYZOCLDMQDE46BVEI/processInstances/GHQJN2KLSWKDG5I3IUGHNTIKA4/getdata?path=/faces/face1/13ed1547-ca5b-40bf-aed3-ce8717daeef7/face.jpeg",                            "referencePath": "https://skydev1.oak.trustx-dev.com/api/userdata-server/processDefinitions/KO6J6243OVYZOCLDMQDE46BVEI/processInstances/GHQJN2KLSWKDG5I3IUGHNTIKA4/getdata?path=/idDocs/doc1/nfc/87957cc7-c05f-4156-a28d-3dfb452fabe1/extracted/dg2-face-image.jpeg",                            "reportType": "FaceMatchReport"                        }                    },                    "nfc": {                        "nfcOverall": {                            "id": "nfcOverall",                            "name": "NFC - Overall",                            "description": "Check to ensure that document has passed all NFC checks.",                            "outcome": "APPROVE"                        },                        "nfcAaChallengeSignatureCheck": {                            "id": "nfcAaChallengeSignatureCheck",                            "name": "NFC - Active Authentication Challenge Signature Check",                            "description": "Check to ensure that document has passed active authentication challenge signature check.",                            "outcome": "APPROVE"                        },                        "nfcDscCscaPathCheck": {                            "id": "nfcDscCscaPathCheck",                            "name": "NFC - Signature Checks",                            "description": "Check to ensure that document has passed all relevant signature checks based on Document Signing Certifaces and Country Signing Certifcates.",                            "outcome": "APPROVE"                        },                        "nfcDscCscaPathRevocationCheck": {                            "id": "nfcDscCscaPathRevocationCheck",                            "name": "NFC - Signing Certificate Revocation Check",                            "description": "Check to ensure that document signing certificates have not been revoked.",                            "outcome": "NA"                        },                        "nfcDgHashCheck": {                            "id": "nfcDgHashCheck",                            "name": "NFC - Datagroup Hash Check",                            "description": "Check that the hashes of the supplied LDS file contents match the hashes in the LDS security object (SOD).",                            "outcome": "APPROVE"                        },                        "nfcSecurityObjectChecks": {                            "id": "nfcSecurityObjectChecks",                            "name": "NFC - Security Object Checks",                            "description": "Check and validate the signature of the LDS Security Object and check its consistency against other document data.",                            "outcome": "APPROVE"                        }                    }                }            }        }    },    "faces": {        "face1": {            "id": "face1",            "capture": {                "imageHref": "/faces/face1/13ed1547-ca5b-40bf-aed3-ce8717daeef7/face.jpeg"            },            "reports": {                "reportsByCategory": {                    "faceQuality": {                        "overallQuality": {                            "id": "overallQuality",                            "name": "Overall Quality",                            "description": "Check to ensure that the face meets the required face quality metrics.",                            "outcome": "APPROVE"                        }                    },                    "faceLiveness": {                        "passiveFaceLiveness": {                            "id": "passiveFaceLiveness",                            "name": "Passive Face Liveness",                            "description": "Check to ensure that the face meets the required passive liveness checks.",                            "outcome": "APPROVE"                        }                    },                    "faceMatch": {                        "templateGeneration": {                            "id": "templateGeneration",                            "name": "Face Template Generation",                            "description": "Check to ensure that the face image is suitable for matching.",                            "outcome": "APPROVE"                        },                        "portraitFaceMatch": {                            "id": "portraitFaceMatch",                            "name": "Portrait Face Match",                            "description": "Check to ensure that the face image matches the portrait image extracted from the document.",                            "outcome": "APPROVE",                            "documentKey": "doc1",                            "faceKey": "face1"                        },                        "nfcFaceMatch": {                            "id": "nfcFaceMatch",                            "name": "NFC Face Match",                            "description": "Check to ensure that the face image matches the face image extracted from the chip on the nfc document.",                            "outcome": "APPROVE",                            "livePath": "https://skydev1.oak.trustx-dev.com/api/userdata-server/processDefinitions/KO6J6243OVYZOCLDMQDE46BVEI/processInstances/GHQJN2KLSWKDG5I3IUGHNTIKA4/getdata?path=/faces/face1/13ed1547-ca5b-40bf-aed3-ce8717daeef7/face.jpeg",                            "referencePath": "https://skydev1.oak.trustx-dev.com/api/userdata-server/processDefinitions/KO6J6243OVYZOCLDMQDE46BVEI/processInstances/GHQJN2KLSWKDG5I3IUGHNTIKA4/getdata?path=/idDocs/doc1/nfc/87957cc7-c05f-4156-a28d-3dfb452fabe1/extracted/dg2-face-image.jpeg",                            "reportType": "FaceMatchReport"                        }                    }                }            }        }    }}
Copy

Note in the example above, some data has been removed in order to make the example more concise. For example, many biographic elements have been removed.

Last updated on