OneTrust ID Verification Framework Guide

Identity (ID) verification presents one of the biggest challenges for fulfilling CCPA consumer rights requests. Integrating CCPA consumer rights requests with existing ID verification standards helps alleviate the pressures of ID verification while seamlessly maintaining the customer experience.

This guide outlines the ID verification approaches and uses cases OneTrust supports with external ID verification providers. Documentation on specific API integration use cases with select ID verification partners will be available as they are tested and validated by the OneTrust DSAR team.

ID Verification Approaches Supported by OneTrust

OpenID Connect

The OpenID Connect (OIDC) protocol is a user authentication method that improves upon on the OAuth 2.0 framework, a well-documented standard overseen by the OpenID Foundation. OneTrust supports integration partnerships with any IdP that can leverage both the OIDC implicit and authorization code grant types, allowing organizations to authenticate users with existing accounts when they access a OneTrust web form by either types.

OIDC advantages:

  • Full control over verification steps and user interface

  • Lightweight, widely supported solution

  • Ideal for more complex ID verification processes, such as selfie scans, device fingerprinting, ID scan, existing authentication frameworks (Okta, Google Authenticator, etc.)

OIDC resources:

Current Support:

Flow Type

Support

Implicit

Deprecated

Authorization Code

Yes

Auth Code w/PKCE

No

Hybrid

No

OneTrust ID Verification API

The OneTrust ID Verification API leverages a RESTful API specification that IdPs will connect to in order to support integration uses cases that require ID verification for consumer rights requests. The API specification operates as a middle layer OneTrust can call to instead of calling ID verification provider's APIs directly. Customers can implement this API standard with their preferred ID verification partners to control the decision workflow; albeit, OneTrust will determine the user interface.

ID Verification API advantages:

  • Limited return of consumer PII

  • Fast delivery with low implementation effort

  • Full control of decision workflow

The following are supported ID verification approaches under this specification:

  1. Initial Submission/Scored-Based Authentication of PII (/verify)

  2. One-Time Password (OTP) Verification (/otp)

  3. Knowledge-Based Authentication (KBA) Verification (/kba)

ID Verification API Use Cases

Initial Submission/Score-Based Authentication of PII

CODE 
POST {url}/verify

After consumers submit their PII via a OneTrust web form, the IdP will compare the data against what exists in the given system/database. If the responses match without fail, the IdP will send the response call with an OTP or KBA action, whichever is first specified by the customer in the decision workflow.

Sample Request

JSON 
{
  "firstName": "John",
  "middleName": "Q",
  "lastName": "Smith",
  "address": "123 Main St.",
  "address2": "Apt 456",
  "city": "Atlanta",
  "state": "GA",
  "zip": "30308",
  "nationalId": "1234",
  "phoneNumber": "706-555-1234", 
  "contactPreference": "T",
  "language": "en-us" 
}

Request Parameters

Name

Type

Description

firstName

String

Required

Data subject's first name

middleName

String

Optional

Data subject's middle name

lastName

String

Required

Data subject's last name

address

String

Required

Data subject's address

address2

String

Optional

Data subject's address, second line

city

String

Required

Data subject's city

state

String

Required

Data subject's two-letter state ISO code

zip

String

Required

Data subject's zip code

nationalId

String

Required

Data subject's national ID (e.g. SSN in the US)

phoneNumber

String

Optional

Data subject's phone number for OTP delivery.

Required if contact preference is voice or text.

email

String

Optional

Data subject's email for OTP delivery.

Required if contact preference is email.

contactPreference

String

Optional

Data subject's preferred OTP delivery method

  • V for voice

  • T for text

  • E for email

language

String

Optional

Data subject's preferred language code

  • en-us for English

  • es for Spanish

Sample Response

JSON 
{
  "sessionId": "a4851db3-0f8c-4e16-a79f-428d1cd796d2",
  "score": 100,
  "maxScore": 100,
  "stageResult": "PASS",
  "nextAction": "OTP"
}

Response Fields

Name

Type

Description

sessionId

String

Required

Unique identifier of the ID verification session

score

Integer

Optional

maxScore

Integer

Optional

stageResult

String

Required

See Common Response Fields

nextAction

String

Required

See Common Response Fields
CODE 
POST {url}/verify
JSON 
{
  "firstName": "John",
  "middleName": "Q",
  "lastName": "Smith",
  "address": "123 Main St.",
  "address2": "Apt 456",
  "city": "Atlanta",
  "state": "GA",
  "zip": "30308",
  "nationalId": "1234",
  "phoneNumber": "706-555-1234", 
  "contactPreference": "T",
  "language": "en-us" 
}
JSON 
{
  "sessionId": "a4851db3-0f8c-4e16-a79f-428d1cd796d2",
  "score": 100,
  "maxScore": 100,
  "stageResult": "PASS",
  "nextAction": "OTP"
}

OTP Verification

CODE 
POST {url}/otp/{sessionId}

The IdP will send an OTP to the consumer via phone number or email address to confirm they possess the contact. Consumers will submit the OTP in the OneTrust OTP collection screen, who will then forward the OTP to the IdP for verification.

Note:

After initial submission, OTP or KBA verification can occur in either order. This will be determined by the consumer during configuration of the decision workflow.

Sample Request

JSON 
{
  "code": "123456"
}

Request Parameters

Name

Type

Description

code

String

Required

OTP supplied by the data subject

Sample Response

JSON 
{
  "stageResult": "PASS",
  "nextAction": "KBA"
  "kbaQuestions": [
    {
      "id": "1",
      "text": "Which of the following addresses have you lived at?",
      "options": [
        {
          "id": "A",
          "text": "123 Main St."
        },
        {
          "id": "B",
          "text": "456 Peachtree St."
        },
        {
          "id": "C",
          "text": "789 6th St."
        }
      ]
    }
  ]
}

Response Fields

Name

Type

Description

stageResult

String

Required

See Common Response Fields

nextAction

String

Required

See Common Response Fields
CODE 
POST {url}/otp/{sessionId}
JSON 
{
  "code": "123456"
}
JSON 
{
  "stageResult": "PASS",
  "nextAction": "KBA"
  "kbaQuestions": [
    {
      "id": "1",
      "text": "Which of the following addresses have you lived at?",
      "options": [
        {
          "id": "A",
          "text": "123 Main St."
        },
        {
          "id": "B",
          "text": "456 Peachtree St."
        },
        {
          "id": "C",
          "text": "789 6th St."
        }
      ]
    }
  ]
}

KBA Verification

CODE 
POST {url}/kba/{sessionId}

The IdP will generate a multiple-choice challenge quiz that the consumer will complete to confirm their PII. The IdP will score the responses, then make one a PASS or FAIL decision.

Note:

After initial submission, OTP or KBA verification can occur in either order. This will be determined by the consumer during configuration of the decision workflow.

Sample Request

JSON 
{
  "kbaAnswers": {
    "1": "A",
    "2": "B",
    "3": "C"
  }
}

Request Parameters

Name

Type

Description

kbaAnswers

Object

Required

A map of questions of question IDs to user-selected answer IDs

Sample Response

JSON 
{
  "stageResult": "PASS",
  "nextAction": "PASS"
}

Response Fields

Name

Type

Description

stageResult

String

Required

See Common Response Fields

nextAction

String

Required

See Common Response Fields
CODE 
POST {url}/kba/{sessionId}
JSON 
{
  "kbaAnswers": {
    "1": "A",
    "2": "B",
    "3": "C"
  }
}
JSON 
{
  "stageResult": "PASS",
  "nextAction": "PASS"
}

Common Response Fields

These fields are present on all API responses under the OneTrust ID Verification API.

Name

Type

Description

stageRequest

String

Required

  • PASS

  • FAIL

nextAction

String

Required

  • ERROR: if a system error occurred. Triggers an “An error has occurred” screen and ends the verification flow.

  • SUCCESS: if the verification flow is complete and the data subject has passed verification.

  • FAIL: if the verification flow is complete and the data subject has failed verification. Sends the user to a “Your identity could not be verified” screen and ends the verification flow.

  • OTP: if the verification flow is still in progress and an OTP has been sent to the data subject.

  • KBA: if the verification flow is still in progress and quiz question(s) have been generated for the data subject to answer.

  • EMAIL

kbaQuestions

Object

Required when nextAction is KBA