Skip to content

Open Banking Configuration

Jump to bottom
HemantKMehta edited this page May 16, 2022 · 33 revisions

Janssen supports Open banking use cases:

  • Dynamic Client Registration
  • Payment Authorization
  • Identity - eKYC
  • Client Initiated Authentication (mobile / out-of-band)

Its best to use the cloud native deployment for open banking so you can take advantage of auto-scaling, high availability, and operational automation. However, for development and testing we also support its VM distribution.

The subsequent parts of this section cover details on its installation, configuration and settings related to the registering an OpenID client,Pushed authorization requests (PAR), JWT Secured Authorization Response Mode (JARM) and MTLS.

Installation: VM Distribution

This section covers details on setting-up the Openbanking use-case in a Janssen VM. We recommend the Cloud Native Distribution for production environment. However, for development and testing VM distribution will be easier. It can be installed on any of the main Linux distributions.

VM Preparation

Prepare a Linux VM with the following minimum specs (recommended):

  • 4 GB RAM
  • 2 GB swap space
  • 2 CPU units
  • 50 GB disk space

Preferably, the VM must have a static IP address and a resolvable host name. A fully qualified domain name (FQDN) is required for production deployments.

Installation

Download the installer (install.py)

wget https://raw.githubusercontent.com/JanssenProject/jans/main/jans-linux-setup/jans_setup/install.py

Execute the installer:

sudo python3 install.py --profile openbanking

The installation script will install required tools, programs, packages and then it will prompt the user for setup instructions. Answer the following questions:

Certificate Generation Setup

Prompt Description
Enter IP Address The IP address for the VM. Use an IP address assigned to one of this server's network interfaces (usage of addresses assigned to loopback interfaces is not supported)
Enter Hostname The hostname for the VM. Recommended to be a FQDN
Enter your city or locality Used to generate X.509 certificates.
Enter your state or province two letter code Used to generate X.509 certificates.
Enter two letter Country Code Used to generate X.509 certificates.
Enter Organization Name Used to generate X.509 certificates.
Enter email address for support at your organization Used to generate X.509 certificates.

Architecture Setup

Prompt Description
Enter maximum RAM for applications in MB Maximum RAM Size in MB
RDBM Type Backend type. Currently only MySQL is supported
Use remote RDBM Select if connecting to an external MySQL server
Enter Openbanking static kid The fallback key when key is not passed in requests (as required by Openbanking)
Use external key If yes, link to an external Open Banking key file

Before the last question installer process will display the selected choices and confirms to proceed. as

Prompt Description
Proceed with these values [Y/n] Confirmation before setting up the services.

Uninstalling Janssen Server

Execute the installation script with the -uninstall argument.

MTLS Configuration

For MTLS, OBIE-issued (for openbanking UK) certificates and keys should be used. The following discussion assumes that the file ca.crt has a CA certificate and ca.key has a CA private key. Following command generates self-signed ca.crt and ca.key:

openssl req -newkey rsa:2048 -nodes -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.crt

The following set of commands is an example of how to create the server’s private key (server.key), Certificate Signing Request (CSR) (server.csr) and certificate (server.crt):

openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -set_serial 100 -days 365 -outform PEM -out server.crt

Now, store the server key (server.key) and certificate (server.crt) file in some location (preferably inside /etc/certs) and set its path in the Apache .conf file (/etc/apache2/sites-enabled/https_jans.conf) with SSLCertificateFile and SSLCertificateKeyFile directives:

SSLCertificateFile /etc/certs/bank/server.crt
SSLCertificateKeyFile /etc/certs/bank/server.key

The path of CA certificate file should be set to SSLCACertificateFile directive as:

SSLCACertificateFile /etc/apache2/certs/matls.pem

The following commands will create client’s private key (client.key), CSR (client.csr) and certificate (client.crt):

openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -set_serial 101 -days 365 -outform PEM -out client.crt

The following command will create a client certification chain (private key, public certificate and ca certificate) into the file client.pem:

cat client.key client.crt ca.crt >client.pem

Use this pem file to create JWKs for the clients (if required). To create a JWK, you can use a free utility published at [https://mkjwk.org]11111(https://mkjwk.org). Or you can download the command-line tool from GitHub. There are numerous other online PEM-to-JWKS tools available like JWKConvertFunctions. We may need to add/update some data in these generated JWKs.

!!!Note It is important to give different values of the Common Name field (“Common Name (e.g. server FQDN or YOUR name) []”) for the CA, Server and clients. Other fields may have common values but the same values for Common Name of all certificates results in certificate verification failed at runtime.

Importing the CA certificate in JVM truststore and signing, encryption keys into auth-Server keystore:

The command line utility keytool is installed with JDK, it can be used to import the CA certificate in JVM truststore (/opt/jre/lib/security/cacerts) and signing,encryption keys into the jans-auth server’s keystore(/etc/certs/jans-auth-keys.jks).

./keytool -importcert -file /path/to/file/filename.cer -keystore /etc/certs/jans-auth-keys.jks -alias yourkeystore

./keytool -importkeystore -srckeystore /path/to/file/filename.jks -srcstoretype JKS -destkeystore /opt/jre/lib/security/cacerts -deststoretype JKS

Accessing the Platform

After successful installation, we have following two methods to access the Open Banking Platform, as discussed in the subsequent text:

  1. jans-cli (recommended) or
  2. curl

Janssen Command Line Interface (jans-cli)

Jans-cli is a command line interface to configure the Janssen software and it supports both interactive and command-line options for configuration.

Jans-cli calls the Jans Config API to perform various operations related to attributes, scopes, authentication method, cache, custom scripts, database, OpenId connect clients, user management, etc. During Janssen installation, the installer creates a client to use Jans Config API. Jans-cli uses this client to call Jans Config API.

OpenID Connect Client Configuration

This section will cover both interractive and commandline option to create a client.

  1. Get List of OpenID Clients (all/ limited)

  2. Creating a New OpenID Clients

    • Print details of available commands for OpenID Connect Client Configuration:

      /opt/jans/jans-cli/config-cli.py --info OAuthOpenIDConnectClients

Operation ID: get-oauth-openid-clients
   Description: Gets list of OpenID Connect clients
   Parameters:
   limit: Search size - max size of the results to return. [integer]
   pattern: Search pattern. [string]
Operation ID: post-oauth-openid-clients
   Description: Create new OpenId connect client
   Schema: /components/schemas/Client
Operation ID: put-oauth-openid-clients
   Description: Update OpenId Connect client.
   Schema: /components/schemas/Client
Operation ID: get-oauth-openid-clients-by-inum
   Description: Get OpenId Connect Client by Inum.
   url-suffix: inum
Operation ID: delete-oauth-openid-clients-by-inum
   Description: Delete OpenId Connect client.
   url-suffix: inum
Operation ID: patch-oauth-openid-clients-by-inum
   Description: Update modified properties of OpenId Connect client by Inum.
   url-suffix: inum
   Schema: Array of /components/schemas/PatchRequest

    • Get the client schema: The following command will display a client schema as a JSON with all the properties of a client. It is not important to fill all details for each of the client. The output of this command should be saved for later use to create the client by filling desired details (say its name is newclient.json). This updated schema file(newclient.json) will be input to the next command to create the client.

           /opt/jans/jans-cli/config-cli.py --schema /components/schemas/Client

    • Create Client by runing post-oauth-openid-clients operation: The following command creates the client using the input from the schema file filled with desired details about the client. The following command requires to complete the authentication and authorization flow, it also gives the instruction on how to complete it.

           /opt/jans/jans-cli/config-cli.py --operation-id post-oauth-openid-clients --data /path/of/schema/file/newclient.json
Clone this wiki locally