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 GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.
The tests for the Identity Building Block can be found in this GitHub repository.
The microservice interfaces are defined as per OPENAPI Ver3.0 standards.
For implementation purposes, it is suggested to refer TMF630_REST_API_Design_Guidelines.
The Identity usage APIs are a set of OpenAPI specifications exposed by the Identity Building Block to other building blocks and applications for user verification.
The Identity usage APIs are based on the following principles:
Verification APIs are inspired from OpenID Connect protocol which simplifies integrations using pre-existing libraries
Only secure options in OpenID connect should be supported to ensure the user data is handled securely
All biometric capture for user verification should be done using Secure Biometrics Interface standards
For Identity Building Block implementations that support mobile wallet integration, the following API spec should also be implemented.
Detailed API schemas written in YAML that define REST API endpoints for each of the services mentioned above are available on GitHub located at the Identity-Provider YAML.
The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here.
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 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.