Introduction to Mojaloop Connection Manager

Setting up Public Key Infrastructure (PKI) for a new Mojaloop environment and subsequently onboarding Digital Financial Service Providers (DFSPs) involves a number of steps around the generation, signing, and sharing of certificates, as well as identifying the various endpoints required to establish connections. DFSPs and the Hub communicate over TLSv1.2 with mutually authenticated X.509 certificates, which are signed by a trusted Certificate Authority (CA). The use of digital certificates is necessary to verify the identity of the parties exchanging data with each other and ensure secure communications. In addition to TLS client and server certificates, all DFSPs and the Hub itself must have a JSON Web Signature (JWS) certificate, which they then share among themselves.

Previous experience shows that the certificate management process is prone to human errors. To reduce the probability of mistakes and miscommunication, a connectivity management tool, Mojaloop Connection Manager (MCM), has been developed, which allows the Hub Operator to exchange endpoint data and certificates with DFSPs through an easy-to-use portal.

The following diagram provides an illustration of how information gets exchanged between Payment Manager (its component called MCM Client) and the MCM portal (which pulls data from the MCM Server).

payment manager architecture mcm
Figure 1. Data exchange between Payment Manager and MCM

MCM has functionality to support the following steps of endpoint mapping and certificate management for the Hub Operator.

Table 1. Certificate and endpoint management supported by MCM
Step Where to read more

The Hub provides endpoint information to DFSPs:

  • IP addresses from which the Hub will initiate connections to DFSPs

  • Hub URLs / IP addresses that DFSPs will initiate connections to

Configuring Hub outbound and inbound endpoints

The Hub collects outbound / inbound endpoint information from DFSPs to update firewalls and configure the backend:

  • IP addresses from which the DFSP will initiate connections to the Hub

  • DFSP callback URLs / IP addresses that the Hub will initiate connections to

Processing DFSPs' outbound and inbound endpoints

The Hub sets up a Certificate Authority to sign TLS client and server certificates, and to create Hub client CSRs (to send to DFSPs).

Setting up a Hub Certificate Authority (CA)

The Hub obtains DFSPs' CA root certificates for importing into the Hub trust store.

Retrieving the certificates of a DFSP’s CA

The Hub creates a CSR for its TLS client certificate and sends it to the DFSPs for signing.

Creating a Hub certificate signing request

The Hub retrieves the TLS client certificate signed by the DFSP’s CA.

Retrieving the Hub’s TLS client certificate CSR signed by a DFSP

The Hub signs and returns the DFSP’s TLS client certificate together with the Hub CA root certificate for installation by the DFSP.

Signing a DFSP’s TLS client certificate CSR

The Hub generates a TLS server certificate for installation in the firewalls.

Uploading the Hub’s TLS server certificate chain

The Hub retrieves the root and intermediate certificates of the DFSP’s CA that signed the DFSP TLS server certificate. These need to be installed in the outbound API gateway.

Retrieving a DFSP’s TLS server certificate chain

The Hub sets up a JWS certificate for installation in WSO2 and for sharing with DFSPs.

Uploading a Hub JWS certificate

The next sections of this document describe how to use MCM to complete the steps outlined above.

Browser support

Currently, the recommended browser is Google Chrome. Using MCM in Mozilla Firefox has some known issues.