Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Terminology used within this specification.
| Term | Description |
|---|---|
Authorization
The process or action of authorizing a user to perform an action, for example accessing and using a service. Authorization is not responsibility of 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 ‘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.
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.
Civil Registry
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
Following is a general description of claims. For the purpose of this document, only the first claim description is relevant since claims for foundational identity only refer to the question ‘who are you’ and not ‘what are you’.
Can be pertaining to identity - I am X
Can be pertaining to entitlement or eligibility - X is allowed to vote
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
Credential
Taken from the World Bank Group's Identification for Development (ID4D) Practitioners Guide Glossary, adapted from ID4D Technology Landscape and Public-Private Cooperation reports.
A document, object, or data structure that vouches for the identity of a person through some method of trust and authentication. Common types of identity credentials include—but are not limited to—ID cards, certificates, numbers, passwords, or SIM cards. A biometric identifier can also be used as a credential once it has been registered with the identity provider.
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 (eID);
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 (eID).
Digital Identity
(Adjusted from ITU, Digital Identity Roadmap Guide, 2018)
Digital identity is the unique representation of a subject engaged in an online transaction. A digital 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.
Digital identity allows an entity (citizen, business, administration) to be distinguished from any other.
A set of digitally captured and stored attributes and/or credentials that satisfactorily, within context, identify someone or something.
Is a ‘representation of an entity in the form of one or more attributes that allow the entity or entities to be sufficiently distinguished within context’. Building on this definition, we might state that a digital identity is the digital representation of an entity detailed enough to make the individual distinguishable within a digital context.
Digital Identifier
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.[19] 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.
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.
(Source)
Electronic Identity (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;
preferably associated with an electronic identity hardware token;
ideally has a hard link back to digital identity.
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;
carries at least functions of electronic authentication and digital signature creation.
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
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
Foundational Identity System (fID System) (also referred to as legal identification system)
(Adjusted from the World Bank Group's Identification for Development Practitioners Guide Glossary)
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.
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.
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.
Functional Identity
(Adapted from Principles on Identification for Sustainable Development, February 2021)
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.
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.
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.
Optionally offers identity assurance based on the credential type.
Optionally digital based on the credential type.
Identity Credential
An identity document in a physical or digital 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
Offers mechanisms for verifying a person’s identity locally or by hitting a service offering the verification capabilities.
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.
Identity and Verification Building Block
Building Block specified in current documentation.
In charge to create, manage life cycle, audit mechanisms, and verify identities.
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)
Partner Specific User Token (PSUT)
Uniquer identifier of pair composed of an Individual and a Partner. Each partner then can identify an individual, but all of the different partners use a different PSUT preveting cross-database aggregation.
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.
Profile
An individual set of claims part of the same set.
UIN
Stands for Unique Identity Number, this number uniquely identifies a person in the Foundational ID system. UIN are an optional approach and not necessary.
Developed by Jaume Dubois (ID30), Ramesh Narayanan (MOSIP), Sasikumar Ganesan (MOSIP), Vishwanath V (MOSIP), Dr. P. S. Ramkumar (ITU), Torsten Lodderstedt (OpenID Foundation), Jane Rose (Technoforte)
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 Build Block must have any response data payload it returns through its API only in the form of JSON or YAML formatted datasets. It is left to the application consuming the response to present it appropriately (e.g. as an Event list or calendar) and provision for associated user interface interactions.
The Identitity Building Block must enable usage from the following actors:
"BB_Admin" who manages this Building Block to run efficiently in a hosted environment;
"Partners" who get registered and can obtain access to services after authorization ;
"Users" who will manage their Identity information, access to this information by third parties, credentials and preferences;
"Subscribers" will be notified of identity change events after registration.
The internal storage of the Identity Building Block must hold the configuration, status, and logged information of all scheduled events. It must also maintain a repository of details of Partners, Users and Subscribers. The Key digital functionalities that are considered within the current scope of the specifications are listed below:
Registered and Authorized Partners have access to Identity Building Block Usage APIs to request Authentication of Users, if successful they can collect personal information after a User informed consent is given. For a specific Partner and a specific User, the Identity Building Block will produce a unique and repeatable Partner Specific User Token (PSUT).
New Users can be on-boarded following an Enrollment process, this process can be composed of one or several steps with data coming from one or multiple sources. Once a new identity has been registered a Unique Identifier will be generated for further representing the User in the GovStack. For privacy purposes, this Unique Identifier will be kept secret inside the Identity Management system, and tokens (randomly generated identifiers) or aliases (existing identifiers) will be linked to it and shared with the User for further involvement in the Usage APIs or for the Credential management. User Interfaces and APIs will allow a user to have a management of its personal data for CRUD requests (Create, Read, Update, Delete) according to GDPR regulation and to the Adopting Country laws, policies and practices. A User will have the possibility to generate a temporary and revokable Virtual ID to preserve its privacy for temporary use. A User will have the possibility to link an existing personal identifier for leveraging on existing forms of trusted ID (i.e. ID Card Number, Passport Number, Phone Number, e-mail address, etc.) this identifier will be usable within ID Usage services.
A User will have the possibility to generate Credentials containing a set of claims, being personal attributes or declarations (i.e. I am an adult). Those credentials will be possible to be issued in the form of Verifiable Credentials (World Wide Web Consortium, International Civil Aviation Organization, or mobile driving license), with the objective to be readable and verifiable against the issuer by a third party. Credentials may have a limited lifetime or not and could be limited to usage by specific partners. Identity Building Block would allow a user to suspend (temporarily) or revoke (definitely) a Credential which then would become unusable with the Usage APIs. A User could obtain physical forms of Credentials printed on a physical support (card, paper, etc.), the information printed on the credential would be shared as a verifiable Credential to ensure backward trustability of the information, and the Physical Credential layout could be generated by the Identity Building Block in a PDF format for a further printing by a credential printing partner. An API would be available to search, authenticate and manage the credentials of a specific User.
Partners will have the possibility to register for Identity-related events for being notified when they will happen. Identity-related events being the creation of identity (new User on-boarded, could be birth registered or a new user registered), update in one or several of the identity personal attributes, or event happening to that identity (i.e. death, disappearance) Subject to preliminary authorization, Partners could register to type of events applicable to all Users, or to specific Users or using filters on some attributes (i.e. age reaching 18) When an event will occur the Identity Building Block will send a notification to the registered partners, then the partner will be in the capacity to request Identity Building Block event-related information.
GovStack administrators will have functionalities to configure the Identity Building Block from a central place.
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.
The Identity Block creates, manages, and uses a digital foundational identity (functional identity is not in the scope of this document). As a part of the overall identity system, it can be interfaced with other Building Blocks in order to realize the complete set of requirements necessary for the delivering identification services and managing lifecycle of Foundational Identities.
The Identity Building Block is composed of a set of interoperable sub-components/modules dedicated to the management of the foundational identity offering different services for ensuring a trusted foundational identity for enabling related use cases.
The guidance from this Building Block takes note of recognized approaches across the globe which in detail and deployment can vary greatly. These approaches will consider central, federated, and distributed (decentralized) models, the Identity Building block will remain approach agnostic and flexible for being capable to adapt to the different policies and existing countries that can exists in adopting countries. This version of the document is focused on centralized approach already taking into account integration with Functional Identity, therefoce covering the federated approach. Fully distributed approach (decentralized identity issuance or self-issuance) is not yet covered yet .
This Building Block may have its own internal workflows and user interface together with its own repositories for delivering its functions.
This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases.
If GovStack will offer global workflow management for cross-building block use cases, Identity and Verification Building Block will have its internal workflows for its own internal business flows execution.
Non-exhaustive list of examples:
For onboarding a new individual.
For managing identity changes after an event on a person's identity (name change, death, etc.).
For life cycle management of an individual's identity evidence (i.e. ID Cards).
For management of access rights to services on an individual's data.
Those workflows will be described in a later version.
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.
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.
The version history table describes the major changes to the specifications between published versions.
| Version | Authors | Comment |
|---|
This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.
The Cross-cutting requirements described in this section are an extension of the cross-cutting requirements defined in the .
Enrollment services for a digital ID in the form of a certificate using the physical credentials of the enrollee (a human citizen subject) and the process of the Identity Building Block (see the functional requirements for Identity in the Identity Building Block Definition). A feature for invalidating, locking or disenrollment/revocation of the digital ID shall also be provided as a response measure to both human citizen subjects leaving the system and responding to security breaches encountered. Digital certificate enrollment must be provided by the solution but is not required for every human citizen subject (see below). Notes:
It is anticipated that the Identity Building Block will call this feature either directly via API or indirectly via the IAM features of the Security Building Block for users electing to use an electronic ID consisting of certificates as a part of the account provisioning process. The digital ID will then be stored with the physical ID records in the identity Building Block and sent to the new user via secure means (probably installed on their device).
Simple numerical digital IDs will also be supported for human citizen subjects as an option where users are unable to leverage certificates-based digital IDs. The requirements governing this are to be stipulated by the Identity Building Block (see the Identity Building Block Definition).
Third-party organizations and internal subjects (both human and non-human) must be issued valid signed digital certificates in order to establish and maintain secure inter-organization and internal communications.
The overall solution suite shall also be able to implement multi-factor authentication using simple numeric digital IDs for human citizen subjects such as their tax file or social security number of the user.
A selection of various alternatives for digital ID is required in order to cater for more or less digitally-savvy citizens. Various token types are also required to be optimally supported such as HOTP and TOTP tokens, SMS, email, push notifications, SSH keys, X.509 certificates, Yubikeys, Nitrokeys, U2F and WebAuthn. Vendors of solutions SHOULD articulate the benefits of what they propose in their solution.
Note that multi-factor authentication must be able to be implemented for both external and internal subjects (people, systems, components etc.) but is not necessarily required for internal non-human subjects (such as building block components) as they communicate via the information mediator Building Block (see the Information Mediation Building Block Definition).
Where human citizen subjects adopt the use of a simple numerical digital ID, the multi-factor authentication process MUST include a time-sensitive credential (AKA OTP or one-time PIN).
Whilst ID and Verification as defined and understood in this Building Block should be supported by local or supranational laws and regulations (like internal security or global AML rules), translation of the appropriate use, in reality, is complex and hardly enforceable. Hence, we recommend that any solution should have a defined consent management mechansîsm by design. The specifications for such mechanisms are out of scope for this Building Block, but should follow the following requirements:
Consent should be created in the context of the user and should be available to the user.
Following the logic that a user is asked to give consent for a particular activity/data share. (Some other system linking the user with the activity). Assuming that the overall system sends the consent request to the appropriate user then their response (I give consent) is stored and managed in the consent management Building Block or any other responsible party). If the user is a mother who does not yet have a registered identity they can still be the 'person' who is asked for their consent.
Address ownership of register and access questions: presumably, the consent register is only held by the data controller who is acting on the basis of the consent.
Purpose limitation of the consent.
A request-response approach or a link to a transaction ID and parties and dates would also help.
An assisted model would also be required, where 3rd party agencies can come in to collect consent from the user.
Apart from technical requirements, it is helpful to differentiate between consent as an ethical process versus consent as a legal basis for processing personal data (certainly under GDPR).
Trust Frameworks can be considered a mechanism to enable the trusted exchange of information between sovereign partners. The Trust Framework is a much-discussed concept and this report recommends including the specifications in the second iteration as a sub-Building Block whereby additional experts should be included.
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 .
The microservice interfaces are defined as per .
For implementation purposes, it is suggested to refer .
The Identity usage APIs are a set of OpenAPI specifications exposed by the Identity Building Block to other building blocks and applications for user verification.
The Identity usage APIs are based on the following principles:
Verification APIs are inspired from OpenID Connect protocol which simplifies integrations using pre-existing libraries
Only secure options in OpenID connect should be supported to ensure the user data is handled securely
All biometric capture for user verification should be done using
For Identity Building Block implementations that support mobile wallet integration, the following API spec should also be implemented.
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).
This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Identity Building Block Specification.
This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Identity Building Block Specification.
This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Identity Building Block Specification.
This Services APIs is not yet specified, but it should be the purpose of a next iteration of the Identity Building Block Specification.
This section provides information on the core data structures/data models that are used by this Building Block.
Identity and Verification Building Block requires data objects, below are the main ones involved listed:
Identities of individuals identified by unique identifiers.
Identifiers:
Token numbers are associated uniquely with a set of data, and identifiers are used to refer to those data without having to actually copy them.
They can be stored then in separate repositories with specific restricted access.
Identifiers can be used to uniquely identify Foundational IDs or Functional IDs.
Token identifiers can be used to avoid data aggregation and ensure capacity to forget an identity.
As identity data should be stored in different storage to ensure privacy protection allowing then data separation and data minimization principles, it’s necessary to use different identifiers for different types of data.
Credentials:
Issued for individuals or presented by them, ID Credentials related to an individual should be traced and accessible in the system in order to have the capacity to identify fraud and do an investigation on them, so as to perform auditing.
Registration requests
Requests will be received by the Identity and Verification Building Block, for example, identity enrollment requests or identity data update registration requests, those requests will be then managed by the different subsystems and the workflows of the Identity and Verification Building Block.
Identification Services
A set of services will be offered on top of identities to identify a person, check some of his/her attributes (i.e. age), or obtain some certified personal information when needed and authorized.
Third parties service user entities
External entities which could be GovStack Building Blocks or not, will have access to and use the services, for that purpose, their access will be granted, consent may be given by the individuals and their activities will be logged.
Identity verification involves the below data structures.
Description: End-user claim is the user information that can be shared with the relying party once the end-user authentication is completed in the Identity Building Block. Below is a set of standard claims that will be supported by the Identity Building Block implementation
Fields:
sub - Subject identifier with the value of PSUT (Partner Specific User Token). This value should be unique for the end user and relying party combination. The same user should have a different subject identifier in different relying party systems to preserve privacy. It must not exceed 255 ASCII characters in length. The sub-value is a case-sensitive string.
name - End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences.
given_name - Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.
family_name - Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.
middle_name - Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.
nickname - Casual name of the End-User that may or may not be the same as the given_name.
preferred_username - Shorthand name by which the End-User wishes to be referred to at the RP. This value may be any valid JSON string including special characters such as @, /, or whitespace. The RP must not rely upon this value being unique.
address - End-User's postal address. The value of the address member is a JSON structure containing some or all of the members from the below list.
formatted - Full mailing address, formatted for display or use on a mailing label. This field may contain multiple lines, separated by newlines. Newlines can be represented either as a carriage return/line feed pair ("\r\n") or as a single line feed character ("\n").
street_address - Full street address component, which MAY include house number, street name, Post Office Box, and multi-line extended street address information. This field may contain multiple lines, separated by newlines. Newlines can be represented either as a carriage return/line feed pair ("\r\n") or as a single line feed character ("\n").
locality - City or locality component.
region - State, province, prefecture, or region component.
postal_code - Zip code or postal code component.
country - Country name component.
gender - End-User's gender. Values defined by this specification are female and male. Other values may be used when neither of the defined values is applicable.
picture - URL of the End-user's profile picture. This URL must refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.
email_verified - True if the End-user's e-mail address has been verified; otherwise false.
phone_number_verified - True if the End-user's phone number has been verified; otherwise false.
zoneinfo - String from zoneinfo time zone database representing the End-User's time zone. For example, Europe/Paris or America/Los_Angeles.
Description: Scopes can be used to request that specific sets of information be made available as claim values. The following scope values will be supported by Identity Building Block implementation for requesting specific details of end-user.
Fields:
The following claims are used within the ID Token
profile -This scope value requests access to the End-User's default profile claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, picture, gender, birthdate, zoneinfo and locale.
email - This scope value requests access to the email and email_verified claim.
address - This scope value requests access to the address claim.
phone - This scope value requests access to the phone_number and phone_number_verified claim.
Fields:
iss - Issuer identifier for the Identity Building Block implementation. The iss value is a case-sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.
sub - Subject identifier with the value of PSUT (Partner Specific User Token). This value should be unique for the end user and relying party combination. Same user should have a different subject identifier in different relying party systems to preserve privacy. It must not exceed 255 ASCII characters in length. The sub-value is a case-sensitive string.
aud - Audience that this ID Token is intended for. It must contain the OIDC client_id of the Relying Party as an audience value.
exp - Expiration time on or after which the ID Token must not be accepted for processing. The processing of this parameter requires that the current date/time must be before the expiration date/time listed in the value. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
iat - Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
auth_time - Time when the End-User authentication occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
nonce - String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. If present in the ID Token, Clients MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authentication Request.
acr - Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied. Below is the list of supported ACRs based on the authentication factors implemented by the Identity Building Block implementation.
&& - This is a multi-factor authentication where both auth factors need to be authenticated.
|| - This is a condition where there is more than one auth factor which shares the same ACR level.
at_hash - Access Token hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token's JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The at_hash value is a case-sensitive string.
Fields:
iss - Issuer identifier for the IDBB implementation. The iss value is a case-sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.
exp - Expiration time on or after which the Access Token must not be accepted for processing. The processing of this parameter requires that the current date/time must be before the expiration date/time listed in the value. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
aud - Audience that this Access Token is intended for. It must contain the OIDC client_id of the Relying Party as an audience value.
sub - Subject identifier with the value of PSUT (Partner Specific User Token). This value should be unique for the end user and relying party combination. Same user should have a different subject identifier in different relying party systems to preserve privacy. It must not exceed 255 ASCII characters in length. The sub-value is a case-sensitive string.
client_id - The OIDC client identifier that was assigned to the relying party when the client registration is done.
iat - Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
jti - JWT ID provides a unique identifier for the JWT. The identifier value must be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object. This can be used to prevent the JWT from being replayed. The jti value is a case-sensitive string.
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:
Federation protocol: .
Image format for biometric data: .
Verifiable credentials (to be covered in the next iteration of this document in more detail): World Wide Web Consortium ().
Modular Open Source Identity Platform (), which also includes information about their .
Open Standard Identity APIs for interoperability within Identity System: .
.
.
Take consideration of consent receipts ()
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 .
The provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here.
birthdate - End-User's birthday, represented as an [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.
email - End-User's preferred e-mail address. Its value must conform to the [RFC5322] addr-spec syntax.
phone_number - End-User's preferred telephone number. [E.164] is RECOMMENDED as the format of this Claim, for example, +1 (425) 555-1212 or +56 (2) 687 2400.
locale - End-User's locale, represented as a [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA.
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 .
| ACR Value | Authentication Factors |
|---|
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].
0.8 | 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 | Jaume Dubois, Ramesh Narayanan, Sasikumar Ganesan, Vishwanath V, Dr. P. S. Ramkumar, Torsten Lodderstedt, Jane Rose, Amy Darling | Adding requirements numbers for Identity Building Block. |
1.0 RC1 | Jaume Dubois, Ramesh Narayanan, Sasikumar Ganesan, Vishwanath V, Dr. P. S. Ramkumar, Torsten Lodderstedt, 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 | Introduce Usage APIS (Verification & Federation). |
1.0 | Wesley Brown, Steve Conrad, Valeria Tafoya | Final edits to align content to specification template for GovStack 1.0 release |
Name | Type | Description | Notes |
sub | string | Subject identifier | Contains the value of the PSUT |
name | string | Full name for this end user |
address | string | Address of the end user |
gender | string | End user gender |
birthdate | date | End user birthdate |
picture | URL | URL to location where end user's picture is stored |
string | Email address for end user |
phone | string | Primary phone for end user |
locale | string | End user's locale |
Name | Type | Description | Notes |
profile | string | Requests access to the End-User's default profile claims |
string | Requests access to the email and email_verified claim |
address | string | Requests access to the address claim |
phone | string | Requests access to the phone_number and phone_number_verified claim |
Name | Type | Description | Notes |
iss | URL | Issuer identifier for the Identity Building Block implementation |
sub | string | Subject identifier with the value of PSUT (Partner Specific User Token) | Should be unique for the end user |
aud | string | Audience that this ID Token is intended for | Must contain the OIDC client_id |
exp | number | Expiration time on or after which the Access Token must not be accepted for processing |
iat | number | Time at which the JWT was issued |
auth_time | number | Time when the End-User authentication occurred |
nonce | string | Used to associate a Client session with an ID Token, and to mitigate replay attacks |
acr | string | Specifying an Authentication Context Class Reference value that identifies which was satisfied |
at_hash | string | Access Token hash value. |
idbb:acr:static-code | PIN || Password |
idbb:acr:generated-code | OTP || TOTP |
idbb:acr:linked-wallet | WLA (Wallet Local Authentication) |
idbb:acr:biometrics | BIO (Biometrics from a L1 SBI device) |
idbb:acr:biometrics-generated-code | BIO && ( OTP || TOTP ) |
idbb:acr:linked-wallet-static-code | WLA && ( PIN || Password ) |
Name | Type | Description | Notes |
iss | URL | Issuer identifier for the Identity Building Block implementation |
exp | number | Expiration time on or after which the Access Token must not be accepted for processing | Current date/time must be before the expiration date/time listed |
aud | string | Audience that this Access Token is intended for |
sub | string | Subject identifier | Contains the value of PSUT |
client_id | string | The OIDC client identifier that was assigned to the relying party when the client registration is done |
iat | number | Time at which the JWT was issued |
jti | string | JWT ID provides a unique identifier for the JWT |
This section lists the technical capabilities of this Building Block.
A common set of unique internal functional components are required to orchestrate the services of the Scheduler Building Block as shown below. The REST API's interfaces route service requests to/from external Building Blocks and appropriate internal blocks in appropriate formats. A brief description of the generic functionality of each of these components has been given below from a minimum viable product perspective. Detailed design and feature lists of these blocks can be customized by developers to optimally match specific target implementation needs.
Identity Building Block must offer an API to verify Identities following a Gov Stack recommended Open Standard API. (REQUIRED)
Identity Building Block must offer an API to Verify Identity of an individual based on one of its known identifiers. (REQUIRED)
Identity Building Block must offer an API to retrieve personal attributes of an individual from one of its identifiers. To be noted that this service will be subject to preliminary access granted by the system and by the individual (informed consent). Authorized access control should be part of API as opposed to external configuration alone. This ensures that relying parties are verified by the API before sharing sensitive data. (REQUIRED)
Identity Building Block must offer an API to identify an unknown individual, which means retrieve an identity identifier from a set of personal attributes sent. This service is normally to be used for security/law enforcement purposes and must be limited to registries of wanted people. For privacy and security reasons, this feature should only be considered where clear and accountable security/law enforcement rules are in place. (REQUIRED)
Identity Building Block must offer an API to verify one characteristic of an individual without having to disclose actually the recorded related attributes. The typical request response is Yes or No (sample use case: age verification, is a person older than 18 > Yes to No). (REQUIRED)
Identity Building Block must offer Identity Verification services based on modalities listed below following a GovStack recommended Open Standard API. (REQUIRED)
Identity verification can be performed in several ways and based on several modalities depending on various criteria.
For example, Identity verification will be performed according to the:
Context of identity verification: online, face-to-face by a third party, self-identity verification, in the absence of infrastructure and technologies.
Capacities given to the individual: having an ID Card, a person Identifier, a password or PIN code, using its biometrics, mobile subscription, or smartphone.
Status of the individual: can they read? Do they have usable fingerprints? Are they old enough to have an ID Card?
Level of trust required: according to the sensitivity of the operations, level of assurance required, policies established by the state or by the service provider, multiple factor identity verification.
Business constraints: does the use case require to be very fast, touchless, seamless, physical, or digital?
Local laws and regulations: the identity verification could differ according to local regulations and laws which may indicate specific ways to perform identity verification.
Below shown table will list the different modalities that can be used to perform an identity verification, the Identity Building Block may use any of them including a combination of several of them to verify a person's identity.
Through this list of capabilities we can see there are numerous but limited options for Identity Verification that can be combined or not, this list allows us to normalize them all into the following inputs for an identity verification:
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.
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. pre-enrollment and enrollment). (REQUIRED)
Identity Building Block must offer capacity to search, retrieve and update and enrollment made (if it has not been committed yet). (REQUIRED)
Identity Building Block must allow to control integrity and origin of an enrollment request by implementing enrollment meta-data about the context and actors of the enrollment, such as signature of data to ensure integrity. To ensure the integrity of the enrollment process, the Building Block must be able to implement technical controls so that only approved enrollment services can engage with the enrollment service. Cryptographic trust should be implemented.(REQUIRED)
Identity Building Block must support receiving encrypted data to ensure privacy protection and prevent data theft. (REQUIRED)
Identity Building Block must offer capacity to perform an enrollment offline which means not expecting interactions between registration client and server during the enrollment process, and data being uploaded as a whole packet. (REQUIRED)
Identity Building Block must keep track of the enrollment request identifiers within its internal management in order to facilitate traceability and troubleshooting. (REQUIRED)
Identity Building Block must generate a Unique Identifier for Identity created. This number must be kept secret within the Identity Building Block. (REQUIRED)
Identity Building Block must be capable to generate Virtual Identifier for referring to a User. The Virtual Identifier will be linked to the User's Unique Identifier. (REQUIRED)
Identity Building Block must offer an API to revoke a Virtual Identifier. In that case, the Alias won't be usable anymore for any Identity Building Block services. (REQUIRED)
Identity Building Block must be capable to attach an Alias Identifier to Unique Identifier for referring to a User. The alias will be an existing form of trusted identification of the User in another system. It could be for example an existing identity document number, an email address, a phone, etc. (REQUIRED)
Identity Building Block must offer an API to revoke the link to an Alias. In that case, the Alias won't be usable anymore for any Identity Building Block services. (REQUIRED)
Identity Building Block must offer APIs to update attributes of identities and to attach legal evidence of that identity change approval (often delivered by justice). (REQUIRED)
Identity Building Block must offer an API to request issuance, get status and manage Identity Credentials, following a GovStack recommended Open Standard API. (REQUIRED)
Identity Building Block must offer an API to manage the full life cycle of credentials related to an identity in an issuing system. The related credential must keep a strong and verifiable link with the individual identity and with the issuer. (REQUIRED)
Identity Building Block API must manage Digital Credentials. (REQUIRED)
Identity Building Block API must manage Physical Credentials. (REQUIRED)
Identity Building Block must offer an API allowing to request an identity credential issuance to a third-party credential management system. The information sent will have to be verifiable towards their issuer for auditability purposes, so they will have to be packed into Verifiable Credential format.
Identity Building Block must offer APIs to either push data for credential issuance in an issuance request or to be requested by the issuing system. (REQUIRED)
Identity Building Block must offer an API allowing to issue a similar credential to the one already issued before based on the credential ID number. (REQUIRED)
Identity Building Block must offer an API allowing to revoke an issued ID credential. This will be used, for example, when a document is damaged, stolen or definitely lost. (REQUIRED)
Identity Building Block must offer an API allowing to temporarily suspend and then un-suspend an issued ID credential. This will be used to disable an ID credential which has been lost, its holder suspending the time to search for it. After retrieval, the document should be unsuspended and usable again. If not retrieved after some time, the document should be revoked. (REQUIRED)
Identity Building Block must offer an API allowing to check the suspension status of a document. (REQUIRED)
Identity Building Block must offer an API to request the status of ID credentials. Status being related to their production, their delivery or their activation status. (REQUIRED)
Identity Building Block must offer an API to search for ID credentials using some of its attributes. The output must be restricted to being a document number which can facilitate an access request only. No information can be shared directly. (REQUIRED)
Identity Building Block must offer an API to retrieve a new copy of an ID credential already issued in case the current document has expired. The copy may be received electronically if is digital or delivered physically in case of a physical ID document. (REQUIRED)
Identity Building Block must offer an API to download a newly generated digital ID credential. (REQUIRED)
Identity Building Block must offer an API to share with a 3rd party a Digital ID Credential. (REQUIRED)
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)
Identity Building Block must prevent any unauthorized system or user to get access to data. (REQUIRED)
Identity Building Block must offer identity verification services only to a registered system or users. (REQUIRED)
Identity Building Block must offer the capacity to grant access to specific verification services for specific or all individuals that are data subjects and hence owners of that data. (REQUIRED)
Identity Building Block must respect principles of data security by design in order to maximize protection against hackers: data encryption, data isolation, data separation, data anonymization, data minimization. (REQUIRED)
Identity Building Block must implement security best practices in order to ensure the Identities it manages can be trusted. (REQUIRED)
Identity Building Block must implement a history of change for any identity must be retrievable and auditable by authorized users to investigate suspicious cases. (REQUIRED)
Identity Building Block must offer identity verification services only with preliminary informed consent on personal data usage of the concerned individual. (REQUIRED)
Identity Building Block must not disclose any personal unnecessary information as part of its services API, and when possible prefer Yes/No answer rather than sharing attributes. All Sensitive Personal Information/Personally Identifiable Information must not be written to logs/reporting databases. (REQUIRED)
Capability
Description
Recommended Use
Level of Trust
Requirements for individual or for the Context of Use
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)
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.
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.
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.
The value set here determines the authorization processing flow. To use the Authorization Code Flow, the value should be configured to "code".
Valid OAuth 2.0 Client Identifier in the Authorization Server.
Redirection URI to which the response would be sent. This URI must match one of the redirection URI values during the client ID creation.
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.
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.
ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the end user.
Space delimited case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for re-authentication and consent.
"consent"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.
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.
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.
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.
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.
OK
Loads IDBB UI application in browser for interacting with user for Login process
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"
{ "name#en" : "John Doe", "name#fr" : "Jean Doe", "phone" : "033456743" }
Supported User Info Claims
OK
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.
Endpoint to fetch all the public keys of the IDBB server. Returns public key set in the JWKS format.
OK
The certificate's Key ID
How the Key is used. Valid value: sig
Cryptographic algorithm family for the certificate's Key pair. Valid value: RSA
RSA Key value (exponent) for Key blinding
RSA modulus value
SHA-256 thumbprint of the certificate.
Certificate to validate the Oauth server trust.
Expire datetime of the key. Given in ISO format.
"2026-02-05T13:43:07.979Z"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.
yyyy-MM-dd'T'HH:mm:ss.SSS'Z'This is the same transactionId received from /link-transaction endpoint.
List of permitted scopes by end-user.
List of accepted essential and voluntary claims by end-user.
OK
This is the same transactionId received from /link-transaction endpoint.
Generate link code request is raised from IDBB UI application.
CSRF token as set in cookie key 'XSRF-TOKEN'
TransactionId that associates the current transaction / session with the relying party redirection. IDBB backend application should be able to maintain this association with respective to the transaction Id.
OK
The same transactionId passed as part of the request.
Unique random string mapped to this transactionId.
Expire date time (ISO format) for the generated linkCode. After this date time linkCode in this request is not valid.
The link status endpoint is invoked from IDBB UI application.
CSRF token as set in cookie key 'XSRF-TOKEN'
This is the same transactionId sent in the /link-code request
This is same linkCode returned in the generate-link-code response.
OK
This is the same transactionId as sent in the request.
Link status of the linkCode passed in the request.
Epoch in milliseconds at which the wallet-app acknowledged the link-code.
Link authorization code endpoint is invoked from UI application.
CSRF token as set in cookie key 'XSRF-TOKEN'
This is the same transactionId sent in the /link-code request.
linkCode for which status is already received as LINKED.
OK
Authorization code. Required to obtain the ID token and / or access token from the /token endpoint.
Client's validated redirect URI.
The echoed state value, used to maintain state between the request and the callback
The echoed nonce value, if one was passed with the request. Clients must validate the value before proceeding.
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.
On Authentication Success: Only linkTransactionId is returned in the below response without any errors.
On Authentication Failure: Error list will be returned.
yyyy-MM-dd'T'HH:mm:ss.SSS'Z'This is the same transactionId received from /link-transaction endpoint
User identifier (UIN/VID).
Authentication Challenge.
Defines the type of auth challenge. It should be same as authfactor.type (oauth-details response).
Actual challenge as string.
Format of the challenge provided.
OK
This is the same transactionId received from /link-transaction endpoint.
List of Errors in case of request validation / processing failure in IDBB server.
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 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.
Authorization code grant type.
Authorization code, sent as query param in the client's redirect URI.
Client Id of the OIDC client.
Type of the client assertion part of this request.
Private key signed JWT, This JWT payload structure is defined above as part of request description.
Valid client redirect_uri. Must be same as the one sent in the authorize call.
OK
Identity token in JWT format. Will have the below claims in the payload.
The access token in JWT format. This token will be used to call the UserInfo endpoint. Relying party application should handle access token as opaque.
The type of the access token, set to Bearer
The lifetime of the access token, in seconds.
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.
Link code as received by the wallet-app from the QR code scanning.
OK
Unique link-transaction-id.
Registered name of the OIDC client.
Registered OIDC client Logo URL.
List of requested scopes to be permitted by the end user.
List of client request mandatory claim names.
List of client request optional claim names.
Auth factors defines the authentication modes that can be used to veifiy the user. More than one authFactor may be resolved or combination of auth factors. Precedence of authFactors is based on its order
Name of the authentication method
Applicable for biometric based authentication, number of bio segments to be captured for authentication.
Applicable for biometric based authentication. Can be more specific about which bio segments should be captured.
Wallet binding endpoint is invoked by Wallet's backend server.
Note: Binding entry uniqueness is combination of these 3 values -> (PSUT, public-key, auth-factor-type)
An identifier for the partner.
An API key provided to the partner for authentication purposes.
User Id (UIN/VID).
Auth factor type to be binded for the provided key.
Format of the auth factor type supported in the wallet app.This is not stored, this value is only validated to check if its a supported format in the IDBB implementation.
Defines the type of auth challenge. It should be same as authfactor.type (oauth-details response).
Actual challenge as string.
Format of the challenge provided.
key to be binded in JWK format.
OK
Unique identifier given to public-key and partner specific userId mapping.
Key binder signed certificate.
Expire date time of the signed certificate.
This endpoint is only for facilitating the OIDC provider details in a standard way.
Reference: https://openid.net/specs/openid-connect-discovery-1_0.html
OK
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.
URL of the OAuth 2.0 Authorization Endpoint.
URL of the OAuth 2.0 Token Endpoint.
URL of the OP's UserInfo Endpoint.
URL of the OP's JSON Web Key Set [JWK] document.
URL of Client Registration Endpoint.
JSON array containing a list of the OAuth 2.0 [RFC6749] scope values that this server supports.
JSON array containing a list of the OAuth 2.0 response_type values that this OP supports.
JSON array containing a list of the Authentication Context Class References that IDP supports.
JSON array containing a list of the JWS [JWS] signing algorithms.
JSON array containing a list of the JWE [JWE] encryption algorithms.
JSON array containing a list of the JWE encryption algorithms (enc values) [JWA] supported by the UserInfo Endpoint to encode the Claims in a JWT.
JSON array containing a list of Client Authentication methods supported by this Token Endpoint.
JSON array containing a list of the display parameter values that the OpenID Provider supports.
JSON array containing a list of the Claim Types that the OpenID Provider supports.
JSON array containing a list of the Claim Names of the Claims that the OpenID Provider MAY be able to supply values for.
Languages and scripts supported for values in Claims being returned.
Languages and scripts supported for the user interface.
Mechanism to be used for returning parameters from the Authorization Endpoint.
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.
Client Identifier
"785b806d0e594657b05aabdb30fff8a4"Current date and time when the request is sent
Name of the OIDC client.
"ABC Health Care"Status of OIDC client.
Relying party logo URI which will used to display logo in OIDC login and permissi
Valid list of callback Uris of the relying party. When OIDC authorize API is called, any one Uri from this list should be sent as redirect_uri. authorization_code will be redirected to this Uri on successful authentication.
Allowed user info claims, that can be requested by OIDC client in the authorize API
The Authentication Context Class Reference is case-sensitive string specifying a list of Authentication Context Class values that identifies the Authentication Context Class. Values that the authentication performed satisfied implying a Level Of Assurance.
Form of Authorization Grant presented to token endpoint.
Auth method supported for token endpoint. At present only "private_key_jwt" is supported.
OK
Date and time when the response is generated
OIDC client identifier.
List of Errors in case of request validation / processing failure in IDBB server. When request processing is fully successful, this array will be empty.
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".
Current date and time when the request is sent
Unique OIDC client id (Case-Sensitive). If duplicates found, request will be rejected.
"785b806d0e594657b05aabdb30fff8a4"Name of OIDC client.
"ABC Health Care"Relying Party ID of the client. This will be passed on to authentications servers when KYC is fetched.
Note: Use the client Id as relyingPartyId if there is no separate concept of relying party in the ID authentication system.
"bharathi-inc"Relying party logo URI which will used to display logo in OIDC login and permission pages.
Valid list of callback Uris of the relying party. When OIDC authorize API is called, any one Uri from this list should be sent as redirect_uri. authorization_code will be redirected to this Uri on successful authentication.
The Authentication Context Class Reference is case-sensitive string specifying a list of Authentication Context Class values that identifies the Authentication Context Class. Values that the authentication performed satisfied implying a Level Of Assurance.
OIDC client's public key used to verify the client's private_key_jwt when OIDC token endpoint is invoked. This field will not be allowed to udpate later, if the private key is compromised, then new OIDC client to be created. Format : Json Web Key (JWK).
Allowed user info claims, that can be requested by OIDC client in the authorize API
Form of Authorization Grant presented to token endpoint
Auth method supported for token endpoint. At present only "private_key_jwt" is supported.
OK
Date and time when the response is generated
Client id as provided in the request.