7 Data Structures
This section provides information on the core data structures/data models that are used by this Building Block.
Last updated
This section provides information on the core data structures/data models that are used by this Building Block.
Last updated
Copyright © 2024
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.
Identity verification involves the below data structures.
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:
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.
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:
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.
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:
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.
&& - 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.
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:
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.
Identity management uses these data structures.
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:
request.biometrics - The table below describes the structure for this field.
request.biometrics.segments: The table below describes the structure for this field.
Description: This field is the response received in response to the enrollment request.
Fields:
| ACR Value | Authentication Factors |
|---|---|
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
string
Email address for end user
phone
string
Primary phone for end user
locale
string
End user's locale
Name
Type
Description
Notes
profile
string
Requests access to the End-User's default profile claims
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
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.
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 )
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
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
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>
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
Click here for more information https://www.ibia.org/cbeff/iso/biometric-organizations
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>
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
