Trusted Identity Claim Verification

This document describes how to use the ID&V API for submitting trusted identity claims by using the OpenID Connect capabilities. The submitted trusted identity claims are used to upgrade the level of confidence of an identity that has been submitted.

Requirements

To enable trusted identity claims as part of an ID proofing process, a client application needs:

API Keys and URLs to access the ID proofing service
GIPS-RS key for Back-end to Back-end communication
GIPS-UA key for the end-user-facing application to the ID Proofing Back-end communication
To register with a trusted Identity Provider known by ID&V such as the IDEMIA Identity Server
To implement the OpenID Connect protocol with this Identity Provider
To enable the end-user to authenticate and provide their consent to share their identity attributes thanks to the Mobile ID Application.

Here is the documentation that describes this:

Scenarios

The OpenID Connect capabilities is used for submitting a trusted identity claim, which is combined with the ID proofing service to increase the level of confidence of an identity that's been submitted.

The OpenID connect protocol is possible in the following scenarios:

The User Agent performs the online authentication request
The Relying Party performs the online authentication request

The User Agent performs the online authentication request

Steps Overview

Create the identity.
Submit a trusted identity claim request.
Online authentication The User Agent sends the online authentication and the end-user consents for attribute sharing.
Retrieve the trusted identity claim.
Submit an identity document capture.
Retrieve the identity claim verification and identity proof results.

Steps for the User Agent to perform the online authentication request

Step 1: Create the identity.

Create an identity on the ID proofing server that will receive all of the data and gather the verification results related to this identity.

Step 2: Submit a trusted identity claim request.

The client application sends a request to submit the trusted identity claim of an individual.

The service creates a TRUSTED_ID_CLAIM evidence in the identity and returns the authorization endpoint of the Identity Provider, where the client application should authenticate itself and the end-user.

Step 3: Online authentication is obtained and the end-user consents to share attributes.

The following step is completed between the client application and the Identity Provider.

The client application obtains the Identity Provider's endpoint from the Service and sends an authentication request to the Identity Provider.
The Identity Provider responds with a redirection to a login page in the client application.
The end-user authenticates and consents to share attributes.
At the end the ID&V service receives a notification once the end-user information has been shared between the client application and the Identity Provider.

Step 4: Retrieve the trusted identity claim.

ID&V retrieves the end-user's attributes shared by the Identity Provider and enhances the identity verification.

Step 5: Submit the identity document capture.

Send the identity document images for verification.

ID&V performs the document authentication and extracts the end-user’s personally identifiable information (PII) and document information. If the ID document (ID) is valid, its status becomes VERIFIED and the ID is assigned a score depending on the number and quality of verifications that have been performed (for example, LEVEL2).

Step 6: Get the identity status and retrieve the proof.

The client application has the capability to check the status of the identity and see which Level of Assurance (LOA) has been achieved.

The end-user can submit additional pieces of evidences to increase the Level of Assurance in the identity claim being presented. Once the client application has reached the end of the process, it can close the transaction by retrieving the proof file that contains all of the identity verification details.

The Relying Party performs the online authentication request

Steps Overview

Create the identity.
Submit a trusted identity claim request.
Online authentication The User Agent sends the online authentication and the end-user consents for attribute sharing.
Retrieve the trusted identity claim.
Submit an identity document capture.
Retrieve the identity claim verification and identity proof results.

Steps for the Relying Party to perform the online authentication request

Step 1: Create the identity.

Create an identity on the ID proofing server that will receive all of the data and gather the verification results related to this identity.

Step 2: Submit a trusted identity claim request.

The client application obtains a request to submit the trusted identity claim of an individual.

The service creates a TRUSTED_ID_CLAIM evidence in the identity and returns the authorization endpoint of the Identity Provider, where the client application should authenticate itself and the end-user.

Step 3: Online authentication is obtained and the end-user consents to share attributes.

The following step is completed between the client application and the Identity provider.

The client application obtains the Identity Provider's endpoint from the service and sends an authentication request to the Identity Provider.
The Identity Provider responds with a redirection to a login page in the client application.
Then end-user authenticates and consents to share attributes.

At the end the ID&V service receives a notification once the end-user information has been shared between the client application and the Identity Provider.

Step 4: Retrieve the trusted identity claim.

ID&V retrieves the end-user's attributes shared by the Identity Provider and enriches the identity verification.

Step 5: Submit the identity document capture.

Send the identity document images for verification.

ID&V performs the document authentication and extracts the end-user’s personally identifiable information (PII) and document information. If the ID document is valid, its status becomes VERIFIED and the ID is assigned a score depending on the number and quality of verifications that have been performed (for example, LEVEL2).

Step 6: Get the identity status and retrieve the proof.

The client application has the capability to check the status of the identity and see which Level of Assurance (LOA) has been achieved.

Web Service Calls

There are many ways to implement the appropriate web service requests depending on your programming language.

For the sake of clarity, the request examples use the cURL tool syntax.

The variables used in the request URLs are:

Variable	Meaning
URL_MAIN_PART	The ID&V domain.
APIKEY_VALUE	Client application API key as provided by portal administrator(s).
IDENTITY_ID	The value obtained after performing Step 1 below. This should be the `id` value from the Create Identity response message.

Create an Identity

This request initiates the verification process with ID&V.

The request looks like this:

Shell
1curl -X POST https://[URL_MAIN_PART]/gips/v1/identities  \
2  -H 'Content-Type: multipart/form-data' \
3  -H 'apikey: [APIKEY_VALUE]'

When this request is sent, the ID&V response contains an id field. The value of that field replaces IDENTITY_ID in subsequent requests.

Sample response:

JSON
1{
2  "id": "gips-3096bbe8-ac24-4e2b-bd35-bd334714c3ec",
3  "status": "EXPECTING_INPUT",
4  "levelOfAssurance": "LOA0",
5  "creationDateTime": "2020-11-18T23:58:35.9240009",
6  "evaluationDateTime": "2020-11-18T23:58:37.5227263",
7  "upgradePaths": {}
8}

Variable	Description
id	The identity ID that will be used to identify the current transaction in subsequent requests.
status	Status of the transaction
levelOfAssurance (LOA)	The current Level of trust for that identity
creationDateTime	Identity creation date
evaluationDateTime	The date at which the identity was last evaluated
upgradePaths	List of possible submissions that would increase LOA

Submission of the end-user's trusted identity claim request

With this request, the client application can request for sharing the end-user's trust identity claim.

The request looks like this:

Shell
1curl -X POST \
2  https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/trusted-id-claim/oidc \
3    -H 'Content-Type: application/json' \
4    -H 'apikey: [APIKEY_VALUE] \
5    -d '{
6      "idpIdentifier": "MIDSERVER",
7      "oidcGrantType": "authorization_code",
8      "responseType": "JSON",
9      "postAuthRedirectUri": "https://client.redirecturi.com"
10  }'

Description of JSON fields in the payload:

Variable	Description
idpIdentifier	Contains the Identity Provider identifier
oidcGrantType	Contains the OpenID Connect's grant type. Supported value is `CODE_FLOW`
postAuthRedirectUri	Contains the redirection URI at the end of the authentication process when ID&V receives the callback with the authentication code. In case there is a `postAuthRedirectUri` sent in the request, the response when receiving the callback with the authentication code is HTTP 302 with the redirection URI. In case there is no `postAuthRedirectUri` sent in the request, the response when receiving the callback with the authentication code is HTTP 201 with no content
responseType	Contains the response type expected by the client application. Enum: allowed value `HTTP_REDIRECT` or `JSON`. In case there is the `responseType = HTTP_REDIRECT` , then the client response is HTTP 302 + location = idpAutorizeEndpoint. In case there is not a `responseType` in the input parameter or the `responseType = JSON`, then the client response is HTTP 200 with a payload containing the `idpAutorizeEndpoint`.
userIdentifier	Contains the end-user identifier used as login for online authentication against the Identity Provider.

Sample response:

JSON
1{
2  "status": "PROCESSING",
3  "type": "TRUSTED_ID_CLAIM",
4  "id": "5e836c69-c029-45eb-bb2c-c307b708e407",
5  "idpAuthorizeEndpoint": "http://localhost:1234/oidc/authorize?response_type=code&scope=openid+id_basic&client_id=@!0000F.6666.9999.5EEE!0001!55CC.EEEE!0008!A7DF.BDBF.82E3.C5C7&nonce=-6507833779997594016&acr_values=loa-2&redirect_uri=http://127.0.0.1:8080/gips/rest/callback/oidc/authorization-granted&state=Z2lwcy0zMDk2YmJlOC1hYzI0LTRlMmItYmQzNS1iZDMzNDcxNGMzZWM7NWU4MzZjNjktYzAyOS00NWViLWJiMmMtYzMwN2I3MDhlNDA3"
6}

Variable	Description
id	The evidence identifier.
status	Evidence status.
type	The evidence type.
idpAuthorizeEndpoint	The Identity Provider authorize endpoint, which contains the following data
location	Contains the OpenID Connect's authorize request parameters.
scope	Contains the OpenID Connect scope value.
client_id	This is the unique identifier provided by the Onboarding Party during Relying Party enrollment. This as the Relying Party's "username".
nonce	This string value used to associate a client session with an ID Token and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy MUST* be present in the nonce values used to prevent attackers from guessing the values.*
acr_values	This parameter controls the authentication methods that the end-user is required to perform during the authentication process.
redirect_uri	The ID&V's redirection URI where the authorization code is sent.
state	This is a secure random identifier associated with a single User Agent's authorization/authentication session. This opaque value is used to maintain the state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie.

Check the status of the end-user's trusted identity claim

With this request, the client application can check the processing status of the end-user's claim identity and see what Level of Assurance (LOA) has been reached.

The request looks like this:

Shell
1curl -X GET \
2  https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/trusted-id-claims \
3  -H 'Content-Type: application/json' \
4  -H 'apikey: [APIKEY_VALUE]'

Sample response:

JSON
1{
2  "globalStatus": {
3    "id": "gips-3096bbe8-ac24-4e2b-bd35-bd334714c3ec",
4    "status": "EXPECTING_INPUT",
5    "levelOfAssurance": "LOA1",
6    "creationDateTime": "2020-11-18T23:58:35.9240009",
7    "evaluationDateTime": "2020-11-19T00:03:38.8673054",
8    "nameReferenceEvidenceId": "5e836c69-c029-45eb-bb2c-c307b708e407",
9    "upgradePaths": {}
10  },
11  "trustedIdClaim": {
12    "evidenceId": "5e836c69-c029-45eb-bb2c-c307b708e407",
13    "submitDateTime": "2020-11-19T00:00:43.8451989",
14    "type": "TRUSTED_ID_CLAIM",
15    "evidenceStatus": {
16      "evaluationDateTime": "2020-11-19T00:03:38.8673054",
17      "status": "VERIFIED",
18      "strength": "LEVEL3",
19      "score": "LEVEL3",
20      "isAdjudicable": false
21    },
22    "idpIdentifier": "MIDSERVER",
23    "oidcGrantType": "authorization_code",
24    "portraitReferenceId": "44406fb1-9079-47db-8080-104f6c3b8839",
25    "trustedIdClaimData": {
26      "idDocumentType": "DRIVING_LICENSE",
27      "idDocumentNumber": "Q88705989",
28      "issuingDate": "2013-01-10",
29      "expiryDate": "2028-02-01",
30      "personalAttributes": {
31        "givenNames": [
32          {
33            "value": "CHRISTOPHE",
34            "verified": true
35          }
36        ],
37        "surname": {
38          "value": "ULYSSE",
39          "verified": true
40        },
41        "dateOfBirth": {
42          "value": "1960-04-10",
43          "verified": true
44        },
45        "gender": {
46          "value": "M",
47          "verified": true
48        }
49      },
50      "address": {
51        "streetDetails": {
52          "streetLines": ["8840 w russell road"],
53          "verified": true
54        },
55        "postcode": "85001",
56        "city": "MINNEAPOLIS",
57        "country": "USA",
58        "verified": true
59      }
60    }
61  }
62}

Values for status can be:

VERIFIED - means that evidence has successfully been verified. When VERIFIED, an identity claim is scored on LEVEL 3.
INVALID - means that the evidence is considered invalid after the checks are performed.
NOT_VERIFIED - means that the evidence was processed, but not enough checks were performed to make a decision.
PROCESSING - means that the evidence is currently being processed by the service.

Check the status of the identity submitted

With this request, the client application can check the status of the identity and see what Level of assurance (LOA) has been reached.

The request looks like this:

Shell
1curl -X GET \
2https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID] \
3-H 'Content-Type: application/json' \
4    -H 'apikey: [APIKEY_VALUE]'

Sample response:

JSON
1{
2  "globalStatus": {
3    "id": "gips-3096bbe8-ac24-4e2b-bd35-bd334714c3ec",
4    "status": "EXPECTING_INPUT",
5    "levelOfAssurance": "LOA1",
6    "creationDateTime": "2020-11-18T23:58:35.9240009",
7    "evaluationDateTime": "2020-11-19T00:06:26.416222",
8    "nameReferenceEvidenceId": "5e836c69-c029-45eb-bb2c-c307b708e407",
9    "upgradePaths": {}
10  },
11  "attributes": [
12    {
13      "evidenceId": "6c3531c2-fc98-4f04-9d9e-f6fec07fbb0f",
14      "submitDateTime": "2020-11-19T00:03:38.8284114",
15      "type": "ATTRIBUTES",
16      "evidenceStatus": {
17        "evaluationDateTime": "2020-11-19T00:06:26.416222",
18        "status": "VERIFIED",
19        "strength": "LEVEL5",
20        "score": "LEVEL3",
21        "isAdjudicable": false
22      },
23      "attributesData": {
24        "givenNames": [
25          {
26            "value": "CHRISTOPHE",
27            "verified": true
28          }
29        ],
30        "surname": {
31          "value": "ULYSSE",
32          "verified": true
33        },
34        "dateOfBirth": {
35          "value": "1960-04-10",
36          "verified": true
37        },
38        "gender": {
39          "value": "M",
40          "verified": true
41        }
42      }
43    }
44  ],
45  "addresses": [
46    {
47      "evidenceId": "1f39161b-72d2-4aa7-9cdd-696da9fd1aef",
48      "submitDateTime": "2020-11-19T00:00:43.8451999",
49      "type": "ADDRESS",
50      "evidenceStatus": {
51        "evaluationDateTime": "2020-11-19T00:06:26.416222",
52        "status": "VERIFIED",
53        "strength": "LEVEL5",
54        "score": "LEVEL3",
55        "isAdjudicable": false
56      },
57      "referenceIds": ["5e836c69-c029-45eb-bb2c-c307b708e407"],
58      "addressData": {
59        "streetDetails": {
60          "streetLines": ["8840 w russell road"],
61          "verified": true
62        },
63        "postcode": "85001",
64        "city": "MINNEAPOLIS",
65        "country": "USA",
66        "verified": true
67      }
68    },
69    {
70      "evidenceId": "6f8f6750-c4f1-49ed-9459-f4987bc64e34",
71      "submitDateTime": "2020-11-19T00:06:24.6170472",
72      "type": "ADDRESS",
73      "evidenceStatus": {
74        "evaluationDateTime": "2020-11-19T00:06:26.416222",
75        "status": "NOT_VERIFIED",
76        "strength": "LEVEL5",
77        "score": "LEVEL0",
78        "isAdjudicable": false
79      },
80      "referenceIds": ["62333961-8885-48bc-99a5-71caad2cbdd9"],
81      "addressData": {
82        "streetDetails": {
83          "streetLines": ["12 COTTONWOOD RD", "SUITE 1001"],
84          "verified": true
85        },
86        "postcode": "12345",
87        "city": "EMPIRE",
88        "state": "NV",
89        "country": "USA",
90        "verified": true
91      }
92    }
93  ],
94  "idDocuments": [
95    {
96      "evidenceId": "62333961-8885-48bc-99a5-71caad2cbdd9",
97      "submitDateTime": "2020-11-19T00:06:24.6170462",
98      "type": "DRIVING_LICENSE",
99      "evidenceStatus": {
100        "evaluationDateTime": "2020-11-19T00:06:26.416222",
101        "status": "INVALID",
102        "strength": "LEVEL3",
103        "score": "LEVEL0",
104        "isAdjudicable": false,
105        "errors": [
106          {
107            "code": "1131",
108            "message": "Identity attributes don't match with evidences"
109          }
110        ],
111        "positiveIndicators": [
112          "DOC_EXPIRATION_DATE_OK",
113          "ISSUING_DATE_VALIDITY_OK",
114          "MODEL_RECOGNIZED_OK",
115          "VISUAL_SECURITY_OK",
116          "DOC_ISSUING_COUNTRY_OK",
117          "DOC_NATIONALITY_OK",
118          "OCR_EXPIRATION_DATE_OK",
119          "GLARE_IMAGE_QUALITY_FRONT_OK",
120          "OCRX_OK",
121          "PAPER_COPY_OK",
122          "PHOTO_LOCATION_OK",
123          "BIRTHDATE_VALID_OK",
124          "OCR_ISSUING_DATE_OK",
125          "EXPIRATION_DATE_CONSISTENCY_OK",
126          "DOCUMENT_BARCODE_PARSING_OK",
127          "BLUR_IMAGE_QUALITY_FRONT_OK",
128          "OCR_DOCNUM_OK",
129          "OCR_BIRTHDATE_OK",
130          "OCR_FIRSTNAMES_OK",
131          "IMAGE_FRONT_DPI_CHECK_OK",
132          "OCR_SEX_OK",
133          "OCR_FULLNAME_OK",
134          "MODEL_COLOR_MATCHING_OK",
135          "HIGH_TEMPLATE_OK",
136          "CB2D_FIELDS_SYNTAX_OK",
137          "LOW_TEMPLATE_OK",
138          "PHOTOCOPY_DETECTION_OK",
139          "PERSONAL_NUMBER_CHECKSUMS_OK",
140          "PORTRAIT_OK",
141          "LCD_DETECTION_OK",
142          "ESFX_OK",
143          "SIDES_DATA_CONSISTENCY_OK"
144        ],
145        "warningIndicators": [
146          "LOW_IMAGE_QUALITY_FRONT_WARNING",
147          "KEYSTONE_IMAGE_QUALITY_FRONT_WARNING",
148          "BLUR_IMAGE_QUALITY_BACK_WARNING",
149          "GLARE_IMAGE_QUALITY_BACK_WARNING"
150        ],
151        "unverifiedIndicators": [
152          "MRZ_CHECKSUMS_UNVERIFIED",
153          "DOCUMENT_NUMBER_VALIDITY_UNVERIFIED",
154          "COMPROMISED_DOCUMENT_CHECK_UNVERIFIED",
155          "TEXTURE_ANALYSIS_UNVERIFIED",
156          "MRZ_BARCODE_CROSSCHECK_UNVERIFIED"
157        ]
158      },
159      "idDocumentData": {
160        "idDocumentType": "DRIVING_LICENSE",
161        "idDocumentNumber": "000000000016",
162        "issuingCountry": "USA",
163        "issuingState": "WA",
164        "issuingDate": "2015-04-01",
165        "expiryDate": "2021-04-01",
166        "personalAttributes": {
167          "givenNames": [
168            {
169              "value": "CHRISTOPHE",
170              "verified": false
171            }
172          ],
173          "surname": {
174            "value": "ULYSSE",
175            "verified": false
176          },
177          "fullname": {
178            "value": "CHRISTOPHE ULYSSE",
179            "verified": false
180          },
181          "dateOfBirth": {
182            "value": "1968-10-18",
183            "verified": false
184          },
185          "gender": {
186            "value": "M",
187            "verified": false
188          },
189          "eyeColor": {
190            "value": "GRAY",
191            "verified": false
192          },
193          "height": {
194            "value": "6' 6",
195            "verified": false
196          }
197        },
198        "address": {
199          "streetDetails": {
200            "streetLines": ["12 COTTONWOOD RD", "SUITE 1001"],
201            "verified": true
202          },
203          "postcode": "12345",
204          "city": "EMPIRE",
205          "state": "NV",
206          "country": "USA",
207          "verified": true
208        }
209      }
210    }
211  ],
212  "trustedIdClaim": {
213    "evidenceId": "5e836c69-c029-45eb-bb2c-c307b708e407",
214    "submitDateTime": "2020-11-19T00:00:43.8451989",
215    "type": "TRUSTED_ID_CLAIM",
216    "evidenceStatus": {
217      "evaluationDateTime": "2020-11-19T00:06:26.416222",
218      "status": "VERIFIED",
219      "strength": "LEVEL3",
220      "score": "LEVEL3",
221      "isAdjudicable": false,
222      "positiveIndicators": ["OIDC_AUTHENTICATION_OK"]
223    },
224    "idpIdentifier": "MIDSERVER",
225    "oidcGrantType": "authorization_code",
226    "portraitReferenceId": "44406fb1-9079-47db-8080-104f6c3b8839",
227    "trustedIdClaimData": {
228      "idDocumentType": "DRIVING_LICENSE",
229      "idDocumentNumber": "Q88705989",
230      "issuingDate": "2013-01-10",
231      "expiryDate": "2028-02-01",
232      "personalAttributes": {
233        "givenNames": [
234          {
235            "value": "CHRISTOPHE",
236            "verified": true
237          }
238        ],
239        "surname": {
240          "value": "ULYSSE",
241          "verified": true
242        },
243        "dateOfBirth": {
244          "value": "1960-04-10",
245          "verified": true
246        },
247        "gender": {
248          "value": "M",
249          "verified": true
250        }
251      },
252      "address": {
253        "streetDetails": {
254          "streetLines": ["8840 w russell road"],
255          "verified": true
256        },
257        "postcode": "85001",
258        "city": "MINNEAPOLIS",
259        "country": "USA",
260        "verified": true
261      }
262    }
263  }
264}

Check the levelOfAssurance value to see the current score of the identity created.

The client application can also check the status of all the submitted data:

The trusted ID Claim is summarized in the “trustedIdClaim” structure.
The portrait is summarized in the “portrait” structure.

The rest of the response contains various information like the upgrade path to improve LOA or attributes (personal information extracted from documents or submitted by the end-user).

Ending the process and retrieving the proof file

With this request, the client application terminates the proofing process and retrieves all information that the Service has gathered and generated.

In response to this request, the client application receives an archive file. The client application may archive this file for audit purposes and use its content as a reference for the end-user's identity.

Getting the proof terminates the transaction and the Service applies the deletion policy to the personal information gathered during the session.

The request looks like this:

Shell
1curl -X GET \
2https://[URL_MAIN_PART]/gips/v1/identities/[IDENTITY_ID]/proof \
3-H 'apikey: [APIKEY_VALUE]' -o proof

Variable	Description
URL_MAIN_PART	The Service domain.
APIKEY_VALUE	Client application API key as provided by your administrator(s).
IDENTITY_ID	Value obtained after performing Step 1. This value should be the `id` value from the Create Identity response message.

API Feedback

This section contains error codes and indicators raised when verifying the end-user's trusted identity claim.

Error Codes

Error codes in relation to the end-user's trusted identity claim:

Error Code	Description
2301	Authentication has failed.
2302	The authorization server is unavailable.
2303	Access denied.

Indicators

ID&V is configured by default, with the following blocking indicators:

Indicator Name	Description
OIDC_AUTHENTICATION	Check that the authorization server issues an authorization code allowing to retrieve the trusted identity claim.

Scoring

Once an end-user's trusted identity claim has been submitted, results of the checks are combined by the ID proofing service to increase the level of assurance in the presented credential.

Here is the summary of the identity claim scoring:

Evidence Type	Status	Score	Description
TRUSTED_ID_CLAIM	NOT_VERIFIED	LEVEL0	The evidence was processed, but the attribute sharing was not performed successfully.
	INVALID	LEVEL0	The trusted Identity claim is considered invalid after the end-user's authentication fails
	VERIFIED	Variable	The trusted identity claim has successfully been shared. The trusted identity claim score depends on the selected Identity Provider.