/
Integrating MOSIP with External Credential Partners

Integrating MOSIP with External Credential Partners

Owned by Abdul Bathish
Mar 20, 2025
6 min read

Introduction

This document provides a detailed technical understanding of the architecture and design of integrating MOSIP with external credential partners. Following is the high-level architecture that has the required building blocks for the intended solution.

 

  • MOSIP Server: The registration or updates are sent to the MOSIP server for processing. The MOSIP server after successfully processing the registration data generates a Unique Identification Number (UIN) which is unique to every resident of a country. All the components that are responsible for generating and sharing credentials reside inside the MOSIP server.

  • Credential Stage: A component of MOSIP inside the MOSIP server. It is responsible for generating a credential and sharing it with the Partner system.

  • Partner System: An external solution onboarded as a 'credential partner' by MOSIP using MOSIP's partner management framework. It securely consumes the credential from the MOSIP server through a standard interface and uses the data inside the credential for its specific use case. Depending on the partner type, the partner system may offer various services such as:

    • Printing physical ID cards

    • Generating digital credentials

    • Creating PDFs and emailing to registered addresses

    • Generating QR codes for various authentication purposes

    • Managing the distribution of credentials to designated residents

    • Integrating with CRVS systems

  • WebSub: WebSub is a websocket used by MOSIP for sharing data with MOSIP partners. MOSIP’s print stage shares the credential with the partner printing system through WebSub. The credentials shared are in the form of Verifiable Credentials (VCs). For more details, please refer to WebSub | MOSIP Docs 1.2.0.

Technical Architecture

The below diagram depicts the technical architecture of the solution. (Here we have highlighted how external print partner can be integrated to MOSIP system)

 

  • Print Stage : Is a stage on the MOSIP server that requests the credential request generator to generate a credential for a given print partner or partners based on a custom-built logic. For example, the custom logic may be to route the print request to a a specific regional print partner.

  • Credential Request Generator : This is a component on the MOSIP server. It stores the credential request in the Credential transaction Database to be consumed by the credential service.

  • Credential Service : This is a component on the MOSIP server. It is responsible for generating a credential. The credential service does the following

  1. It constructs the credential based on the partner policy (that defines the type of the credential and the data that must be shared as part of the credential) and stores the credential into the datashare.

  2. The datashare returns the URL which is published by the credential service inside WebSub event hub as a message against a partner topic.

  3. WebSub picks up the event from the event hub and shares it with the Partner Print System through a callback mechanism via a standard REST interface.

  4. The partner print system retrieves the datashare URL from the event and downloads the credential from the datashare and returns the status back to WebSub. The following statuses may be returned

    1. RECEIVED: Indicates that the credential request has been received

    2. DOWNLOADED : Indicates that the credential has been downloaded

    3. VALIDATED : indicates that the credential has been validated

    4. PRINTED : indicates that the credential has been printed

    5. ERROR : an error occurred while processing the credential

Credential Type : Verifiable Credentials, see Verifiable Credentials Data Model v1.1

Print Partner System : The partner print system has to be amended with the functionality to receive the credential from MOSIP and interpret it. The following are key sequence of operations

  1. Receive the datashare URL of the credential from WebSub

  2. Download the credential from the datashare URL

  3. Decrypt the credential using the private key

  4. Validate the credential

  5. Parse and extract the demographic and biometric data (eg:- photo)

  6. Print the ID card

Note : The way the credential is processed and interpreted is left to the implementation of the partner printing system and is outside the scope of MOSIP.

The partner printing system is expected to expose an API end point for MOSIP to publish the datashare URL of the credential.

Print Service (Partner Printing System)

For MOSIP to communicate with the partner printing system, the partner printing system is expected to implement a print service.

Note: The print service may be considered as an extension to the functionality of the partner printing system. It may also be implemented as a separate microservice and linked to the partner printing system. The technology, architecture and language of the print service implementation is outside the scope of MOSIP.

For implementing the print service, follow the below procedure.

  • The print service will be called/invoked only by WebSub(Subscription engine) with credential request event using registered callback URL.
    Sample callback url:

    • https://{PrintProviderName}-printservice.print/v1/print/callback/notifyPrint

  • Sample credential request:

    • { "publisher": "CREDENTIAL_SERVICE", "topic": "{mosip.partner.id}/CREDENTIAL_ISSUED", "publishedOn": "2023-05-04T13:21:01.565Z", "event": { "id": "324190df-3071-429a-9eec-182008c7b123", "transactionId": "37238d20-3dcd-4aa3-851b-6240956fb432", "type": { "namespace": "mosip", "name": "mosip" }, "timestamp": "2023-05-04T13:21:01.565Z", "dataShareUri": "http://datashare.datashare/v1/datashare/get/mpolicy-default-euin/mpartner-default-print/mpartner-default-printmpolicy-default-euin20230504132101mDBLJnCc", "data": { "registrationId": "10013100370000520230504123911", "ExpiryTimestamp": "9999-12-31T23:59:59.100", "TransactionLimit": null, "proof": { "signature": "eyJ4NWMiOlsiTUlJRHRUQ0NBcDJnQXdJQkFnSUlFTDN2UzV5VHVGRXdEUVlKS29aSWh2Y05BUUVMQlFBd2NERUxNQWtHQTFVRUJoTUNTVTR4Q3pBS_yPau0n049iZ81r0QV1MrKppldeGyklbH8jAdtIvoVI6COkW6QSzeimHI9EB1L9g" }, "credentialType": "vercred", "protectionKey": "959920" } } }

  • Once the request is received by the print service, it immediately sends back the CredentialStatusEvent "RECEIVED" to WebSub indicating that it has received the credential URL.

Sample status update request:

{ "publisher": "PRINT_SERVICE", "topic": "CREDENTIAL_STATUS_UPDATE", "publishedOn": "2023-03-30T06:51:48.177Z", "event": { "id": "1389e511-914e-4696-b1db-6ce8723d7212", "requestId": "8b388343-ab91-4ade-b68f-5f248060f0bd", "timestamp": "2023-03-30 06:51:48.177843", "status": "RECEIVED", "url": "" } }

  • Download the encrypted credential using the dataShareURL

  • Upon successfully downloading the credential, publish the CredentialStatusEvent as "DOWNLOADED" to WebSub to update the status.

  • Decrypt the credential using partner printing system’s private key.
    Sample Decrypted Response: Please refer the Verifiable Credential section below.

  • Validate the credential using the credential’s JWS signature inside the credential proof section

  • Publish the CredentialStatusEvent "VALIDATED" to WebSub to update the status.

  • Consume the validated credential and process it for further printing. The processing of the credential is left to the implementation of the partner printing system. For example, the partner printing system may parse & format the credential and store it in a database or a Message Queue as per the design and implementation of the partner printing system.

  • After successfully printing, publish the CredentialStatusEvent "PRINTED" to WebSub to update the status.

  • { "publisher": "PRINT_SERVICE", "topic": "CREDENTIAL_STATUS_UPDATE", "publishedOn": "2023-03-30T06:51:48.177Z", "event": { "id": "1389e511-914e-4696-b1db-6ce8723d7212", "requestId": "8b388343-ab91-4ade-b68f-5f248060f0bd", "timestamp": "2023-03-30 06:51:48.177843", "status": "PRINTED", "url": "https://api-internal.mosip.net/v1/datashare/get/mpolicy-default-resident/mpartner-default-resident/{mosip.datashare.partner.id}mpolicy-default-resident20230324065147HVeiufGl" } }

     

  • If any error during the above process, publish the CredentialStatusEvent "ERROR" to WebSub to update the status. A sample response for error would be

    • { "publisher": "PRINT_SERVICE", "topic": "CREDENTIAL_STATUS_UPDATE", "publishedOn": "2023-03-30T06:51:48.177Z", "event": { "id": "1389e511-914e-4696-b1db-6ce8723d7212", "requestId": "8b388343-ab91-4ade-b68f-5f248060f0bd", "timestamp": "2023-03-30 06:51:48.177843", "status": "ERROR", "url": "" } }

      Note : The “ERROR” status and the message next to it.

    • The following are standard error messages that should be returned to MOSIP

      • “Unable to decrypt credential data”

      • “Unable to download credential”

      • “Unable to validate credential”

      • “Error receiving credential event”

      • “Unable to print”

Guidelines and Assumptions

  1. The credential processing service within the partner system has to be implemented by the vendor. The MOSIP team can work with the vendor during the implementation and testing stage of the integration process.

  2. MOSIP can interface with any partner system irrespective of its implementation technology.

  3. MOSIP integrates with external partners using the MOSIP Partner Management System, through which credential partners are onboarded.

  4. The format and design of the credential output (ID card, digital credential, etc.) is left to the implementation of the partner.

  5. The country/organization has to decide the procedure to secure and/or cleanup the data stored at the location of the partner after the credential processing is complete.

Reference Implementation

To help partners better understand the integration process, MOSIP provides reference implementation that demonstrate how to integrate with the MOSIP system:

  1. Print Partner Reference Implementation: