First developed by:
Jaume Dubois (ID30), Ramesh Narayanan (MOSIP), Sasikumar Ganesan (MOSIP), Vishwanath V (MOSIP), Dr. P. S. Ramkumar (ITU), Jane Rose (Technoforte), Smita Selot
Authors to this version:
Mikael Linden (Gofore) and David Higgins (Brook IT Consulting), and Smita Selot
Contributors:
Charity Chirowamhangu, Antony Muriithi, Daniel Abadie, Norbert Nahayo, Rounak Nayak, Eric Ramirez, and Mary Metias
Reviewers:
Yuliia Kravchenko, Smita Selot
Editor:
Ali González-García
Identity BB Cover
ID-Related BB Common Terminology
These terms are defined as being common across all the ID-Related Building Blocks (Identity, Consent, E-Signature, and Wallet)
Consent Building Block (CBB)
The Consent Building Block enables services for individuals to approve the use of their Personal Data by defining the principles, functions, and architecture of an information system. For organisations that process Personal Data, it provides the ability to know the individual's will and legitimately process such Personal Data. The Consent Building Block is a process-oriented GovStack Building Block facilitating auditable bilateral agreements within a multi-agent environment that integrates with most other Building Blocks.
Credential
A set of data presented as evidence of a claimed identity and/or entitlements. ()
It may include an identifier to uniquely identify the credential, as well as metadata that describes properties of the credential itself such as the issuer, the expiry time, a representative image, etc.
See also related terminology for and .
Digital Credentials
A Digital Credential (also known as a verifiable credential) is a digitally-issued and verifiable form of a .
See also related terminology for and .
e-Signature Building Block (eSBB)
eSignature Building Block provides the necessary functionalities to bring handwritten signatures to the digital world. Handwritten signatures have served as a way to agree/witness a given document, yet, in today's digital world most documents are in digital form. The digital form varies between structured (XML, JSON) and unstructured documents (PDF, Word, Image, CSV, Spreadsheet). eSignatures can be added to digital documents similar to handwritten signatures achieving the same functionality.
Identity Building Block (IDBB)
Identity Building Block as specified in current documentation.
In charge to create, manage life cycle, audit mechanisms, and verify identities.
Legal Entity
is an organisation (public or private) that has the rights and obligations to define standards for Personal Data processing. E.g. a public health authority
PII (Personally Identifiable Information)
PII refers to any information:
a) that identifies or can be used to identify, contact or locate the person to whom such information pertains;
b) from which identification or contact information of an individual person can be derived; or
c) that is or can be linked to a natural person directly or indirectly.
()
Trust
The confidence of one party or entity that another party or entity will behave in a well-defined way that does not violate agreed-upon rules, policies or legal clauses of the identity management system. ()
Verifiable Credentials (VCs)
A Verifiable Credential (also known as a digital credential) is a digitally-issued and verifiable form of a .
See also related terminology for and .
Wallet Building Block (WBB)
Wallet as a term can mean many things depending on your background and context. However with GovStack we have chosen to use Wallet in its widest context, as a Container with Content.
Therefore the total scope and focus of the Wallet Building Block (WBB) is to provide specifications which support multiple forms of Containers and Contents, we have chosen this abstraction to ensure that the Building Block remains inclusive of different formats of Wallets.
Release Notes
Version 2
v2.0
8 Service APIs
This section provides a reference for APIs that should be implemented by this Building Block.
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 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 .
4 Key Digital Functionalities
Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform.
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 Building 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 Identity Building Block must enable usage from the following actors:
5 Cross-Cutting Requirements
This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.
5.1 Requirements
The Cross-cutting requirements described in this section are an extension of the cross-cutting requirements defined in the .
"BB_Admin" who manages this Building Block to run efficiently in a hosted environment;
"Partners" who are registered trusted partners and can obtain access to services after authorization;
"Users" who will manage their own identity information, credentials, preferences and, when appropriate, Partner's access to this information;
"Subscribers" who can subscribe to notifications of changes in the identity information.
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.1 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.1.1 Enrollment services
Enrollment services exposes API to on-board new and update existing 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)
Once a new identity has been registered a Unique Identity Number (UIN) will be generated for further representing the User in the GovStack. For privacy purposes, this UIN will be kept secret inside the Identity Building Block, and tokens (randomly generated identifiers) or aliases (existing identifiers) will be linked to it and shared with the User for further involvement in the Identity Verification services or for the Credential management.
4.1.2 Identity Verification
Registered and Authorized Partners have access to Identity Building Block Identity verification APIs to request Authentication of Users. If successful, they can collect personal information (e.g. User's name, User is older than 18 years old) after a User informed consent (if applicable) is given. For a specific Partner and a specific User, the Identity Building Block will produce a unique and repeatable Pairwise Pseudonymous Identifier (PPID, a.k.a. PSUT). This service can be used in other Building Blocks, in public services, but also in private services, even cross-countries.
Section 8 defines an OpenID Connect based API for Identity Verification.
4.1.3 Query Services
Query Services expose an API that trusted and separately authorized partners can use for making queries on identity data in the Identity Building Block.
4.1.4 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.
A User could obtain physical forms of Credentials printed on a physical support (card, paper, etc.). 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.
Issuing Verifiable Credentials is covered in the Wallet Building Block.
4.1.5 Upstream Federation Services
Upstream Federation Services expose an API to trusted partners allowing Users to federate (i.e. map) their identities in external identity providers to their identity in the Identity Building Block. Indeed, individuals may already have an existing form of digital identity (such as, a functional identity) they need to keep using and would like to associate with their foundational identity. In that case the Upstream Federation Services will be able to attach those forms of identity based on their identifier to their foundational identity managed by Identity Building Block, also to allow delegation to them of individual’s authentication.
4.1.6 Notifications Services
Notification Services expose APIs which allow triggering of external processes according to events happening on the identity data managed by the Identity Building Block (i.e. new User on-boarded, 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).
Partners will have the possibility to subscribe for Identity-related events for being notified when they will happen. Subject to preliminary authorization, Partners could subscribe 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.2 Other services
4.2.1 Service for users to manage their identity
4.2.1.1 User Interfaces and APIs will allow a user to have a management of their personal data for CRUD requests (Create, Read, Update, Delete) according to GDPR regulation and to the Adopting Country laws, policies and practices.
4.2.1.2 A User will have the possibility to generate a temporary and revocable Virtual ID to preserve its privacy for temporary use.
4.2.1.3 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 Identity Verification services.
4.2.2 Administration Management
GovStack administrators will have functionalities to configure the Identity Building Block from a central place.
4.2.3 Policy Management
This would cover what attributes would be shared with different partners. But this will be expanded in future releases and could be considered as a specific type of administration management interface.
Enrollment services for a digital identity 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 Specification). A feature for invalidating, locking or disenrollment/revocation of the digital identity shall also be provided as a response measure to both human citizen subjects leaving the system and responding to security breaches encountered. Digital certificate or verifiable credential 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 eID consisting of certificates as a part of the account provisioning process. The digital identity 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 eIDs will also be supported for human citizen subjects as an option where users are unable to leverage certificates-based eIDs. 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 eIDs for human citizen subjects such as their tax file or social security number of the user.
A selection of various alternatives for eID is required in order to cater for varying needs of citizens. Various eID 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 Mediator Building Block Specification).
5.1.3 Use Multi-Factor Authentication with Numerical eID (REQUIRED)
Where human citizen subjects adopt the use of a simple numerical eID, the multi-factor authentication process MUST include a time-sensitive credential (AKA OTP or one-time PIN).
5.2 Consent Management
Depending on the jurisdiction, processing (such as, collecting or sharing) PII (Personally identifiable information) data may require User consent. The local laws may also require the User is informed on processing their PII.
The Identity Building Block may work with the Consent Building Block to implement a consent collection mechanism. In this case the consent collection must ensure an authentic approval of an individual using the Identity Building Block before processing their PII as it is essential that the individual is authenticated as a first step.
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 will be a consideration of the ID related working group across all GovStack ID related BBs in a future release.
This release of the Wallet Building Block was developed between September and December, 2025 by the Cross-Functional ID Infrastructure Working Group, a super-group of all the key Identity and Trust-related Building Blocks in GovStack (e-signature, identity, Wallet, Consent).
Release 2.0 of Identity is the result of a review of all 4 specifications to ensure their are aligned and consistent to a single Identity Universe. As a result, a shared ID Terminology reference document was created and some terms from this Building Blocked were moved there. It also incorporates previously un-released work on implementing Credential Management APIs.
The biggest change in this release comes from the re-structuring of Key Digital Functionalities and its respective Functional Requirements on section 6. This version addresses that and adds requirements for Upstream Federation. More detail can be found on the change log. Details on this decision were captured on the Working Group Decision Record ID-WGDR-2026-01.
2. Change log
Section 1 Version History
Alignment of Version Numbers to semantic versioning
Inclusion of Release Notes
Section 2 Description
Updates for Consistency use of IDVBB to IDBB
Links to Wallet BB added as now published
Removal of future capability from Federated and Distributed Identities as in current spec
Removal of terms in common terminology from main terminology
Incorporation of definitions for each ID related BB into common terminology
Removal of terms no longer used in text
Update of definitions to be headline text and supporting information to streamline readability
Move from Table to GovSpecs 2.0 Heading format for AI readability
Section 4 Key Digital Functionalities
The major change this version introduces is the re-structuring of how Key Digital Functionalities. The following is a comparison table between the functionalities of the two versions:
Version 1 (1.0 through 23Q4.1)
Version 2.0
4.1 Core services
4.1.1 Identity Usage
4.1.2 Enrollment services
4.1.3 Credential Management Services
4.1 Core Services
4.1.1 Enrollment services
4.1.2 Identity verification
4.1.3 Query Services
Other changes are:
Alignment of services to a common order mapped to section 2
Restructure into Core Services and Other Services
Grammatical, reference and typo changes
Section 5 Cross Cutting Requirements
Grammatical, reference and typo changes
Consent Section re-written to refer to Consent BB
Trust Framework section updated to reflect thoughts from WG
Consistency in Requirements of GovSpec 2.0 (Required and Recommended) naming
Section 6 Functional Requirements
New requirements for new 6.3. Query services and 6.5 Upstream Federation Services were added
A requirement about the integrity of enrollment is now disaggregated between adding meta-data and cryptographic signatures.
A thorough break-down of how the requirements were re-organized can be found on Appendix 2 of ID-WGDR-2026-1
Grammatical, reference and typo changes
Alignment to Service order in other sections
Move of Modalities out to Section 10
Consistency in Requirements of GovSpec 2.0 (Required and Recommended) naming
Section 7 Data Structures
Grammatical, reference and typo changes
Section 8 Service APIs
Addition of Credential Management APIs
Grammatical, reference and typo changes
Consistency with naming of external services
Section 9 Internal Workflows
Grammatical, reference and typo changes
Section 10 Other Resources
Addition of sub page "Consideration of Authentication Methods" this includes content previously in section 4 on Modalities
Section 8 Service APIs
Inclusion of Service Management APIs
Version 1
v1.1.1 (23Q4.1)
Released May 2023
Clarity updates
v1.1.0 (23Q4)
Section 2 Description
2.1: "Centralized, Federated, Distributed Identities" - detailed explanation of different identity approaches
2.2: "Identity Building Block Overview" - comprehensive overview with diagrams of services
2.3: "Identity System Components" - detailed component descriptions
2.4: "Integration with an Existing Identity System"
Section 3 Terminology
Additional Terminology:
Digital Identity
Electronic Identity
Foundational vs Functional Identity Systems
Section 4 Key Digital Functionalities
Restructured with
Section 4.2 "Core Services" containing 6 subsections (4.2.1-4.2.6) including a new "Federations Services" section, plus sections 4.2-4.5 for other functionalities
Section 5 Cross Cutting Requirements
Section 5.2 "Consent Management" with 8 detailed requirements,
Section 5.3 "Trust Framework"
Section 5.4 "Standards"
Section 6 Functional Requirements
Includes more detailed requirements for enrollment, specifically mentioning "pre-enrollment and enrollment" as separate steps
Adds note about "demographic data collection, biometric data collections, supporting documents collections, etc."
Section 8 Service APIs
Includes wallet binding API as a draft specification
The Identity Verification 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 by 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
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 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
These Credential Management APIs are a set of OpenAPI specifications exposed by the Identity Building Block to service identity credential requests by credential partners such as printing and QR code partners.
The Credential Management APIs are based on the following principles:
The credential request API is asynchronous for the identity holder i.e., the call to share credentials is responded with an event ID. Then the identity holder later uses the event ID to retrieve the details using the API '/events/{eventId}'.
The '/share-credential' API is used to convey the format of the credential information. The format allows the credential information to be masked/unmasked. The API also conveys the consent of the identity holder.
The API '/download/personalized-card' is used to download the identity card in PDF format.
Systems for Voter ID, Tax ID, Card printing etc. receive internal notifications from IDBB.
Wallet applications will receive the identity credentials as per pre-authorized flow.
The APIs '/block', '/unblock' and '/updateIdentity' can only be called by systems with administrative permissions given by the IDBB.
8.4 Subscription Management
The Subscription Management APIs follow the APIs from the WebSub standard and WebHooks common practice.
8.5 Administration Management
This Services APIs is not yet specified, but it should be the purpose of a future iteration of the Identity Building Block Specification.
The version history table describes the major changes to the specifications between published versions.
Version
Authors
Comment
4.1.4 Identity and Verification Services
4.1.5 Notifications Services
4.1.6 Federations Services
4.2 Identity Management
4.3 Credential Management
4.4 Subscription Management
4.5 Administration Management
4.1.4 Credential Management Services
4.1.5 Upstream Federation Services
4.1.6 Notifications Services
4.2 Other services
4.2.1 Service for users to manage their identity
4.2.2 Administration Management
4.2.3 Policy Management
1.0 RC1(release candidate)
Authors:
Jaume Dubois, Ramesh Narayanan, Sasikumar Ganesan, Vishwanath V, Dr. P. S. Ramkumar, Jane Rose, Valerie Khan, Debora Comparin, Raul Kaidro, Edgar Whitley, Jonathan Marksell, Vyjanthi Desai, Deepti, Yiannis Theodorou
Introduce Usage APIS (Verification & Federation).
1.0.0May 2023
Authors:
Jaume Dubois, Ramesh Narayanan, Sasikumar Ganesan, Vishwanath V, Dr. P. S. Ramkumar, Jane Rose, Valerie Khan, Debora Comparin, Raul Kaidro, Edgar Whitley, Jonathan Marksell, Vyjanthi Desai, Deepti, Yiannis Theodorou
Technical Reviewers:Tony Shannon, Saša Kovačević, Riham Moawad, Riham Fahmi, Aare Laponin, Manish Srivastava, Palab Saha, Surendra Singh Sucharia, Arvind Gupta, Gayatri. P., Shivank Singh Chauhan, Gavin Lyons
Editors:
Wesley Brown, Steve Conrad, Valeria Tafoya
Final edits to align content to specification template for GovStack 1.0 release
1.0.1February 2024
Authors:
Smita Selot, Jaume Dubois, Ramesh Narayanan, Sasikumar Ganesan, Vishwanath V, Dr. P. S. Ramkumar, Jane Rose
Open Enrollment API to handle multiple cases/contexts
1.1.0 (also known as 23Q4)October 2024
Authors:
Jaume Dubois , Ramesh Narayanan , Sasikumar Ganesan , Vishwanath V, Dr. P. S. Ramkumar, Torsten Lodderstedt, Jane Rose, Smita Selot
Updated Description covering Centralized, Federated and Distributed IDs.
Restructure of Key Digital Functionalities.
Inclusion of Wallet Binding API.
Additional detailed workflows.
1.1.1
(also known as 23Q4.1)November 2024
Authors:
Jaume Dubois , Ramesh Narayanan , Sasikumar Ganesan , Vishwanath V, Dr. P. S. Ramkumar, Jane Rose, Smita Selot
Minor updates for clarity
2.0
December 2025
Contributors:
Charity Chirowamhangu, Antony Muriithi, Daniel Abadie, Norbert Nahayo, Rounak Nayak, Eric Ramirez, and Mary Metias
Authors:
Mikael Linden, David Higgins. and Smita SelotReviewers:
Yuliia Kravchenko, Smita Selot.
Editor:
Ali González-García
Incorporation of Credential Management APIs
Updates to Terminology, removal of references to IDVBB to IDBB.
Consistency updates to order and flow between key digital functionalities and requirements.
Updated diagrams to reflect core services.
See for detail.
0.8(draft not published)
Authors:
Valerie Khan, Jaume Dubois, Debora Comparin, Stephanie De Labriolle, Ramesh Narayanan, Sasikumar Ganesan, Vishwanath V, Raul Kaidro, P.S Ramkumar, Dr. Edgar Whitley, Deepti Vikas Dutt, and Jonathan Marskell
Identity Building Block overall scope and requirements. Introduced the overall high level Identity Building Block scope and requirements.
0.9(draft not published)
Authors:
Jaume Dubois, Ramesh Narayanan, Sasikumar Ganesan, Vishwanath V, Dr. P. S. Ramkumar, Jane Rose, Amy Darling
Adding requirements numbers for Identity Building Block.
10 Other Resources
This section links to any external documents that may be relevant, such as standards documents or other descriptions of this Building Block that may be useful.
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:
We recognise there are common terms across all ID related Building Blocks (Identity, E-Signature, Consent, Wallet). We define these here.
In addition the following terms are specific to the ID Building Block.
Attribute
Information bound to an entity that specifies a characteristic of the entity. (ITU-T X.1252)
Authorization
The process or action of authorizing a user to perform an action, for example accessing and using a service. Authorization is not the responsibility of the Identity Building Block
Authentication
The process or action of verifying the identity of a user or process. For the purpose of this project, authentication has been replaced with the term "identity verification" to allow for a clearer definition and for demarcation with other Building Blocks.
Biographic data (or Demographic data)
Set of text attributes representing the identity given at birth. Common attributes: Name, firstname, birthdate, birthplace, parents' biographic data.
Biometric data
Set of physical attributes which can be used to identify a person.
Most common ones are fingerprints, face, and iris.
More can be used like voice, behavioral, veins, etc.
Civil Registry or CRVS (Civil Registry and Vital System)
A civil registry or CRVS (Civil Registry and Vital System) is a system recording life events (birth, death, marriage, divorces, adoptions, name changes, etc.) It is used to keep track of the life events of individuals and to produce statistics for policy making.
Claim
Digital assertion about identity attributes made by an entity about itself or another entity. ()
Examples:
Can be pertaining to identity - I am X
Can be pertaining to entitlement or eligibility - X is allowed to vote
Credential Management
Is a document lifecycle management regardless of its form. An identity credential can appear in both physical (e.g. ID card, passport, driver’s license) and electronic form ();
Includes issuance, maintenance, suspension, termination of suspension, revocation, and expiration;
There should be no difference between physical and electronic documents with the exception of audit trail kept during usage of the electronic document ().
Identity (Digital Identity)
A representation of an entity in the form of one or more attributes that allow the entity or entities to be sufficiently distinguished within a context. ()
Identity is the unique representation of a subject engaged in an online transaction. An identity is always unique in the context of a digital service but does not necessarily need to uniquely identify the subject in all contexts. In other words, accessing a digital service may not mean that the subject’s real-life identity is known.
Identity allows an entity (citizen, business, administration) to be distinguished from any other.
Identifier (Digital Identifier)
Series of digits, characters and symbols used to identify uniquely a subscriber, a user, a network element, a function, a network entity, a service or an application. ()
Digital identity fundamentally requires digital identifiers—strings or tokens that are unique within a given scope (globally or locally within a specific domain, community, directory, application, etc.). Identifiers are the key used by the parties to an identification relationship to agree on the entity being represented. Identifiers may be classified as omnidirectional and unidirectional. Omnidirectional identifiers are intended to be public and easily discoverable, while unidirectional identifiers are intended to be private and used only in the context of a specific identity relationship.
Identifiers may also be classified as resolvable or non-resolvable. Resolvable identifiers, such as a domain name or e-mail address, may be dereferenced into the entity they represent, or some current state data providing relevant attributes of that entity. Non-resolvable identifiers, such as a person's real-world name, or a subject or topic name, can be compared for equivalence but are not otherwise machine-understandable.
Electronic Identifier (eID)
An electronic identity:
is a means for the user to prove electronically that they are who they say they are and thus gain access to services;
is presented in an electronic environment;
can appear in a form of a certificate as a username, email address, or phone number;
Electronic Identity Token
A secure electronic identity token:
is a hardware device to be used during electronic transactions in order to provide for electronic identity verification process;
provides for additional level of assurance;
stores a set of private keys with corresponding public keys;
Electronic Transaction
Is between two or more parties
The parties can be anonymous (privacy is protected if only attributes/details associated with claims are shared). This may involve a coordination hub that removes metadata that would allow the identity provider to have knowledge of which service was being accessed.
The transaction could be indifferent to the identity of the parties involved since it is atomic, or trust and repudiation is not a concern
Enrollment
The process of inauguration of an entity into a context. ()
Enrolment may include verification of the entity's identity and establishment of a contextual identity.
Also, enrolment is a pre-requisite for registration. In many cases, the latter is used to describe both processes.
Foundational Identity
Identity credentials that serve as proof of identity for a wide variety of public and private sector transactions and services and are managed by a foundational identity system.
Foundational Identity System (fID System) (also referred to as legal identification system)
An identification system primarily created to manage identity information for the general population and provide credentials that serve as proof of identity for a wide variety of public and private sector transactions and services. Common types of foundational identification (ID) solutions include civil registries, universal resident or national ID systems, and population registers.
(Adjusted from the )
Typical capacities include:
Provide recognition before the law and proof of legal identity.
The name and nature of legal identification systems vary under national law, but typically include civil registration systems, national identification systems, population registries, and other foundational identification systems.
Functional Identity
Is linked to systems that have a specific function with specific business rules: e.g. education, healthcare, and justice are functional domains that could establish and use functional Identities.
Functional identification systems provide official proof of identity and authorization for particular purposes or sectors. This typically includes identification systems that provide voter identification, ration cards, social security numbers, health cards, tax numbers, and more; in some cases, these credentials may also be recognized as proof of identity for other purposes or sectors.
Historically functional identities are created in the absence of/as complements to foundational identities. In the presence of a proper foundational eID, there is no further need for a separate functional eID.
(Adapted from )
Functional Identity System
Maintains a registry of credentials.
Associates the identity of a person with the entitlement that the functional credential offers.
Optionally offers uniqueness based on the credential type.
Identity Assurance
The confidence provided in the process of identity validation and verification used to establish the identity of the entity to which the credential was issued, and the degree of confidence that the entity that uses the credential is that entity or the entity to which the credential was issued or assigned. ()
Identity Credential
An identity document in a physical (e.g. ID card, driver's license) or digital (eID) form that an identity credential holder may present to authenticate his identity in a physical or electronic interaction;
Data, or the physical object upon which the data may reside, that an identity credential holder may present to authenticate his identity in an electronic or online transaction.
Identity Registry
An identity registry contains individuals identity information, it can be related to group or sub-groups (i.e. for a functional system, a region, a company).
Identity Verification
The process of confirming that a claimed identity is correct by comparing the offered claims of identity with previously proven information. ()
GovStack prefers the term Identity Verification to the term Authentication.
Offers mechanisms for verifying a person’s identity locally or by hitting a service offering the verification capabilities.
Partner
3rd party consuming the services of the building block. Partners should be registered and authorized to use the services (partner management is not yet described in this specification)
Pairwise Pseudonymous Identifier (PPID)
(also: ) Identifier that identifies the Entity to a Relying Party that cannot be correlated with the Entity's PPID at another Relying Party. (OpenID Connect)
Partner Specific User Token (PSUT)
See:
Population Registry
A population registry is a database/system which includes records of the entire population of a country covering citizens but also foreigners staying in the country and also the national diaspora.
UIN
Stands for Unique Identity Number, this number uniquely identifies a person in the . UIN are an optional approach and not necessary.
2 Description
This section provides context for this 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.
This Building Block covers the foundational identity of a natural person. In this Building Block, foundational identity means the identity credentials that serve as proof of identity for a wide variety of public and private sector transactions and services and are managed by a foundational identity system. In contrast, functional identity serves as the proof of identity and authorization just for particular purposes or sectors.
The Identity Building 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.
Those data can be used for different reasons:
Establishing uniqueness of a person;
Verifying a person identity;
Identifying an unknown person;
Claiming an identity;
Verifying presence or liveness;
Deduplication.
Can be pertaining to membership - X is an employee of Y corp
Can be pertaining to ownership - X owns Z car
Can be pertaining to role - X is a doctor
Can be pertaining to any other identity association - X is an organ donor, X studied subject Y at Institution Z
Can protect persons privacy by disclosing the state of attributes without disclosing the attribute itself (i.e. “is older than 18” don’t need to share the age)
Can be pertaining to 3rd party claim, i.e. I claim that something is answerable at a 3rd party verification place
A set of digitally captured and stored attributes and/or credentials that satisfactorily, within context, identify someone or something.
Building on this definition, we might state that an identity is the digital representation of an entity detailed enough to make the individual distinguishable within a digital context.
There are many different schemes and formats for digital identifiers. The most widely used is Uniform Resource Identifier (URI) and its internationalized version Internationalized Resource Identifier (IRI)—the standard for identifiers on the World Wide Web. OpenID and Light-weight Identity (LID) are two web authentication protocols that use standard HTTP URIs (often called URLs), for example. A Uniform Resource Name (URN) is a persistent, location-independent identifier assigned within the defined namespace.
preferably associated with an electronic identity hardware token;
ideally has a hard link back to digital identity.
carries at least functions of electronic authentication and digital signature creation.
Trust is needed in the identity of the parties for legal recourse, reversal, or non-repudiation
Parties are entities - Persons, Businesses, or Things
If the party is a Thing, it is then deemed acting on behalf of a Person or a Business
A transaction is a multi-step interaction and each step could involve flow of data or instructions
At a step level, there is a need for trust in the parties and the data
At a transaction level, there is a need for trust in the parties, the data, and factors such as eligibility and permissions
Privacy and security principles of need to know, selective disclosure, access control, and information security against snooping are needed
Maintains a registry of natural persons and provides issuance and lifecycle management of foundational identities.
Those persons are people needing to interact with a country: citizens, diaspora, foreign residents, foreign workers, refugees, etc.
Has an identity issuance and management process that takes care of the accuracy of information in order to act as a reliable root of trust.
Offers identity assurance in the form of identity verification in the digital realm.
Digital identity and electronic identity serve as foundational level attributes.
Is often associated with a credential that provides entitlements - a functional health identity card both provides identity services of a kind and entitles the holder to access health care services.
Optionally offers identity assurance based on the credential type.
Optionally digital based on the credential type.
Local verification involves trusting the source of the information by (for example) using digital signatures rather than having to go back to the root source of truth (and hence creating a privacy invasive audit record of the check).
Identity verification services might be available in synchronous and asynchronous modes and might have real time or non real time responses.
Online identity verification uses a single or multi-factor mechanism. Identity verification involves an identifier and the factors. The identifier may be the User Identification Number (UIN) or an alias that is associated with the UIN in reference to the eID term described above.
A foundational identity system can offer verification services in a centralized or multi-provider (federated/distributed) model.
In a federated model identity verification has to come from different sources based on the credential used. This means that there is a need for discovery, registration, resolution and routing of verification requests to the appropriate verification service. This needs a web of trust model to be defined. Such a model will also be repeatable for cross border usage where it will be dealing with a federation of foundational identity systems.
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) modelshe Identity Building block will remain approach agnostic and flexible for being capable to adapt to the different policies and existing countries that can exist in adopting countries. This version of the document is focused on a centralized approach already taking into account integration with Functional Identity, therefore covering the federated approach.
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 ID 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 and federated presents lots of benefits in terms of privacy protection. See also Wallet Building Block.
In each of these approaches trust in the identity enrollment and verification flows 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.
Overall, we advocate 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
Enrollment Services allow to on-board new identities and update existing identities for individuals, which means collecting their personal identity data, evidence of them and biometrics.
Identity Verification Services allow a service provider to verify the identity (i.e. authenticate User) and some of their attributes, for example checking a person's declared identity or verifying their age.
Query Services enable trusted and separately authorized partners to make queries on identity data in the Identity Building Block.
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, and declare them as stolen.
Upstream federation services are there to map to and harmonize multiple identities, which creating a link in between various digital identities (including functional identities) that an individual may have in other public or private services, including those abroad.
Notification Services will allow a third party to subscribe to events occurring on identity and to receive notifications, useful to inform external functional building blocks when a person was born or has passed 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, if appropriate, performs informed consent of the individuals of their end usages. The registry should, if appropriate, 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, a UIN Generator will follow predefined business rules for generating a UIN and will make sure that a new generated number has never been already issued. It is recommended that such number does not contain any embedded personally identifiable information (such as, date of birth or gender) that may change or erode privacy. 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.
Biometric Services which offer capacities to compare biometrics in between identities. Key use cases being 1:N search which consist in confirming unicity of a person by comparing its biometrics to all ones stored in the system, 1:1 search to confirm an identity by comparing biometrics data one to one. Those services may be asynchronous when an adjudication system is in place, an adjudication system being a human based decision workflow allowing operators to take decision on uniqueness or identities match based on candidates identified automatically by the biometric search system. Centralized databases of biometric scan introduce significant privacy risks, see, for example, . Biometric services also provide standard interfaces for managing biometric data for operations on biometric data such as conversion, compression, templatization, matching, segmentation and more.
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.
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 System
Identity 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 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 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 ID BB Services Facade which will make its integration transparent toward the remainder of the GovStack.
6 Functional Requirements
This section lists the technical capabilities of this Building Block.
Internal functional components
A common set of unique internal functional components are required to orchestrate the services of the 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 Enrollment
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)
6.2 Identity Verification
Identity Building Block must offer an API to verify Identities following a GovStack 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 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)
6.3. Query services
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, when applicable, by the individual (informed consent). Authorized access control should be part of the 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)
6.4 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)
6.5. Upstream federation services
Identity Building Block must offer an API that trusted and authorized Partners can call to enable Users to link their external identities to their foundational identity. Those identities can be, for instance, functional identities, commercial identities or foreign identities. Local policies may apply what external identities are accepted. (REQUIRED)
Identity Building Block must offer an API that trusted and authorized Partners can call to enable Users to review and unlink the linked external identities. (REQUIRED)
Trust and identity assurance considerations must be taken into account in the identity linking. For instance, linking a high-assurance foundational identity to a low-assurance external identity may erode the overall security of the foundational identity and must be prevented or at least flagged for those who rely on the foundational identity. (REQUIRED)
6.6 Notifications 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.7 Service for users to manage their identity
Identity Building Block must be capable of generating a 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 of attaching an Alias Identifier to the 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)
6.8 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)
9 Internal Workflows
This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases.
the If GovStack will offer global workflow management for cross-building block use cases, Identity Building Block will have its internal workflows for its own internal business flows execution.
Non-exhaustive list of examples:
For onboarding a new individual.
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 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. (REQUIRED)
To ensure the integrity of the enrollment process, the Identity 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 the enrollment process. (REQUIRED)
Identity Building Block must keep track of the enrollment request identifiers within its internal management in order to facilitate audit trail and troubleshooting. (REQUIRED)
Identity Building Block must generate a UIN for every Identity created. This number must be kept secret within the Identity Building Block. (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)
Identity Building Block must offer Identity Verification services based on modalities listed in other resources following a GovStack recommended Open Standard API. (REQUIRED)
To ensure the integrity of the queries, the Identity Building Block must be able to implement technical controls so that only approved partners can engage with the query service. Cryptographic trust should be implemented.(REQUIRED)
Identity Building Block must support encrypted data exchange to ensure privacy protection and prevent data theft. (REQUIRED)
Identity Building Block must keep track of the queries served within its internal management in order to facilitate audit trail and troubleshooting. (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 it 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)
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 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. This 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 (when appropriate) 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)
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 Enrollment 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:
User goes to the Enrollment office.
The Enrollment Client collects user demographic details and supporting documents and calls the createPacket API of the GovStack Packet Store.
Enrollment Client collects user bio-metric details and calls createPacket API of GovStack Packet Store.
Once all the enrollment data is available at the GovStack Packet Store, it triggers enrollment process in the GovStack Packet Processor.
GovStack Packet Processor processes the data and generates a Unique Identity for the user.
The user is notified of successful enrollment and receives the Unique Identity by mail.
9.2.2 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.
The user goes to the Enrollment office.
The enrollment Client retrieves the user demographic details and supporting documents from an existing database and calls the createPacket API of the GovStack Packet Store.
Enrollment Client collects user biometric details afresh and calls createPacket API of GovStack Packet Store.
Once all the enrollment data is available at the GovStack Packet Store, it triggers the enrollment process in the GovStack Packet Processor.
GovStack Packet Processor processes the data and generates a Unique Identity for the user.
The user is notified of successful enrollment and receives the Unique Identity by mail.
9.3 Credential Management
9.3.1 Sharing Credentials
This sequence diagram shows the workflow for sharing credentials.
The user logs into the Citizen Portal.
After authentication, the user can select the format of the credentials to be shared. The format is defined by the attributes such as fully/partially masking.
The user gives consent for sharing the credentials and logs a request. The Citizen Portal returns an event ID.
The user logs in to the Citizen Portal after some time and checks the status of the credential-sharing request using the event ID.
The credentials can be provided as a Verifiable Credential in PDF format with the issuer's signature.
9.3.2 Download Credentials
This sequence diagram shows the workflow for downloading a Unique Identity Card:
The user logs into the Citizen Portal.
After authentication, the user clicks on the Download Card.
The Citizen Portal calls the '/download/personalized-card' API on the IDBB.
IDBB returns a link for the card download.
The Citizen Portal shares the link with the user.
9.4 Notification Workflow
post
Format for sharing identity credentials with an identity partner
Body
idstringOptional
id to hit API
Default: mosip.resident.share.credential
requesttimestringOptional
2021-10-19T17:01:59.538Z
versionstringOptional
Example: 1.0
Responses
200
EventId generated successfully.
application/json
401
Unauthorized
application/json
post
/share-credential
get
Get the status by eventID
Authorizations
HTTPRequired
Authorization code received from /token endpoint
Path parameters
eventIdintegerRequired
Event ID to get the status
Query parameters
languagestringRequired
Language Code in 3 letters. Example- eng
Responses
200
OK
application/json
idstringOptional
id of get event status API
versionstringOptional
version of API
requestTimestringOptional
timestamp when API executes
401
Unauthorized
application/json
get
/events/{eventId}?language=LANGCODE
post
Download the personalized UIN Card
Authorizations
HTTPRequired
Authorization code received from /token endpoint
Body
idstringOptional
id for downloading card
versionstringOptional
version of API
requesttimestringOptional
timestamp when we hit API
Responses
200
OK - The PDF Bytes
400
Bad Request
application/json
401
Unauthorized
application/json
post
/download/personalized-card
No content
post
Update UIN request raised by the resident/citizen
Authorizations
HTTPRequired
ID token received from /token endpoint
Body
idstringOptional
id to hit update uin API.
versionstringOptional
version of API
requestTimestringOptional
timestamp when we get resposne.
Responses
200
OK, update is successful.
application/json
idstringOptional
mosip.resident.updateuin
versionstringOptional
1.0
responsetimestringOptional
2024-03-21T09:14:42.537Z
responseobjectRequired
Give response such as Registration id and 1 message like Notification has been sent to the provided contact detail(s)
post
/update-uin
200
OK, update is successful.
get
Get the status by eventID
Authorizations
HTTPRequired
Authorization code received from /token endpoint
Path parameters
langCodestringRequired
Language Code in 3 letters. Example- eng
Query parameters
fromDatestringRequired
Start date of the request inclusive; the default date will be the 1st of January of that year
pageFetchstringOptional
integer greater than 0, default is 10
pageStartstringOptional
integer starting from 0, default is 0
searchTextstringOptional
This will be used to look for Event Id- string greater than 0 but not more than 30; >= 0 characters; <= 30 characters
serviceTypestringOptional
The service type in general. It can map to different request types. Possible values: AUTHENTICATION_REQUEST, SERVICE_REQUEST,DATA_UPDATE_REQUEST,ID_MANAGEMENT_REQUEST,DATA_SHARE_REQUEST,ALL; default is ALL
sortTypestringOptional
ASC/DESC, default is ASC
Default: ASC
statusFilterstringOptional
Comma separated service types status code- optional. This can be one of - ALL,SUCCESS,IN_PROGRESS,FAILED
toDatestringOptional
End date of the request inclusive; the default date will be the date on which this transaction is being done (date today
Header parameters
localestringRequired
Locale based on Language and country.Used in date time formatting. Ex. en-US
time-zone-offsetstringRequired
Used in time conversion per the client on any timestamps returned in the response. Ex. -330 - for India
Responses
200
OK
application/json
idstringOptional
id to get service history API
versionstringOptional
version of service history API
responseTimestringOptional
401
Unauthorized
application/json
get
/service-history/{langCode}
patch
Activate/Deactivate UIN
Body
idstringOptional
Example - govstack.updateIdentity
versionstringOptional
v1
requesttimestringOptional
timestamp when API executes
metaDataobjectOptional
Responses
200
UIN activation status successfully updated
application/json
idstringOptional
Example - govstack.updateIdentity
versionstringOptional
v1
responsetimestringOptional
timestamp
metaDataobjectOptional
204
No content
401
Unauthorized
403
Forbidden
patch
/updateIdentity
post
Command to be used by administrators to unblock UIN
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.
GET /service-history/{langCode}?fromDate=text HTTP/1.1
Authorization: string YOUR_SECRET_TOKEN
locale: text
time-zone-offset: text
Accept: */*
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.
Login/
Password
Previously given login/password are typed in a login form to verify person identity.
For online access on web site or in mobile application.
Medium
(What you KNOW only)
Require the individual to have access to a digital device having network connectivity and sufficient power stability.
Visual physical identity credential identity control
National ID card provided to the individual includes security features allowing to verify the document is genuine and data printed on it allow to know the identity of the individual.
For fast verification in public place, or when there is no digital identity verification available or no connectivity to network.
Low
(What you HAVE only)
Having been issued and delivered a physical identity credential.
eID card identity data control
National ID card provided to the individual includes a chip in which its identity information is securely written allowing them to get them and make sure about their authenticity.
For identity verification in face to face control.
Medium
(What you HAVE only)
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:
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).
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.
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.
Having been issued and delivered a physical identity credential with a chip (eID card), having access to a digital identity verification device. No need for network connectivity.
eID card based identity verification
National ID card provided to the individual includes a chip in which its identity information is securely written allowing them to get them and make sure about their authenticity. Those same data can be used for a match versus other information like who the person pretends to be, what is printed on the document or it’s biometrics captured live.
For identity verification in face to face control.
High
(What you HAVE and what you ARE)
Having been issued and delivered a physical identity credential with a chip (eID card), having access to a digital identity verification device which can perform a matching between person attributes and chip stored attributes.
Fingerprint 1:1 matching versus ID credential
The individual live capture fingerprint will be compared to its fingerprint(s) captured during its identity creation.
Those original fingerprints being stored on or within its Identity credential.
For identity verification in face to face control or self-control of identity (i.e. airport eGates).
High
(What you ARE)
Having been issued and delivered a physical identity credential including a digital ID into a chip (eID card) or in a cryptogram, having access to a digital identity verification device which can perform an ID Credential reading, fingerprint(s) capture and matching with attributes stored in ID credential.
Fingerprint 1:1 matching online
The individual live capture fingerprint will be compared to its fingerprint(s) captured during its identity creation.
The fingerprints are verifiable using an online service.
For identity verification in face to face control or self-control of identity (ie airport eGates)
High
(What you ARE)
Having been registered to a state recognized identity provider, having access to a connected digital identity verification device which can perform fingerprint(s) capture and access to online identity verification services.
Fingerprint recognition
The individual doesn't provide its identity, a search based on its fingerprints is performed against a database of known identities in order to identify him/her.
NOT RECOMMENDED FOR CIVIL USE. This capability is rather to be used for security purposes in criminal or border control systems or secured building access.
High
(What you ARE)
Having been registered (or not) to a state recognized identity database, having access to a connected digital identity verification device which can perform fingerprint(s) capture and access to online identification services.
Facial 1:1 matching versus ID credential
The individual live face capture will be compared to its face captured during its identity creation.
That original face capture may be stored on or within its Identity credential.
For identity verification in face to face control or self-control of identity (ie airport eGates)
A face liveness detection is recommended.
High
(What you ARE)
Having been issued and delivered a physical identity credential including a digital ID into a chip (eID card) or in a cryptogram, having access to a digital identity verification device which can perform an ID Credential reading, face capture and matching with attributes stored in ID credential.
Facial 1:1 matching online
The individual live face capture will be compared to its face captured during its identity creation.
The face is verifiable using an online service.
For identity verification in face to face control or self-control of identity (ie airport eGates)
A face liveness detection is recommended.
High
(What you ARE)
Having been registered to a state recognized identity provider, having access to a connected digital identity verification device which can perform face capture and access to online identity verification services.
Facial recognition
The individual doesn't provide its identity, a search based on its face is performed against a database of known identities in order to identify him/her.
NOT RECOMMENDED FOR CIVIL USE. This capability is rather to be used for security purposes in criminal or border control systems or secured building access.
High
(What you ARE)
Having been registered (or not) to a state recognized identity database, having access to a connected digital identity verification device which can perform face capture and access to online identification services.
Iris 1:1 matching versus ID credential
The individual live iris captured will be compared to its iris captured during its identity creation.
That original iris capture may be stored on or within its Identity credential.
For identity verification in face to face control or self-control of identity (i.e. airport eGates)
Liveness detection is recommended.
High
(What you ARE)
Having been issued and delivered a physical identity credential including a digital ID into a chip (eID card) or in a cryptogram, having access to a digital identity verification device which can perform an ID Credential reading, iris capture and matching with attributes stored in ID credential.
Iris 1:1 matching online
The individual live iris capture will be compared to its iris captured during its identity creation.
The iris is verifiable using an online service.
For identity verification in face to face control or self-control of identity (i.e. airport eGates)
Liveness detection is recommended.
High
(What you ARE)
Having been registered to a state recognized identity provider, having access to a connected digital identity verification device which can perform iris capture and access to online identity verification services.
Iris recognition
The individual doesn't provide its identity, a search based on its iris is performed against a database of known identities in order to identify him/her.
NOT RECOMMENDED FOR CIVIL USE. This capability is rather to be used for security purposes in criminal or border control systems or secured building access.
High
(What you ARE)
Having been registered (or not) to a state recognized identity provider, having access to a connected digital identity verification device which can perform iris capture and access to online identification services.
OTP
The individual needs to type in a form (online or app) a One Time Password (OTP) received from the identity provider.
Can be used when needing to access an online service.
To be used a second factor of authentication, for example with a login password).
High
(What you KNOW and what you HAVE)
Having been registered to a state recognized identity provider, owning a mobile subscription, being in capacity to receive messages (SMS, messaging, email), having access to service provider online services. It is important to acknowledge different patterns of phone ownership (individual, household, community).
Online ID credential matching
The individual will authenticate versus himself its ID credential online.
The process may include biometrics control versus data printed or stored in the Identity credential, together with genuity check of the document using security features and eventually control of document authenticity versus database of issued documents.
Can be used to perform remote on-boarding of persons in services. To be noted it anyway required a face to face on-boarding to enroll for the Identity credential.
Ensuring the document is genuine can be a challenge, unless an ID credential secured chip is involved as part of the process.
High
(What you HAVE, what you ARE, what you WERE)
Owning an ID Credential registered for online services verification, having a connected smartphone eventually capable of reading a chip.
Online PKI based identity verification
The individual uses its identity credential or a digital device to encrypt or sign identity verification data which can then be verified on server side. A PIN code is requested.
Can be used if ,and only if, a specific PKI infrastructure is in place to issue, read and verify online.
HIGH
(What I HAVE, what I KNOW)
The individual own an identity credential or a digital device storing personal cryptographic secrets.
Behavior based identity verification
The individual is authenticated seamlessly based on its context and behavior following an evaluation of the risk he/she not be himself/herself.
To be used for very frequent access control (i.e. control of office workers) when security and convenience are both importants.
Requires solid on-boarding before.
MEDIUM
(What I DO,
Where I AM)
Having been screened and tracked on normal habits, locations, behaviors to be used for evaluation of fraud risk being online.
Token based identity verification (SSO)
The individual has already been authenticated to a third party system allowing him to avoid a new identity verification and reuse the token.
This mechanism is also named Single Sign On (SSO).
To be used for online identity verification is usage of a digital identity.
Depends on previous identity verification
Having been previously authenticated by a third party system and obtained a verifiable authentication token.
Verifiable Credential
The individual has shared a verifiable credential to a third party system which allows its identity verification.
Can be used in various contexts online/offline.
Can be related to one or several attributes of Identity.
High
(What you HAVE, what you ARE, what you WERE)
Require an electronic or physical support to verify the credential.
If a verifiable credential can be verified offline, connectivity is required to verify the security chain.
Create OIDC Client Endpoint
post
API to add new open ID connect (OIDC) clients, it can be invoked by other modules which manages the relying parties / partners.
Each relying party can associate to one or multiple OIDC client Ids.
On create, OIDC client status will be by default set to "active".
Authorizations
AuthorizationstringRequired
Valid JWT issued by a trusted IAM system with "add_oidc_client" scope.
Body
Responses
200
OK
application/json
responseTimestringOptional
Date and time when the response is generated
401
Unauthorized
post
/client-mgmt/oidc-client
Update OIDC Client Endpoint
put
API to update existing Open ID Connect (OIDC) client, it can be invoked by other modules which manages the relying parties / partners when there any updates on the fields accepted in this API.
Authentication and authorization is based on a valid JWT issued by a trusted IAM system including "update_oidc_client" scope.
Authorizations
AuthorizationstringRequired
Valid JWT issued by a trusted IAM system including "update_oidc_client" scope.
Path parameters
client_idstringRequired
Client Identifier
Example: 785b806d0e594657b05aabdb30fff8a4
Body
Responses
200
OK
application/json
responseTimestringOptional
Date and time when the response is generated
put
/client-mgmt/oidc-client/{client_id}
200
OK
Authorization Endpoint
get
This is the authorize endpoint of Open ID Connect (OIDC). The relying party applications will do a browser redirect to this endpoint with all required details passed as query parameters.
This endpoint will respond with a HTML page / JS application to be loaded in the browser.
All the validations on the query parameter values will be performed, in case of any failures respective error message will be sent along with browser redirection back to relying party application.
Query parameters
scopestring · enumRequired
Specifies what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. OpenID Connect requests MUST contain the OpenID scope value.
Default: openid profilePossible values:
response_typestring · enumRequired
The value set here determines the authorization processing flow. To use the Authorization Code Flow, the value should be configured to "code".
Possible values:
client_idstring · max: 256Required
Valid OAuth 2.0 Client Identifier in the Authorization Server.
redirect_uristring · uriRequired
Redirection URI to which the response would be sent. This URI must match one of the redirection URI values during the client ID creation.
statestring · max: 256Optional
Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie.
noncestringOptional
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.
displaystring · enumOptional
ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the end user.
Possible values:
promptstring · enumOptional
Space delimited case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for re-authentication and consent.
Example: consentPossible values:
max_agenumberOptional
Maximum Authentication Age. This specifies the allowable elapsed time in seconds since the last time the end user was actively authenticated by the OP. If the elapsed time is greater than this value, then the OP MUST attempt to actively re-authenticate the end user. The max_age request parameter corresponds to the OpenID 2.0 PAPE [OpenID.PAPE] max_auth_age request parameter. When max_age is used, the ID Token returned MUST include an auth_time claim value.
ui_localesstringOptional
End user's preferred languages and scripts for the user interface, represented as a space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. For instance, the value "fr-CA fr en" represents a preference for French as spoken in Canada, then French (without a region designation), followed by English (without a region designation). An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.
acr_valuesstring · enumOptional
Requested Authentication Context Class Reference values. Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this Authentication Request, with the values appearing in order of preference. The Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value, as specified in Section 2. The acr Claim is requested as a Voluntary Claim by this parameter.
Possible values:
claims_localesstringOptional
End-User's preferred languages and scripts for Claims being returned, represented as a space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.
claimsstringOptional
This parameter is used to request specific claims to be returned. The value is a JSON object listing the requested claims. The claims parameter value is represented in an OAuth 2.0 request as UTF-8 encoded JSON.
Responses
200
OK
Loads IDBB UI application in browser for interacting with user for Login process
No content
get
/authorize
Token Endpoint
post
Once the client / relying party application receives the authorization code through redirect, this OIDC complaint endpoint will be called from the relying party backend application to get the ID Token and Access Token.
The only supported client authentication method : private_key_jwt
ClientAssertion is a signed JWT with client's private key, corresponding public key should be shared with IDBB during the OIDC client creation process.
clientAssertion JWT payload must be as below:
The JWT MUST contain the following REQUIRED Claim Values and MAY contain few additional OPTIONAL Claim Values:
iss* (Issuer): This MUST contain the client_id of the OIDC / OAuth Client.
sub* (Subject): This MUST contain the client_id of the OIDC / OAuth Client.
aud* (Audience): Value that identifies the IDBB server as an intended audience. The IDBB server MUST verify that it is an intended audience for the token. The audience SHOULD be the URL of the IDBB's token endpoint.
exp* (Expiration): Time on or after which the ID token MUST NOT be accepted for processing.
iat*: Time at which the JWT was issued.
Note: The Client Assertion JWT can contain other Claims. Any Claims used that are not understood WILL be ignored.
Body
grant_typestring · enumRequired
Authorization code grant type.
Possible values:
codestringRequired
Authorization code, sent as query param in the client's redirect URI.
client_idstringRequired
Client Id of the OIDC client.
client_assertion_typestring · enumRequired
Type of the client assertion part of this request.
Possible values:
client_assertionstringRequired
Private key signed JWT, This JWT payload structure is defined above as part of request description.
redirect_uristringRequired
Valid client redirect_uri. Must be same as the one sent in the authorize call.
post
/oauth/token
UserInfo Endpoint
get
Once the access token is received via the token endpoint, relying party backend application can call this OIDC compliant endpoint to request for the user claims.
Consented user claims will be returned as a JWT. This JWT will be a nested JWT which is signed using JWS and then encrypted using JWE.
Example: Assuming the below are the requested claims by the relying party
name : { "essential" : true }
phone: { "essential" : true }
Response 1: When consent is provided for both name and phone number:
{ "name" : "John Doe", "phone" : "033456743" }
Response 2: When consent is provided for only name:
{ "name" : "John Doe" }
Response 3: When Claims are requested with claims_locales : "en fr"
The response is signed and then encrypted, with the result being a Nested JWT. Signed using the IDBB's private key. Signed full JWT will then be encrypted using OIDC client's public key.
401
Unauthorized
get
/oidc/userinfo
JSON Web Key Set Endpoint
get
Endpoint to fetch all the public keys of the IDBB server. Returns public key set in the JWKS format.
Responses
200
OK
application/json
get
/.well-known/jwks.json
200
OK
Configuration Endpoint
get
This endpoint is only for facilitating the OIDC provider details in a standard way.
URL using the https scheme with no query or fragment component that the RP asserts as its Issuer Identifier. This also MUST be identical to the iss Claim value in ID Tokens issued from this Issuer.
authorization_endpointstringRequired
URL of the OAuth 2.0 Authorization Endpoint.
token_endpointstringRequired
URL of the OAuth 2.0 Token Endpoint.
userinfo_endpointstringRequired
URL of the OP's UserInfo Endpoint.
jwks_uristringRequired
URL of the OP's JSON Web Key Set [JWK] document.
registration_endpointstringRequired
URL of Client Registration Endpoint.
claims_supportedstring[]Optional
JSON array containing a list of the Claim Names of the Claims that the OpenID Provider MAY be able to supply values for.
claims_locales_supportedstring[]Optional
Languages and scripts supported for values in Claims being returned.
ui_locales_supportedstring[]Optional
Languages and scripts supported for the user interface.
get
/.well-known/openid-configuration
200
OK
Generate Link Code endpoint
post
Generate link code request is raised from IDBB UI application.
UI application creates a deeplink with this link-code as parameter.
This deeplink is embedded in a Machine-readable-code (like QR code) and the same is rendered in the UI.
End user scans this machine-readable-code to open wallet app.
On open of wallet-app, wallet-app invokes /link-transaction endpoint.
In the UI application, once machine-readable-code is rendered, at the same time /link-status endpoint is invoked as a long polling request.
Header parameters
X-XSRF-TOKENstringRequired
CSRF token as set in cookie key 'XSRF-TOKEN'
Body
requestTimestringRequired
Responses
200
OK
application/json
responseTimestringOptional
post
/linked-authorization/link-code
200
OK
Link status endpoint
post
The link status endpoint is invoked from IDBB UI application.
Checks the status of link code and will return the status as LINKED once the /link-transaction endpoint is called from wallet application.
Header parameters
X-XSRF-TOKENstringRequired
CSRF token as set in cookie key 'XSRF-TOKEN'
Body
requestTimestringRequired
Responses
200
OK
application/json
responseTImestringOptional
post
/linked-authorization/link-status
200
OK
Link authorization code endpoint
post
Link authorization code endpoint is invoked from UI application.
This is a Long polling request to IDBB backend.
validates the transactionId
validates the linkCode if its LINKED.
checks the cache to see if the auth-code is generated, if yes returns the response.
If the auth-code is not yet generated, polling request waits for the configured time.
On successful response, IDBB UI should redirect to the provided redirectUri with auth-code or error details.
Header parameters
X-XSRF-TOKENstringRequired
CSRF token as set in cookie key 'XSRF-TOKEN'
Body
requestTimestringRequired
Responses
200
OK
application/json
responseTimestringOptional
post
/linked-authorization/link-auth-code
200
OK
Link Transaction endpoint
post
The link transaction endpoint is invoked from Wallet-app.
Validates the link-code and its expiry and generates the linkTransactionId. This linkTransactionId is linked to transactionId used in the /link-code endpoint.
Returns the auth-factors, clientName, logoUrl, User claims, authorize scopes along with linkTransactionId.
Note:
Wallet-app will hereafter address the transaction with this linkTransactionId for the /authenticate and /consent endpoints.
Body
requestTimestringRequired
Responses
200
OK
application/json
responseTimestringOptional
post
/linked-authorization/link-transaction
200
OK
Linked Authentication Endpoint
post
Once end user provides the user identifier (UIN/VID) and all the required auth challenge to the Wallet-app, this endpoint will be invoked from wallet-app.
Supported auth-challenge depends on the integrated IDBB implementation.
Validates linkedTransactionId.
Validates null / empty individualId.
On Authentication Success: Only linkTransactionId is returned in the below response without any errors.
On Authentication Failure: Error list will be returned.
Once the authentication is successful and user permission is obtained, this endpoint will be invoked by the wallet app to send the accepted user claims and permitted scopes.
Validates linkedTransactionId.
Validate accepted claims and permitted scopes in the request.
If valid, stores the accepted claims and permitted scopes in the datastore.
This section provides information on the core data structures/data models that are used by this Building Block.
7.1 Resource Model
Identity 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.
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 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 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 PPID (Pairwise Pseudonymous identifier, a.k.a. 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.
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.
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 .
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.
ACR Value
Authentication Factors
&& - 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 [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.
7.3 Identity Management Data Structures
Identity management uses these data structures.
7.3.1 Enrollment Request
Description: The purpose of enrollment request is create/update enrollment of users using new registration process, importing data from existing servers, or a mix of these two processes.
Fields:
Name
Description
Example
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:
7.4 Credential Management Data Structures
Credential management uses these API fields and data structures.
7.4.1 Common API Parameters
This table describes common parameters used by the Credential Management APIs.
Name
Type
Description
Example
7.4.2 Request to Share Credential
This table describes the parameters of the schema 'ShareCredentialInfo' used by the Credential Management API '/share-credential'.
Name
Type
Description
Example
7.4.3 Event Response for Sharing Credential
This table describes the parameters of the schema 'EventResp' used by the API '/events/{eventId}?language=LANGCODE'.
Name
Type
Description
Example
7.4.4 Update Credential Information for a Unique Identity Number
This table describes the parameters of the schema 'UpdateUINInfo' used by the API '/update-uin'.
Name
Type
Description
Example
7.4.5 Status of Credential Service Request
This table describes the parameters of the schema 'ServiceHistoryInfo' used by the API '/service-history/{langCode}'.
Name
Type
Description
Example
7.4.6 Update identity information for a specific UIN
This table describes the parameters of the schema 'ServiceHistoryInfo' used by the API '/service-history/{langCode}'.
Name
Type
Description
Example
7.4.7 Administratively block/unblock UIN
This table describes the parameters of the schema 'UINAdminRequest' used by the APIs '/block' and '/unblock'.
Name
Type
Description
Example
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.
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
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.
Requests access to the address claim
phone
string
Requests access to the phone_number and phone_number_verified claim
phone - This scope value requests access to the phone_number and phone_number_verified claim.
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.
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.
idbb:acr:linked-wallet-static-code
WLA && ( PIN || Password )
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
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.
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>
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
responsetime
string
Response time of the API
2022-06-23T12:00:40.326Z
errors
Array of objects
Errors if any
errors.errorCode
string
The error code
errors.message
string
The error message
sharableAttributes.format
string
Format of attribute
DDMMYYYY
sharableAttributes.isMasked
boolean
Boolean value whether to mask or not
true
purpose
string
Alphanumeric string stating the purpose of sharing the credential
Sharing Credential with Partner
consent
string
Consent whether Accepted or denied
Accepted
individualId
string
UIN/Vid of logged in user
summary
string
short summary about the event
timestamp
string
local timestamp
info
object
Info for multiple attributes
info.purpose
string
Purpose to share credential like
sharing with a banking parter
info.applicantName
string
name of applicant
info.partnerId
string
parter id to which we want to share credential
info.partnerLogo
string
Logo of partner if any
info.partnerName
string
name of partner
info.paymentStatus
string
status of payment
info.partnerTransactionId
string
unique transaction id of payment if any
info.deliveryAddres
string
delieveryAddress of user in case of order physical card
info.authenticationMode
string
mode of authentication like OTP
info.vidType
string
type of vid
permanent or one-time
info.vid
string
virtual id that is created with the help of uin
info.attributeList
string
list of attributes
firstName, email, etc.
info.downloadCardLink
string
direct link to download
info.orderTrackingLink
string
direct link to track order status
info.trackingId
string
id to track order
otp
string
otp to verify mobile number
identityJson
string
base 64 encoded identity value to update
documents
Array of objects
Array of document type and content
documents.name
string
document cateogory
proof of resident
documents.value
string
document value
pdf content
totalPages
integer
total number of pages
data
Array of objects
data.eventId
string
Random 16 digits eventId
data.eventDescription
string
details of events
data.eventStatus
string
status of event
data.timeStamp
string
timestamp of response
data.requestType
string
type of request
documents.category
string
document cateogory
proof of resident
documents.value
string
document value
pdf content
verifiedAttributes
array of Strings
verifiedAttributes.attributeString
string
name off the verified attribute
registrationId
string
unique id created while registring uin
uin
string
unique value for each individual
expiryTimestamp
string
timestamp when it will expire
Name
Type
Description
Notes
sub
string
Subject identifier
Contains the value of the PSUT
name
string
Full name for this end user
address
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
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
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 )
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
id
string
ID of the API
mosip.resident.enrollment
version
string
Version of the API
v1
requesttime
Name
Type
Description
Example
version
object
Contains information about the version of the BIR
version.major
integer<int32>
Major version number
1
cbeffversion
Name
Type
Description
Example
version
object
Contains information about the version of the BIR
version.major
integer <int32>
Major version number
1
version.minor
Name
Type
Description
Example
id
string
ID of the API
version
string
Version of the API
responsetime
id
string
ID of the API
resident.share.credential
version
string
Version of the API
1.0
requesttime
string
Request time of the API
partnerId
string
Id to which credentials will be shared
resident.share.credential
sharableAttributes
Array of objects
sharableAttributes.attributeName
string
Name of attribute
eventId
string
The eventId for the share credential format
Randomly generated 16 digit number
eventType
string
Type of event
Authentication
eventStatus
string
Status of request
transactionID
string
transactionId will be shown that is used to send otp
individualId
string
uin/vid which is used to send otp for updating uin
individualIdType
string
type of individual id
pageNo
integer
starting number of page from where history needs to be fetched
