7 Data Structures

This section provides information on the core data structures/data models that are used by this Building Block.

7.1 Resource Model

Identity and Verification Building Block requires data objects, below are the main ones involved listed:

  • Identities of individuals identified by unique identifiers.

  • Identifiers:

    • Token numbers are associated uniquely with a set of data, and identifiers are used to refer to those data without having to actually copy them.

    • They can be stored then in separate repositories with specific restricted access.

    • Identifiers can be used to uniquely identify Foundational IDs or Functional IDs.

    • Token identifiers can be used to avoid data aggregation and ensure capacity to forget an identity.

    • As identity data should be stored in different storage to ensure privacy protection allowing then data separation and data minimization principles, it’s necessary to use different identifiers for different types of data.

  • Credentials:

    • Issued for individuals or presented by them, ID Credentials related to an individual should be traced and accessible in the system in order to have the capacity to identify fraud and do an investigation on them, so as to perform auditing.

  • Registration requests

    • Requests will be received by the Identity and Verification Building Block, for example, identity enrollment requests or identity data update registration requests, those requests will be then managed by the different subsystems and the workflows of the Identity and Verification Building Block.

  • Identification Services

    • A set of services will be offered on top of identities to identify a person, check some of his/her attributes (i.e. age), or obtain some certified personal information when needed and authorized.

  • Third parties service user entities

    • External entities which could be GovStack Building Blocks or not, will have access to and use the services, for that purpose, their access will be granted, consent may be given by the individuals and their activities will be logged.

7.2 Identity verification Data Structures

Identity verification involves the below data structures.

7.2.1 End-User Claim

Description: End-user claim is the user information that can be shared with the relying party once the end-user authentication is completed in the Identity Building Block. Below is a set of standard claims that will be supported by the Identity Building Block implementation

Fields:

Name

Type

Description

Notes

sub

string

Subject identifier

Contains the value of the PSUT

name

string

Full name for this end user

address

string

Address of the end user

gender

string

End user gender

birthdate

date

End user birthdate

picture

URL

URL to location where end user's picture is stored

email

string

Email address for end user

phone

string

Primary phone for end user

locale

string

End user's locale

  • sub - Subject identifier with the value of PSUT (Partner Specific User Token). This value should be unique for the end user and relying party combination. The same user should have a different subject identifier in different relying party systems to preserve privacy. It must not exceed 255 ASCII characters in length. The sub-value is a case-sensitive string.

  • name - End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences.

  • given_name - Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

  • family_name - Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

  • middle_name - Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.

  • nickname - Casual name of the End-User that may or may not be the same as the given_name.

  • preferred_username - Shorthand name by which the End-User wishes to be referred to at the RP. This value may be any valid JSON string including special characters such as @, /, or whitespace. The RP must not rely upon this value being unique.

  • address - End-User's postal address. The value of the address member is a JSON structure containing some or all of the members from the below list.

    • formatted - Full mailing address, formatted for display or use on a mailing label. This field may contain multiple lines, separated by newlines. Newlines can be represented either as a carriage return/line feed pair ("\r\n") or as a single line feed character ("\n").

    • street_address - Full street address component, which MAY include house number, street name, Post Office Box, and multi-line extended street address information. This field may contain multiple lines, separated by newlines. Newlines can be represented either as a carriage return/line feed pair ("\r\n") or as a single line feed character ("\n").

    • locality - City or locality component.

    • region - State, province, prefecture, or region component.

    • postal_code - Zip code or postal code component.

    • country - Country name component.

  • gender - End-User's gender. Values defined by this specification are female and male. Other values may be used when neither of the defined values is applicable.

  • birthdate - End-User's birthday, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format. The year MAY be 0000, indicating that it is omitted. To represent only the year, YYYY format is allowed.

  • picture - URL of the End-user's profile picture. This URL must refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.

  • email - End-User's preferred e-mail address. Its value must conform to the RFC 5322 [RFC5322] addr-spec syntax.

  • email_verified - True if the End-user's e-mail address has been verified; otherwise false.

  • phone_number - End-User's preferred telephone number. E.164 [E.164] is RECOMMENDED as the format of this Claim, for example, +1 (425) 555-1212 or +56 (2) 687 2400.

  • phone_number_verified - True if the End-user's phone number has been verified; otherwise false.

  • locale - End-User's locale, represented as a BCP47 [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA.

  • zoneinfo - String from zoneinfo time zone database representing the End-User's time zone. For example, Europe/Paris or America/Los_Angeles.

7.2.2 Scope

Description: Scopes can be used to request that specific sets of information be made available as claim values. The following scope values will be supported by Identity Building Block implementation for requesting specific details of end-user.

Fields:

Name

Type

Description

Notes

profile

string

Requests access to the End-User's default profile claims

email

string

Requests access to the email and email_verified claim

address

string

Requests access to the address claim

phone

string

Requests access to the phone_number and phone_number_verified claim

The following claims are used within the ID Token

  • profile -This scope value requests access to the End-User's default profile claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, picture, gender, birthdate, zoneinfo and locale.

  • email - This scope value requests access to the email and email_verified claim.

  • address - This scope value requests access to the address claim.

  • phone - This scope value requests access to the phone_number and phone_number_verified claim.

7.2.3 ID Token

Description: The ID Token is a security token that contains the end user's basic identifier information and a few other claims about the authentication event. The ID Token is represented as a JSON Web Token (JWT) [JWT].

Fields:

Name

Type

Description

Notes

iss

URL

Issuer identifier for the Identity Building Block implementation

sub

string

Subject identifier with the value of PSUT (Partner Specific User Token)

Should be unique for the end user

aud

string

Audience that this ID Token is intended for

Must contain the OIDC client_id

exp

number

Expiration time on or after which the Access Token must not be accepted for processing

iat

number

Time at which the JWT was issued

auth_time

number

Time when the End-User authentication occurred

nonce

string

Used to associate a Client session with an ID Token, and to mitigate replay attacks

acr

string

Specifying an Authentication Context Class Reference value that identifies which was satisfied

at_hash

string

Access Token hash value.

  • iss - Issuer identifier for the Identity Building Block implementation. The iss value is a case-sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.

  • sub - Subject identifier with the value of PSUT (Partner Specific User Token). This value should be unique for the end user and relying party combination. Same user should have a different subject identifier in different relying party systems to preserve privacy. It must not exceed 255 ASCII characters in length. The sub-value is a case-sensitive string.

  • aud - Audience that this ID Token is intended for. It must contain the OIDC client_id of the Relying Party as an audience value.

  • exp - Expiration time on or after which the ID Token must not be accepted for processing. The processing of this parameter requires that the current date/time must be before the expiration date/time listed in the value. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

  • iat - Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

  • auth_time - Time when the End-User authentication occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

  • nonce - 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. If present in the ID Token, Clients MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authentication Request.

  • acr - Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied. Below is the list of supported ACRs based on the authentication factors implemented by the Identity Building Block implementation.

ACR ValueAuthentication Factors

idbb:acr:static-code

PIN || Password

idbb:acr:generated-code

OTP || TOTP

idbb:acr:linked-wallet

WLA (Wallet Local Authentication)

idbb:acr:biometrics

BIO (Biometrics from a L1 SBI device)

idbb:acr:biometrics-generated-code

BIO && ( OTP || TOTP )

idbb:acr:linked-wallet-static-code

WLA && ( PIN || Password )

&& - This is a multi-factor authentication where both auth factors need to be authenticated.

|| - This is a condition where there is more than one auth factor which shares the same ACR level.

  • at_hash - Access Token hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token's JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The at_hash value is a case-sensitive string.

7.2.4 Access Token

Description: Access token represents the authorization of a specific application to access specific parts of a user’s data. The Access Token is represented as a JSON Web Token (JWT) [JWT].

Fields:

Name

Type

Description

Notes

iss

URL

Issuer identifier for the Identity Building Block implementation

exp

number

Expiration time on or after which the Access Token must not be accepted for processing

Current date/time must be before the expiration date/time listed

aud

string

Audience that this Access Token is intended for

sub

string

Subject identifier

Contains the value of PSUT

client_id

string

The OIDC client identifier that was assigned to the relying party when the client registration is done

iat

number

Time at which the JWT was issued

jti

string

JWT ID provides a unique identifier for the JWT

  • iss - Issuer identifier for the IDBB implementation. The iss value is a case-sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.

  • exp - Expiration time on or after which the Access Token must not be accepted for processing. The processing of this parameter requires that the current date/time must be before the expiration date/time listed in the value. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

  • aud - Audience that this Access Token is intended for. It must contain the OIDC client_id of the Relying Party as an audience value.

  • sub - Subject identifier with the value of PSUT (Partner Specific User Token). This value should be unique for the end user and relying party combination. Same user should have a different subject identifier in different relying party systems to preserve privacy. It must not exceed 255 ASCII characters in length. The sub-value is a case-sensitive string.

  • client_id - The OIDC client identifier that was assigned to the relying party when the client registration is done.

  • iat - Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

  • jti - JWT ID provides a unique identifier for the JWT. The identifier value must be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object. This can be used to prevent the JWT from being replayed. The jti value is a case-sensitive string.

7.3 Identity Management Data Structures

Identity management uses these data structures.

7.3.1 Enrollment Request

Description: The purpose of enrollment request is create/update enrollment of users using new registration process, importing data from existing servers, or a mix of these two processes.

Fields:

Name

Type

Description

Example

id

string

ID of the API

mosip.resident.enrollment

version

string

Version of the API

v1

requesttime

string

Request time of the API

2022-06-06T13:24:50.605Z

request

object

Request Object

request.offlineMode

boolean

Offline mode

false

request.id

string

ID of the packet

10001100020010120230704042404

request.refId

string

Reference ID used in multi-step enrolment

10001_10002

request.fields

object

Fields of the Packet in key-value pair

{

"gender": "[ { "language" : "eng", "value" : "Male" } ]",

"city": "[ { "language" : "eng", "value" : "Kenitra" } ]",

"postalCode": "14022",

"fullName": "[ { "language" : "eng", "value" : "Enrollment89 I290" } ]",

"dateOfBirth": "1988/11/07", email": "techece@gmail.com"

}

request.metaInfo

object

Metainfo of the Packet in key-value pair

{

"metaData": "[ { label" : "centerId",

"value" : "10001" }, { "label" : "machineId", "value" : "10002" }, { "label" : "REGISTRATIONTYPE", "value" : null } ]"

}

request.process

string

Process of the Packet

NEW, UPDATE, DEMO, BIO etc.

request.source

string

Source of the Packet

REGISTRATION_CLIENT

request.audits

Array of JSON strings

Audit trail of the Packet in key-value pair

[

{

"eventId": "RPR_405",

"hostName": "Techno-367",

"sessionUserId": "mosip",

"idType": "REGISTRATION_ID",

"hostIp": "192.168.1.100",

"moduleName": "REQUEST_HANDLER_SERVICE",

"description": "Packet uploaded successfully",

"eventType": "USER"

}

]

request.biometrics

object

Biometrics of the Packet (click here)

Explained in the next table

request.documents

object

Documents of the Packet

  • request.biometrics - The table below describes the structure for this field.

Name

Type

Description

Example

version

object

Contains information about the version of the BIR

version.major

integer<int32>

Major version number

1

cbeffversion

object

Contains information about the version of the CBEFF being used.

cbeffversion.major

integer<int32>

Major version number of CBEFF

1

cbeffversion.minor

integer<int32>

Minor version number of CBEFF

1

birInfo

object

Contains information about the specific BIR; Click this link for more information: https://www.ibia.org/cbeff/iso/bir-header-identifiers

birInfo.creator

string

NA

birInfo.index

string

NA

birInfo.payload

Array of strings<byte>

NA

birInfo.integrity

boolean

Indicates whether the integrity of the specific BIR is true or false

False

birInfo.creationDate

string<date-time>

The date and time when the BDB was created

"2019-06-27T13:40:06.209Z"

birInfo.notValidBefore

string<date-time>

NA

birInfo.notValidAfter

string<date-time>

NA

segments

Array of objects (Biometric Information Record)

Segments contains each and every BIR. For example, if 10 fingers, 2 irises and one face is captured then segments will contain 13 BIRs (10+2+1)

Explained in the next table

others

Array of objects (BIR)

This section contains all the subtypes captured.

<others>

<entry key="CONFIGURED">

leftEye,rightEye,

rightIndex,rightLittle,rightRing,

rightMiddle,leftIndex,

leftLittle,leftRing,

leftMiddle,leftThumb,

rightThumb,face</entry>

</others>

  • request.biometrics.segments: The table below describes the structure for this field.

Name

Type

Description

Example

version

object

Contains information about the version of the BIR

version.major

integer <int32>

Major version number

1

version.minor

integer <int32>

Minor version number

1

cbeffversion

object

Contains information about the version of the CBEFF being used.

cbeffversion.major

integer <int32>

Major version number of CBEFF

1

cbeffversion.minor

integer <int32>

Minor version number of CBEFF

1

birInfo

object

Contains information about the specific BIR; Click for more information: https://www.ibia.org/cbeff/iso/bir-header-identifiers

birInfo.creator

string

NA

birInfo.index

string

NA

birInfo.payload

Array of strings <byte>

NA

birInfo.integrity

boolean

Indicates whether the integrity of the specific BIR is true or false

false

birInfo.creationDate

string<date-time>

The date and time when the BDB was created

"2019-06-27T13:40:06.209Z"

birInfo.notValidBefore

string<date-time>

NA

birInfo.notValidAfter

string<date-time>

NA

bdbInfo.challengeResponse

Array of strings <byte>

NA

bdbInfo.index

string

Unique index for each bdb (UUID)

362dc162-6cf9-48ae-a914-0feb1934b587

bdbInfo.format

object

The bdb format

bdbInfo.format.organization

string

The organization

Mosip

bdbInfo.format.type

string

Org type

8

bdbInfo.encryption

boolean

Bdb encryption status

true

bdbInfo.creationDate

string<date-time>

The creation date

"2023-06-09T06:59:32.946225700Z"

bdbInfo.notValidBefore

string<date-time>

NA

bdbInfo.notValidAfter

string<date-time>

NA

bdbInfo.type

Array of strings

Captured biometric type.

FACE/FINGER/IRIS

bdbInfo.subtype

Array of strings

Subtype captured like “Left Iris”, “Right Iris”

Left Index Finger

bdbInfo.level

string

Level of bdb

Enum: "RAW" "INTERMEDIATE" "PROCESSED"

bdbInfo.product

object

NA

bdbInfo.product.organization

string

MOSIP

bdbInfo.product.type

string

8

bdbInfo.captureDevice

object

Capture device information

bdbInfo.captureDevice.organization

string

Organization of capture device

MOSIP

bdbInfo.captureDevice.type

string

Type of capture device

Face

bdbInfo. featureExtractionAlgorithm

object

NA

bdb. featureExtractionAlgorithm.type

string

NA

bdbInfo. comparisonAlgorithm

object

NA

bdb. comparisonAlgorithm.organization

string

NA

bdb. comparisonAlgorithm.type

string

NA

bdbInfo. compressionAlgorithm

object

NA

bdb. compressionAlgorithm.organization

string

NA

bdb. compressionAlgorithm.type

string

NA

bdb.purpose

string

Purpose of capturing BDB.

Enum: "VERIFY" "IDENTIFY" "ENROLL" "ENROLLVERIFY" "ENROLLIDENTIFY" "AUDIT"

ENROLL

bdb.quality

object

The quality score while capturing biometrics

bdb.quality.algorithm

object

The algorithm used

bdb.quality.algorithm.organization

string

HMAC

bdb.quality.algorithm.type

string

SHA-256

bdb.quality.score

integer<int64>

The quality score

100

bdb.quality.qualityCalculationFailed

string

NA

bdb

Array of strings <byte>

Contains the actual biometric data

sb

Array of strings <byte>

The biometric signature block

birs

Array of objects (BIR)

These elements represent individual biometric records. There are multiple instances of , each representing a different biometric sample (e.g., fingerprints, face, iris).

sbInfo

object

Biometric signature block information

sbInfo.format

object

Format of signature

sbInfo.format.organization

string

Organization

MOSIP

sbInfo.format.type

string

NA

others

object

Additional information about the capture

<others>

<entry key="SPEC_VERSION"></entry>

<entry key="RETRIES">0</entry>

<entry key="FORCE_CAPTURED">false</entry>

<entry key="EXCEPTION">true</entry>

<entry key="PAYLOAD"></entry>

<entry key="SDK_SCORE">0.0</entry>

</others>

7.3.2 Enrollment Response

Description: This field is the response received in response to the enrollment request.

Fields:

Name

Type

Description

Example

id

string

ID of the API

version

string

Version of the API

responsetime

string<date-time>

Response time of the API

2023-06-09T06:59:32.946225700Z

metadata

object

Metainfo of the Packet in key-value pair

NULL

response

Array of objects

Response of the API

response.id

string

The registration id

rid

response.packetName

string

The sub packet name

Id / optional / evidence

response.source

string

Packet source. Typically name of the source system

REGISTRATION_CLIENT

response.process

string

The packet process. Could be NEW/UPDATE/LOST or a newly created process

NEW/UPDATE/LAST

response.refId

string

The reference id used for getting the private key from keymanager. Typically centerid_machineid

110011_110011

response.schemaVersion

string

The id schema version

0.1

response.signature

string

The packet signature

The signature string

response.encryptedHash

string

The sub packet encrypted hash value

The encrypted hash string

response.providerName

string

The packet store provider

PacketWriterImpl

response.providerVersion

string

The version of provider

1.0

response.creationDate

string

The packet creation date

2023-06-09T06:59:32.946225700Z

errors

Array of objects

Errors if any

errors.errorCode

string

The error code

errors.message

string

The error message

Last updated

Copyright © 2024