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 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, [phone] or [phone].

• 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 Value	Authentication 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.