Developed by Jaume Dubois (ID30), Ramesh Narayanan (MOSIP), Sasikumar Ganesan (MOSIP), Vishwanath V (MOSIP), Dr. P. S. Ramkumar (ITU), Torsten Lodderstedt (OpenID Foundation), Jane Rose (Technoforte), Smita Selot (Technoforte)

The functional requirements of the Identity Building Block cover the full life cycle or a Foundational ID so as the services offered to use that Identity. The Identity Building Block must offer functionalities to onboard new individuals, update and manage the life cycle of personal data, issue unique identifiers, issue physical or digital credentials, publish identity change events, and offer services to verify identity.

The Identity Build Block must have any response data payload it returns through its API only in the form of JSON or YAML formatted datasets. It is left to the application consuming the response to present it appropriately (e.g. as an Event list or calendar) and provision for associated user interface interactions.

The Identitity Building Block must enable usage from the following actors:

• "BB_Admin" who manages this Building Block to run efficiently in a hosted environment;

• "Partners" who get registered and can obtain access to services after authorization ;

• "Users" who will manage their Identity information, access to this information by third parties, credentials and preferences;

• "Subscribers" will be notified of identity change events after registration.

The internal storage of the Identity Building Block must hold the configuration, status, and logged information of all scheduled events. It must also maintain a repository of details of Partners, Users and Subscribers. The Key digital functionalities that are considered within the current scope of the specifications are listed below:

4.2 Core Services

This section provides a description of the Key Functionalities for each of the core services of the Identity Building Block that was described in Section 2.

4.2.1 Identity Usage

Registered and Authorized Partners have access to Identity Building Block Usage APIs to request Authentication of Users, if successful they can collect personal information after a User informed consent is given. For a specific Partner and a specific User, the Identity Building Block will produce a unique and repeatable Partner Specific User Token (PSUT).

4.2.2 Enrollment services

Enrollment services exposes API to on-board new identities, this API is to be used by registration systems that may vary in their form and technologies, this API is there to receive the raw data in a predefined format.

• The enrollment service will need to evaluate the identity related claims based on the registration data (e.g. differentiating between self-asserted or vouched for data in comparison to data coming from an authoritative source (such as a CRVS system). Depending on the context, some of this data (and meta-data) might need to be archived for audit purposes or to allow for repeated anti-fraud checks (e.g. data from an authoritative source was used but subsequently was reported lost / stolen). As this meta-data forms the basis of the resulting identity service, only identity-specific data needs to be stored in the live system, with meta-data being held separately (and under additional security controls).

• Enrollment services may be designed to be permissive, i.e. allowing for enrollment based on partial / poor quality data dependent on the context.

• Those data need to be traceable and auditable so they should come in with all evidence and capture contextual meta-data, but should not permit tracking of such without evidence of permission (declarative process)

4.2.3 Credential Management Services

Credential Management Services exposes an API to get access and update the credential associated to the identity, also manage issuance and life-cycle of credentials whatever physical or digital.

4.2.4 Identity and Verification Services

Identity and Verification Services expose APIs to offer identification services to the 3rd party players . Those services can be: identity verification, attributes sharing or answers to claims (ie I claim I’m older than 18 years old) Usage can be multiple in public services, but also private, even cross-countries. They can be based on identity attributes : text, biometrics, also known documents and even on what people know (PIN code, Passport) or what they own (smartphone with SIM card)

4.2.5 Notifications Services

Notification Services expose APIs which allow triggering of external processes according to events happening on the identity data managed by the identity system (ie name change, death, new child born, document lost or stolen, etc.) In order to preserve privacy and respect the principle of single source of truth, the notification should only mention an identity change event to a set of subscribers for them to be aware they may need to refresh a right or create a new record in their system (ie: a birth may generate change in households register of social security and or person reaching 60 may be allowed to retirement pension)

4.2.6 Federations Services

Federation Services expose APIs allowing federation of identities from external identity providers. Indeed, individuals may already have an existing form of digital identity they need to keep using and would like to associate with their national identity. In that case the Federation services will be able to attach those forms of identity based on their identifier to their national identity managed by IDV BB, also to allow delegation to them of individual’s authentication.

Registered and Authorized Partners have access to Identity Building Block Usage APIs to request Authentication of Users, if successful they can collect personal information after a User informed consent is given. For a specific Partner and a specific User, the Identity Building Block will produce a unique and repeatable Partner Specific User Token (PSUT).

4.2 Identity Management

New Users can be on-boarded following an Enrollment process, this process can be composed of one or several steps with data coming from one or multiple sources. Once a new identity has been registered a Unique Identifier will be generated for further representing the User in the GovStack. For privacy purposes, this Unique Identifier will be kept secret inside the Identity Management system, and tokens (randomly generated identifiers) or aliases (existing identifiers) will be linked to it and shared with the User for further involvement in the Usage APIs or for the Credential management. User Interfaces and APIs will allow a user to have a management of its personal data for CRUD requests (Create, Read, Update, Delete) according to GDPR regulation and to the Adopting Country laws, policies and practices. A User will have the possibility to generate a temporary and revokable Virtual ID to preserve its privacy for temporary use. A User will have the possibility to link an existing personal identifier for leveraging on existing forms of trusted ID (i.e. ID Card Number, Passport Number, Phone Number, e-mail address, etc.) this identifier will be usable within ID Usage services.

4.3 Credential Management

A User will have the possibility to generate Credentials containing a set of claims, being personal attributes or declarations (i.e. I am an adult). Those credentials will be possible to be issued in the form of Verifiable Credentials (World Wide Web Consortium, International Civil Aviation Organization, or mobile driving license), with the objective to be readable and verifiable against the issuer by a third party. Credentials may have a limited lifetime or not and could be limited to usage by specific partners. Identity Building Block would allow a user to suspend (temporarily) or revoke (definitely) a Credential which then would become unusable with the Usage APIs. A User could obtain physical forms of Credentials printed on a physical support (card, paper, etc.), the information printed on the credential would be shared as a verifiable Credential to ensure backward trustability of the information, and the Physical Credential layout could be generated by the Identity Building Block in a PDF format for a further printing by a credential printing partner. An API would be available to search, authenticate and manage the credentials of a specific User.

4.4 Subscription Management

Partners will have the possibility to register for Identity-related events for being notified when they will happen. Identity-related events being the creation of identity (new User on-boarded, could be birth registered or a new user registered), update in one or several of the identity personal attributes, or event happening to that identity (i.e. death, disappearance) Subject to preliminary authorization, Partners could register to type of events applicable to all Users, or to specific Users or using filters on some attributes (i.e. age reaching 18) When an event will occur the Identity Building Block will send a notification to the registered partners, then the partner will be in the capacity to request Identity Building Block event-related information.

4.5 Administration Management

GovStack administrators will have functionalities to configure the Identity Building Block from a central place.

5.1 Requirements

The Cross-cutting requirements described in this section are an extension of the cross-cutting requirements defined in the Security Requirements.

5.1.1 Enrollment Services (REQUIRED)

Enrollment services for a digital ID in the form of a certificate using the physical credentials of the enrollee (a human citizen subject) and the process of the Identity Building Block (see the functional requirements for Identity in the Identity Building Block Definition). A feature for invalidating, locking or disenrollment/revocation of the digital ID shall also be provided as a response measure to both human citizen subjects leaving the system and responding to security breaches encountered. Digital certificate enrollment must be provided by the solution but is not required for every human citizen subject (see below). Notes:

• It is anticipated that the Identity Building Block will call this feature either directly via API or indirectly via the IAM features of the Security Building Block for users electing to use an electronic ID consisting of certificates as a part of the account provisioning process. The digital ID will then be stored with the physical ID records in the identity Building Block and sent to the new user via secure means (probably installed on their device).

• Simple numerical digital IDs will also be supported for human citizen subjects as an option where users are unable to leverage certificates-based digital IDs. The requirements governing this are to be stipulated by the Identity Building Block (see the Identity Building Block Definition).

• Third-party organizations and internal subjects (both human and non-human) must be issued valid signed digital certificates in order to establish and maintain secure inter-organization and internal communications.

5.1.2 Multi-Factor Authentication (REQUIRED)

The overall solution suite shall also be able to implement multi-factor authentication using simple numeric digital IDs for human citizen subjects such as their tax file or social security number of the user.

A selection of various alternatives for digital ID is required in order to cater for more or less digitally-savvy citizens. Various token types are also required to be optimally supported such as HOTP and TOTP tokens, SMS, email, push notifications, SSH keys, X.509 certificates, Yubikeys, Nitrokeys, U2F and WebAuthn. Vendors of solutions SHOULD articulate the benefits of what they propose in their solution.

Note that multi-factor authentication must be able to be implemented for both external and internal subjects (people, systems, components etc.) but is not necessarily required for internal non-human subjects (such as building block components) as they communicate via the information mediator Building Block (see the Information Mediation Building Block Definition).

5.1.3 Numerical Digital ID Attribute (REQUIRED)

Where human citizen subjects adopt the use of a simple numerical digital ID, the multi-factor authentication process MUST include a time-sensitive credential (AKA OTP or one-time PIN).

5.2 Consent Management

Whilst ID and Verification as defined and understood in this Building Block should be supported by local or supranational laws and regulations (like internal security or global AML rules), translation of the appropriate use, in reality, is complex and hardly enforceable.

Hence, we recommend that any solution should have a defined consent management mechansîsm by design.

The specifications for such mechanisms but should follow the following requirements:

1. Consent should be created in the context of the user and should be available to the user.

2. Take consideration of consent receipts (Kantara Initiative Releases the First Open, Global Consent Receipt Specification)

3. Following the logic that a user is asked to give consent for a particular activity/data share. (Some other system linking the user with the activity). Assuming that the overall system sends the consent request to the appropriate user then their response (I give consent) is stored and managed in the consent management Building Block or any other responsible party). If the user is a mother who does not yet have a registered identity they can still be the 'person' who is asked for their consent.

4. Address ownership of register and access questions: presumably, the consent register is only held by the data controller who is acting on the basis of the consent.

5. Purpose limitation of the consent.

6. A request-response approach or a link to a transaction ID and parties and dates would also help.

7. An assisted model would also be required, where 3rd party agencies can come in to collect consent from the user.

8. Apart from technical requirements, it is helpful to differentiate between consent as an ethical process versus consent as a legal basis for processing personal data (certainly under GDPR).

Identity Building Block implement a Consent collection mechanism in order to be aligned with the open-standard openID Connect. This consent collection ensure an authentic approval of an individual before sharing its PII (Personal Identifiable Information), as the the individual is authenticated as a first step.

In future releases, after a proper study being done, the Identity Building Block would integrate with the Consent Building Block to leverage the storing and verification features, together with the standardization brought by Consent Building Block.

5.3 Trust Framework

Trust Frameworks can be considered a mechanism to enable the trusted exchange of information between sovereign partners. The Trust Framework is a much-discussed concept and this report recommends including the specifications in the second iteration as a sub-Building Block whereby additional experts should be included.

5.4 Standards

The following standards are applicable to data structures in the Identity Building Block:

The purpose of this document is to be the reference specification of the Identity Building Block, describing its internal architecture, its external interfaces, and how it is expected to interact with other Building Blocks.

The Identity Block creates, manages, and uses a digital foundational identity (functional identity is not in the scope of this document). As a part of the overall identity system, it can be interfaced with other Building Blocks in order to realize the complete set of requirements necessary for the delivering identification services and managing lifecycle of Foundational Identities.

The Identity Building Block is composed of a set of interoperable sub-components/modules dedicated to the management of the foundational identity offering different services for ensuring a trusted foundational identity for enabling related use cases.

The guidance from this Building Block takes note of recognized approaches across the globe which in detail and deployment can vary greatly. These approaches will consider central, federated, and distributed (decentralized) models, the Identity Building block will remain approach agnostic and flexible for being capable to adapt to the different policies and existing countries that can exists in adopting countries. This version of the document is focused on centralized approach already taking into account integration with Functional Identity, therefore covering the federated approach. Fully distributed approach (decentralized identity issuance or self-issuance) is not yet covered yet .

2.1 Centralized, Federated, Distributed Identities

Identity systems can follow different approaches between centralized, federated or distributed identities.

• With the Centralized Identity approach, the identity is managed in a unique central place and offered as a service to the systems around. Foundational Identity follows a Centralized approach.

• With the Federated Identity approach, the identities are multiple and managed in different systems which are all trusted to ensure identity verification services. Federated systems may be functional systems which could include different characteristics of persons. This approach helps to leverage existing identity assets. In a federated identity approach the IDV BB could:

  • act as an Identity Provider and expose authentication services via federation (see Open ID Connect Standards).

  • offer services for identity proofing to external Identity Providers via the Identity Verification services standardized interfaces.

• With the Distributed Identity approach (also named decentralized or self-sovereign identity), the identity is owned and managed by the end person in a form of credentials (physical or digital) for which the owner is in full or as-needed control of its usage. This model if compared to centralized to federated presents lots of benefits in terms of privacy protection.

In each of these approaches trust in the identity and verification needs to be established. The centralized and federated approaches have organizations that provide trust through their ID proofing process but trust in the organizations themselves needs to be evaluated. Federated is an early form of decentralization and establishes a web of trust. If the same is extended to include relying parties and other service providers who participate in identity proofing, a distributed model is being created.

The concept of federated and distributed identity approaches are not covered in this specification and will be explained in more detail in future iterations of the ID specification.

Overall, we advocates that regardless which approach is chosen, the data should always belong to the individual, but the level of control offered to them might vary based on features offered as well as the underlying needs. For example a population registry cannot "forget" a person and might not allow for that.

There is no one-fits-all solution and often a combination of those approaches enables most benefits.

2.2 Identity Building Block Overview

The diagram below shows the high level view of the Identity Building Block.

The Identity Building Block offers a set of external services to the other building blocks

• Federation services are there to federate and harmonize multiple identities, which is creating

  a link in between various digital identities that an individual may have.

• Enrollment Services allow to on-board new identities for individuals, which means collecting its personal identity data, evidence of them, biometrics.

• ID/Credential Management Services permit to issue and manage the life cycle of Identity credentials, those services will allow to issue identity documents, to manage their renewal, declare them as stolen.

• Identity Verification Services allow a service provider to verify an identity or some of its attributes, for example checking a person declared identity or verifying its age.

• Notification Services will allow a third party to subscribe to events occurring on identity and to receive notifications, useful to inform external functional building block when a person was born or has passed off so that the external system can take required actions.

Note: these services are detailed in Section 4 (Key Digital Functionalities)

The Identity Building Block also includes internal sub-building blocks/ modules, notably:

• Identity Registry is a system storing and managing the identities. It contains and manages all the data that might need to be collected (according to local laws and regulations) including demographic (ie name), biographics (ie age), portrait, known identifiers, known documents and can offer consultation or management services on them. As the system must be auditable, it must keep track of identity changes and keep evidence leading to those changes. Privacy and Data protection rules force us to carefully manage storage and access to data, by respecting specific data protection design rules (minimization, isolation, anonymization, ..) Generally speaking, countries apply privacy and data protection laws similar to European GDPR which impose to minimize data stored including in time and always performs informed consent of the individuals of their end usages. The registry should allow for portability of data from one solution to another. For this the registry should support open data formats as well as standards based data formats. This applies to biometric and biographic data. The module should also offer APIs for such data portability.

• Identifier Management module, managing identifiers assigned to identities. In case a Unique Identity Number (UIN) is used and is acting as ‘primary key’ of identity, it is recommended that such number does not contain any personally identifiable information and hence can be used and shared publicly. The UIN should also be non-revocable. There may also be a set of tokens or aliases identifiers to use the identity and, where required, to link to data in functional systems.

• Orchestrator (optional but strongly recommended) is often embedded in the Identity system in order to run the control steps and actions required to build an identity. It’s recommended to use an internal workflow for that, which may lead to triggering an external workflow if, for example, required to launch additional actions after identity creation.

• Identity Provider can be part of Identity Building Block and provide reference identities for identity verification, it can be also optional when in a decentralized (or distributed) identity model.

• UIN Generator, allows to generate Unique Identity Numbers which are unique in the system. UIN Generator will follow predefined business rules for that generation and will make sure that a new generated number has never been already issued.

2.3 Identity System Components

The graphic below presents the overall view of the Identity System with its main components.

2.3.1 Specificity of the Identity Registration System

Identity Registration system must be understood as different from a classical application registration system, as it establishes a person’s foundational ID which is likely to act as a basis for their digital twin (digital twin is the equivalent of a physical real person in the digital realm) for all digital interactions and therefore will be of high importance for him/her as well as being highly attractive for hackers, demanding the highest level of security.

It might require secured biometrics and document capture capacities in order to limit the chance of fraud, although the use of biometrics is not recommended given the potential privacy implications. It can be compared at the entrance door of a secured site where security is particularly reinforced and the process takes necessary time to check all information, if compared to internal access control which can be lighter and based on short interactions. The Identity Registration system can be a single client Application, or web based application or even a client server application, it could be also online or offline.

If an identity registration client is confirmed to be an external building block it will most probably be more related to the Registration Building block. It must have its own APIs and own rules, tools and capture technologies compatible with the Identity Building Block's OpenAPIs.

The client has to deal with secure interfacing; where biometrics is being used with biometrics capture devices, and performing some operations on the biometrics such as quality checks, liveness checks etc. These interfaces will be part of the biometric services. The data capture formats for biometrics will also have to be based on open standards to ensure compatibility and portability.

2.4 Integration with an Existing Identity System

It happens that some countries have an existing identity system they choose to reuse, like for example a National Population Register, a Civil Register or ID Document system. In that case the existing system will need to be equipped with the IDV BB Services Facade which will make its integration transparent toward the remainder of the GovStack.

The results presented here benefit from publicly available sources that are referenced here. This report is recommending the use of open standards throughout any implementation. Here below are some of those standards which have been reviewed to prepare that specification:

For this purpose, the team is suggesting the following already available and recognized open standard providers:

• Federation protocol: Open ID Connect.

• Image format for biometric data: ISO-19794.

• Verifiable credentials (to be covered in the next iteration of this document in more detail): World Wide Web Consortium (W3C).

• ISO/IEC 24760

• Modular Open Source Identity Platform (MOSIP), which also includes information about their APIs MOSIP.

• Open Standard Identity APIs for interoperability within Identity System: OSIA.

10.1 Key Decision Log

A historical log of key decisions regarding this Building Block.

10.2 Future Considerations

A list of topics that may be relevant to future versions of this Building Block.

Internal functional components

A common set of unique internal functional components are required to orchestrate the services of the Scheduler Building Block as shown below. The REST API's interfaces route service requests to/from external Building Blocks and appropriate internal blocks in appropriate formats. A brief description of the generic functionality of each of these components has been given below from a minimum viable product perspective. Detailed design and feature lists of these blocks can be customized by developers to optimally match specific target implementation needs.

6.1 Identity Usage

• Identity Building Block must offer an API to verify Identities following a Gov Stack recommended Open Standard API. (REQUIRED)

• Identity Building Block must offer an API to Verify Identity of an individual based on one of its known identifiers. (REQUIRED)

• Identity Building Block must offer an API to retrieve personal attributes of an individual from one of its identifiers. To be noted that this service will be subject to preliminary access granted by the system and by the individual (informed consent). Authorized access control should be part of API as opposed to external configuration alone. This ensures that relying parties are verified by the API before sharing sensitive data. (REQUIRED)

• Identity Building Block must offer an API to identify an unknown individual, which means retrieve an identity identifier from a set of personal attributes sent. This service is normally to be used for security/law enforcement purposes and must be limited to registries of wanted people. For privacy and security reasons, this feature should only be considered where clear and accountable security/law enforcement rules are in place. (REQUIRED)

• Identity Building Block must offer an API to verify one characteristic of an individual without having to disclose actually the recorded related attributes. The typical request response is Yes or No (sample use case: age verification, is a person older than 18 > Yes to No). (REQUIRED)

• Identity Building Block must offer Identity Verification services based on modalities listed below following a GovStack recommended Open Standard API. (REQUIRED)

6.1.1 Modalities

Identity verification can be performed in several ways and based on several modalities depending on various criteria.

For example, Identity verification will be performed according to the:

• Context of identity verification: online, face-to-face by a third party, self-identity verification, in the absence of infrastructure and technologies.

• Capacities given to the individual: having an ID Card, a person Identifier, a password or PIN code, using its biometrics, mobile subscription, or smartphone.

• Status of the individual: can they read? Do they have usable fingerprints? Are they old enough to have an ID Card?

• Level of trust required: according to the sensitivity of the operations, level of assurance required, policies established by the state or by the service provider, multiple factor identity verification.

• Business constraints: does the use case require to be very fast, touchless, seamless, physical, or digital?

• Local laws and regulations: the identity verification could differ according to local regulations and laws which may indicate specific ways to perform identity verification.

Below shown table will list the different modalities that can be used to perform an identity verification, the Identity Building Block may use any of them including a combination of several of them to verify a person's identity.

Through this list of capabilities we can see there are numerous but limited options for Identity Verification that can be combined or not, this list allows us to normalize them all into the following inputs for an identity verification:

1. Identifier: identifier referring to a digitally retrievable identity that can give access to an individual's attributes for verification. It is noted that several kinds of identifiers could be used to refer to the same person, which is particularly important to preserve privacy (see glossary).

2. Set of attributes: attributes provided by the individual or retrieved on/within its Identity credential for purpose of a matching versus a reference (online or ID credential), those attributes can be biographic data, biometrics data, or scan of identity evidence.

3. Authentication token: A previous identity verification token can be used for identity verification, this token would allow the current service provider to verify against the authenticating system the genuineness of the token.

6.2 Identity Management

• Identity Building Block must offer an API to Enroll persons following a GovStack recommended Open Standard API. (REQUIRED)

• Identity Building Block must offer capacity to perform an enrollment in one step. (REQUIRED)

• Identity Building Block must offer capacity to perform an enrollment in multiple steps (i.e. demographic data collection, biometric data collections, supporting documents collections, etc.). (REQUIRED)

• Identity Building Block must offer capacity to search, retrieve and update and enrollment made (if it has not been committed yet). (REQUIRED)

• Identity Building Block must allow to control integrity and origin of an enrollment request by implementing enrollment meta-data about the context and actors of the enrollment, such as signature of data to ensure integrity. To ensure the integrity of the enrollment process, the Building Block must be able to implement technical controls so that only approved enrollment services can engage with the enrollment service. Cryptographic trust should be implemented.(REQUIRED)

• Identity Building Block must support receiving encrypted data to ensure privacy protection and prevent data theft. (REQUIRED)

• Identity Building Block must offer capacity to perform an enrollment offline which means not expecting interactions between registration client and server during the enrollment process, and data being uploaded as a whole packet. (REQUIRED)

• Identity Building Block must support porting existing demographic, biometric, and other enrollment data from external servers during enrollment process. (REQUIRED)

• Identity Building Block must keep track of the enrollment request identifiers within its internal management in order to facilitate traceability and troubleshooting. (REQUIRED)

• Identity Building Block must generate a Unique Identifier for Identity created. This number must be kept secret within the Identity Building Block. (REQUIRED)

• Identity Building Block must be capable to generate Virtual Identifier for referring to a User. The Virtual Identifier will be linked to the User's Unique Identifier. (REQUIRED)

• Identity Building Block must offer an API to revoke a Virtual Identifier. In that case, the Alias won't be usable anymore for any Identity Building Block services. (REQUIRED)

• Identity Building Block must be capable to attach an Alias Identifier to Unique Identifier for referring to a User. The alias will be an existing form of trusted identification of the User in another system. It could be for example an existing identity document number, an email address, a phone, etc. (REQUIRED)

• Identity Building Block must offer an API to revoke the link to an Alias. In that case, the Alias won't be usable anymore for any Identity Building Block services. (REQUIRED)

• Identity Building Block must offer APIs to update attributes of identities and to attach legal evidence of that identity change approval (often delivered by justice). (REQUIRED)

6.3 Credential Management

• Identity Building Block must offer an API to request issuance, get status and manage Identity Credentials, following a GovStack recommended Open Standard API. (REQUIRED)

• Identity Building Block must offer an API to manage the full life cycle of credentials related to an identity in an issuing system. The related credential must keep a strong and verifiable link with the individual identity and with the issuer. (REQUIRED)

• Identity Building Block API must manage Digital Credentials. (REQUIRED)

• Identity Building Block API must manage Physical Credentials. (REQUIRED)

• Identity Building Block must offer an API allowing to request an identity credential issuance to a third-party credential management system. The information sent will have to be verifiable towards their issuer for auditability purposes, so they will have to be packed into Verifiable Credential format.

• Identity Building Block must offer APIs to either push data for credential issuance in an issuance request or to be requested by the issuing system. (REQUIRED)

• Identity Building Block must offer an API allowing to issue a similar credential to the one already issued before based on the credential ID number. (REQUIRED)

• Identity Building Block must offer an API allowing to revoke an issued ID credential. This will be used, for example, when a document is damaged, stolen or definitely lost. (REQUIRED)

• Identity Building Block must offer an API allowing to temporarily suspend and then un-suspend an issued ID credential. This will be used to disable an ID credential which has been lost, its holder suspending the time to search for it. After retrieval, the document should be unsuspended and usable again. If not retrieved after some time, the document should be revoked. (REQUIRED)

• Identity Building Block must offer an API allowing to check the suspension status of a document. (REQUIRED)

• Identity Building Block must offer an API to request the status of ID credentials. Status being related to their production, their delivery or their activation status. (REQUIRED)

• Identity Building Block must offer an API to search for ID credentials using some of its attributes. The output must be restricted to being a document number which can facilitate an access request only. No information can be shared directly. (REQUIRED)

• Identity Building Block must offer an API to retrieve a new copy of an ID credential already issued in case the current document has expired. The copy may be received electronically if is digital or delivered physically in case of a physical ID document. (REQUIRED)

• Identity Building Block must offer an API to download a newly generated digital ID credential. (REQUIRED)

• Identity Building Block must offer an API to share with a 3rd party a Digital ID Credential. (REQUIRED)

6.4 Subscription Management

• Identity Building Block must offer an API for Subscribers to register for identity change events.(REQUIRED)

• Identity Building Block must offer an API for Subscribers to register to Creation, Update and Disabling (person dead or considered as disappeared) events. (REQUIRED)

• Identity Building Block must offer an API for Subscribers to collect event details after being notified of them. (REQUIRED)

6.5 Administration Management

• Identity Building Block must prevent any unauthorized system or user to get access to data. (REQUIRED)

• Identity Building Block must offer identity verification services only to a registered system or users. (REQUIRED)

• Identity Building Block must offer the capacity to grant access to specific verification services for specific or all individuals that are data subjects and hence owners of that data. (REQUIRED)

• Identity Building Block must respect principles of data security by design in order to maximize protection against hackers: data encryption, data isolation, data separation, data anonymization, data minimization. (REQUIRED)

• Identity Building Block must implement security best practices in order to ensure the Identities it manages can be trusted. (REQUIRED)

• Identity Building Block must implement a history of change for any identity must be retrievable and auditable by authorized users to investigate suspicious cases. (REQUIRED)

• Identity Building Block must offer identity verification services only with preliminary informed consent on personal data usage of the concerned individual. (REQUIRED)

• Identity Building Block must not disclose any personal unnecessary information as part of its services API, and when possible prefer Yes/No answer rather than sharing attributes. All Sensitive Personal Information/Personally Identifiable Information must not be written to logs/reporting databases. (REQUIRED)

The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.

In common for all services of the Identity Building Block, the API expects the calling Partner has been already authenticated and authorized to access the service. For detailed specifications of APIs with input/output formats please refer to API specifications defined in YAML in the corresponding GitHub repository.

The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.

The tests for the Identity Building Block can be found in this GitHub repository.

API standards

• The microservice interfaces are defined as per OPENAPI Ver3.0 standards.

• For implementation purposes, it is suggested to refer TMF630_REST_API_Design_Guidelines.

8.1 Identity Usage

The Identity usage APIs are a set of OpenAPI specifications exposed by the Identity Building Block to other building blocks and applications for user verification.

The Identity usage APIs are based on the following principles:

• Verification APIs are inspired from OpenID Connect protocol which simplifies integrations using pre-existing libraries

• Only secure options in OpenID connect should be supported to ensure the user data is handled securely

• All biometric capture for user verification should be done using Secure Biometrics Interface standards

Service Group: Client Management

For Identity Building Block implementations that support mobile wallet integration, the following API spec should also be implemented.

Detailed API schemas written in YAML that define REST API endpoints for each of the services mentioned above are available on GitHub located at the Identity-Provider YAML.

The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here.

8.2 Identity Management

The Enrollment APIs are a set of OpenAPI specifications exposed by the Identity Building Block ‘Enrollment Server’ service to any enrollment client.

The Enrollment APIs are based on the following principles:

• When enrollment is done in one step, the CreateEnrollment can contain all the data and an additional flag (finalize) to indicate all data was collected.

• During the process, the enrollment structure can be updated. Only the data that changed need to be transferred. Data not included is left unchanged on the server. In the following example, the biographic data is not changed.

• Images can be passed by value or reference.

• Existing standards are used whenever possible, for instance, the preferred image format for biometric data is ISO-19794. The underlying data should be of open mime types that offer good compression without loss of data (for example JPEG2000 for images).

8.3 Credential Management

This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Identity Building Block Specification.

8.4 Subscription Management

This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Identity Building Block Specification.

8.5 Administration Management

This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Identity Building Block Specification.

If GovStack will offer global workflow management for cross-building block use cases, Identity and Verification Building Block will have its internal workflows for its own internal business flows execution.

Non-exhaustive list of examples:

• For onboarding a new individual.

• For managing identity changes after an event on a person's identity (name change, death, etc.).

• For life cycle management of an individual's identity evidence (i.e. ID Cards).

• For management of access rights to services on an individual's data.

Those workflows will be described in a later version.

9.1 Identity Verification Workflow

The below workflow details the steps involved in the relying party application enabling the end user to log in using their National ID. Once the login process is completed, Identity Building Block also allows the relying party to get verified user claims based on explicit permission from the end user.

9.1.1 Verification with user claims

The steps are:

• The relying party wants to authenticate the user to the Identity Building Block.

• The relying party redirects the user to the Identity Building Block UI.

• The user will authenticate on the Identity Build block.

• The Identity Build Block will ask the user permission to share his/her personal data.

• The User selected the attributes he/she accepts to share.

• A code is generated and returned by the Identity Building Block to the relying party.

• The relying party uses the code and receives an ID token and an access token.

• The relying party then uses the access token to receive the user information.

• The user can pursue its application within the relying party UI.

9.1.2 Verification without user claims

If the relying party wants to verify the identity of the end user without user information, then a lean workflow can be adopted. The steps of lean flow are similar to the workflow steps in previous section. However, during /authorize API call, the scope is set to "openid". This informs the IDBB UI that no user claims will be accessed and thus IDBB UI doesn't show any consent page and these steps are skipped in the workflow.

9.2 Identity Management Workflow

The enrollment process differs from country to country and the enrollment data collection can be done in-person, or ported from existing servers. Here sample workflows are shown.

9.2.1 Enrollment Workflow (Fresh Enrollment)

These are the sample steps for fresh enrollment where the enrollment data is collected afresh:

1. User goes to the Enrollment office.

2. The Enrollment Client collects user demographic details and supporting documents and calls the createPacket API of GovStack Packet Store.

3. Enrollment Client collects user bio-metric details and calls createPacket API of GovStack Packet Store.

4. Once all the enrollment data is available at the GovStack Packet Store, it triggers the enrollment process in GovStack Packet Processor.

5. GovStack Packet Processor processes the data and generates Unique Identity for the user.

6. The user is notified of successful enrollment and the receives the Unique Identity by mail.

Enrollment Workflow (Enrollment with existing database)

These are the steps for enrollment using existing data, in which the demographic details are collected from an existing database and biometric data is collected afresh.

1. User goes to the Enrollment office.

2. Enrollment Client retrieves the user demographic details and supporting documents from an existing database and calls createPacket API of GovStack Packet Store.

3. Enrollment Client collects user biometric details afresh and calls createPacket API of GovStack Packet Store.

4. Once all the enrollment data is available at the GovStack Packet Store, it triggers the enrollment process in GovStack Packet Processor.

5. GovStack Packet Processor processes the data and generates Unique Identity for the user.

6. The user is notified of successful enrollment and the receives the Unique Identity by mail.

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:

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

• 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_verified - True if the End-user's e-mail address has been verified; otherwise false.

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

• 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:

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

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.

7.2.4 Access Token

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.

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:

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

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

7.3.2 Enrollment Response

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

Fields: