Onfido logo home page
Watch a demo
Get in touch
Arrow back Back to guides

Quick start: Face Authenticate

Start here

Face Authenticate enables the repeat verification of end users, who have been verified and explicitly trusted, by comparing current and previous facial biometrics collected via a face scan completed on the Onfido SDKs.

Follow this guide to:

  • set up your integration for Face Authenticate
  • complete the authentication of an end user using the Onfido Authenticate SDKs

Overview

Face Authenticate has 3 steps:

  1. Establish a trusted face for the end user
  2. Integrate and start the Onfido Authentication SDK flow
  3. Validate the Authentication result

Establish a trusted face

Each applicant you run Face Authenticate against must have a trusted image selected and set via Trusted Faces. This image acts as the reference for an applicant’s identity in the initial authentication attempt.

With an Onfido check

The following diagram illustrates the flow for creating a trusted face with an Onfido check:

trusted face steps

  1. Create an applicant with Onfido

Create an applicant from your backend server, using a valid API token. For example:

curl -X POST https://api.eu.onfido.com/v3.4/applicants/ \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "first_name": "Jane",
  "last_name": "Doe",
  "dob": "1990-01-31",
  "address": {
    "building_number": "100",
    "street": "Main Street",
    "town": "London",
    "postcode": "SW4 6EH",
    "country": "GBR"
  }
}'
  1. Upload a document, live photo or live video to Onfido

For example:

$ curl -X POST https://api.eu.onfido.com/v3.4/documents \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -F 'type=passport' \
  -F 'file=@path/to/passport.png;type=image/png' \ 
  -F 'applicant_id=<APPLICANT_ID>'
  1. Create a check containing a Document report, or a Document and Facial Similarity report

For example:

curl -X POST https://api.eu.onfido.com/v3.4/checks \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "applicant_id": "<APPLICANT_ID>",
  "report_names": ["document", "facial_similarity_photo"]
}'

For more details on how to create a check please see our quick start guide for creating a check.

  1. Retrieve the results of the check

You can retrieve an individual check or report's status and result via the API.

If you have set up webhooks, a notification is sent upon completion of either a check or report.

  1. Review the results of the check

If the result is clear, create a trusted face for the applicant from your backend server using the live_photo_id, live_video_id or document_id returned in the report response.

We recommend the following order of priority for using media to create a trusted face:

  1. Live photo
  2. Document picture
  3. Live video

For example:

curl -X POST https://api.eu.onfido.com/v3.4/applicants/<APPLICANT_ID>/face \
    -H 'Authorization: Token token=<API_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{"live_photo_id": "<LIVE_PHOTO_ID>"}'

OR

If the result is consider, Onfido cannot verify the identity of the end user. In this case you should not create a trusted face for the applicant without further manual review.


Without an Onfido check

You can still use Face Authenticate to re-verify users who have not completed an identity verification check with Onfido.

To establish a trusted face:

  1. Create an applicant with Onfido

Create an applicant from your backend server, using a valid API token. For example:

curl -X POST https://api.eu.onfido.com/v3.4/applicants/ \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "first_name": "Jane",
  "last_name": "Doe",
  "dob": "1990-01-31",
  "address": {
    "building_number": "100",
    "street": "Main Street",
    "town": "London",
    "postcode": "SW4 6EH",
    "country": "GBR"
  }
}'
  1. Create a trusted face for the applicant from your backend server using a file containing an image of the applicant that you trust
curl -X POST https://api.eu.onfido.com/v3.4/applicants/<APPLICANT_ID>/face \
  -H 'Authorization: Token token=<API_TOKEN>' \
  -F 'file=@applicant_image.jpg;type=image/jpeg'

Integrate and start the Onfido Authentication SDK flow

Face Authenticate is only available via the Onfido SDKs, not via the API directly. You need to integrate the Authentication SDKs into your app in order for users to complete the flow.

Android Authentication SDK

  1. Add the SDK dependency
repositories {
    mavenCentral()
}
dependencies {
    implementation 'com.onfido.sdk:authentication:x.y.z'
}
  1. Build a configuration object
val config = OnfidoAuthenticationConfig.builder(this)
   .withSdkToken(sdkToken)
   .withRetryCount(2)
   .build()

Use .withRetryCount() to set the number of repeat attempts a user can do after the first unsuccessful try.

  1. Instantiate and start the flow
val OnfidoAuthentication onfidoAuthentication = OnfidoAuthenticationImpl(this)

onfidoAuthentication.startActivityForResult(
 this,    // must be an Activity or Fragment (support library)
 AUTH_REQUEST_CODE,   // this request code will be important for you on onActivityResult() to identity the onfido callback
 config   // pass previously created configuration object
)

For more information please see Onfido Android Authentication SDK.


iOS Authentication SDK

  1. Add the SDK dependency

Using CocoaPods

The SDK is available on CocoaPods and you can include it in your project by adding the following to your Podfile:

pod 'OnfidoAuth'

Run pod install to install the SDK.

Using Swift Package Manager

The SDK is available with Swift Package Manager and you can include it in your project by adding the following package repository URL:

https://github.com/onfido/onfido-auth-sdk-ios.git

  1. App permissions

The SDK uses the device's camera. You must have the NSCameraUsageDescription key in your application's Info.plist file.

<key>NSCameraUsageDescription</key>
<string>Required for facial capture</string>
  1. Create the SDK configuration

Once you have added the SDK as a dependency and you have an SDK token, you can configure the SDK:

let config = try! OnfidoAuthConfig.builder()
    .withSDKToken("<YOUR_SDK_TOKEN_HERE>")
    .withRetryCount(2) // Optional, default is 0
    .build()

let flow = OnfidoAuthFlow(withConfiguration: config)
    .with(responseHandler: { response in
        // Callback when flow ends
    })

Use .withRetryCount() to set the number of repeat attempts a user can do after the first unsuccessful try.

  1. Start the flow

Run the flow from the view controller you want the flow to be presented from e.g. self, where self is a view controller.

flow.run(from: self)

For more information please see Onfido iOS Authentication SDK.


Web SDK

  1. Import the library

HTML Script Tag Include

<script src="dist/onfidoAuth.min.js"></script>

Note: If you are importing the Auth module, you do not also need to import the standard SDK module (dist/onfido.min.js).

And the CSS styles:

<link rel="stylesheet" href="dist/style.css" />

NPM style import

// ES6 module import
import { init } from 'onfido-sdk-ui/dist/onfidoAuth.min.js'

// commonjs style require
var Onfido = require('onfido-sdk-ui/dist/onfidoAuth.min.js')

You also need to have an auth-sdk/ folder in your public assets folder, and copy the contents of node_modules/onfido-sdk-ui/dist/auth-sdk into it.

If you are using Webpack on your application, you can automate this by adding:

new CopyPlugin({
  patterns: [
    {
      from: `../../node_modules/onfido-sdk-ui/dist/auth-sdk`,
      to: `${__dirname}/bin/src/auth-sdk`,
    },
  ],
})

This will fetch the core authentication technology from the SDK into your application. Using web workers for authentication enables the best performance achievable, without compromising on usability.

The CSS style will be included inline with the JS code when the library is imported.

⚠️ Note: The library is Browser only, it does not support the Node Context.

  1. Add basic HTML markup

Add an empty HTML element at the bottom of your page for the modal interface to mount itself on.

<div id="onfido-mount"></div>
  1. Initialize the SDK

You can now initialize the SDK, using an SDK token.

Onfido.init({
  token: '<YOUR_SDK_TOKEN>',
  containerId: 'onfido-mount',
  containerEl: <div id="root" />, //ALTERNATIVE to `containerId`
  onComplete: function (data) {
    console.log('everything is complete')
  },
  steps: ['auth'],
})

For more information please see Web SDK.


Validate the Authentication result

The following diagram illustrates the flow for starting and validating a Face Authentication attempt:

auth steps

1. Retrieve the Onfido public key

In order to verify the Onfido JWT returned in the Authentication response you first need to retrieve the Onfido public key and store it in your backend.

GET /v3.4/auth/keys HTTP/1.1
Host: api.eu.onfido.com
Content-Type: application/json

Note: This is a periodic task.

2. Generate an SDK token

For example:

curl -X POST https://api.eu.onfido.com/v3.4/sdk_token \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
     "applicant_id": "<APPLICANT_ID>",
     "referrer": "https://*.example.com/example_page/*",
     "cross_device_url": "https://example.com"
   }'

3. Start the flow for the end user

When a user is requesting authentication, configure and initialise the Face Authenticate Onfido SDK flow in your app.

The end user will be presented with a set of screens asking them to complete a face scan. The face scan requires the user to frame their face using the device camera and then move the device closer to capture the face again. The face scan is captured and uploaded to the Onfido backend where a 3D facemap of the applicant’s face is created based on the images captured during the scan.

Authentication result

When the user has successfully completed the flow and the captured face scan has been uploaded and compared on the Onfido backend, the SDK will return an Authentication result object containing the Authentication session result and a signed JWT to validate the response to your app.

Android

data class AuthenticationResult(
    val token: String?,
    val verified: Boolean,
    val uuid: String
)

iOS

public struct AuthenticationResult {
    
    public let token: String?
    public let uuid: String?
    public let verified: Bool
}

Web

Example of an auth onComplete data callback:

    {
      "success": true,
      "token": "<SIGNED_TOKEN>",
      "type": "complete",
      "uuid": "<ATTEMPT_ID>"
    }

Whether the applicant was successfully authenticated is indicated in the verified (iOS and Android) or success (Web) parameter, which is returned as true for success or false for failure.

Authentication is only successful if both:

  • The applicant’s 3D facemap matches the applicant’s 2D trusted face image (1st authentication attempt) OR the applicant’s 3D facemap matches the previous attempt’s 3D facemap (subsequent authentication attempts)

AND

  • The applicant passes a liveness test when completing the face scan

For more information on handling callbacks from the SDK please see the Android, iOS or Web READMEs.

4. Validate signed JWT

If the Authenticate attempt is successful, the Authentication result object will also contain a signed JWT in the token parameter. To guarantee the security of the attempt, you must send the signed JWT to your backend to validate against the stored Onfido public key.

If the token is valid, you can authenticate the user and grant them access to your services.

If the token validation is unsuccessful, you should deny access to the user.

If the Authenticate attempt is unsuccessful, you should deny access and prompt a user retry attempt.

Onfido

Our solutions

Onfido uses 256-bit SSL encryption 100% of the time on every device.

BSI ISO/IEC27001

Onfido has been certified by BSI to ISO 27001 under certificate number IS 660122.

© Onfido™, 2021. All rights reserved.
Company Registration Number: 07479524.