Cloud-Native

System Requirements

Use the listing below for a detailed estimation of the minimum required resources. The table contains the default resources recommendation per service. Depending on the use of each service the resources need may increase or decrease.

Service	CPU Unit	RAM	Processor Type	Required
Auth server	2.5	2.5GB	64 Bit	Yes
config - job	0.3	0.3GB	64 Bit	Yes on fresh installs
persistence - job	0.3	0.3GB	64 Bit	Yes on fresh installs
auth-server-key-rotation - job	0.3	0.3GB	64 Bit	No [Strongly recommended]
cleanup - job	0.3	0.3GB	64 Bit	No [Strongly recommended]
nginx	1	1GB	64 Bit	No
config-api	1	1.2GB	64 Bit	No

Installation

Install using Helm(production-ready)

• To complete this installation in a production environment, you must obtain official Open Banking certificates. This requires generating private keys locally and submitting a Certificate Signing Request (CSR) to your Open Banking Directory (e.g., OBIE) to receive the corresponding signed certificates. Self-signed certificates should only be used for testing. Ensure you have the following files ready:

  Certificate / key	Description
  OB Root CA	Used in nginx as a certificate authority
  OB Issuing CA	Used in nginx as a certificate authority
  OB Signing CA	Used in nginx as a certificate authority
  OB AS Transport key obtransport.key	Used for mTLS. This will also be added to the JVM
  OB AS Transport crt obtransport.pem	Used for mTLS. This will also be added to the JVM
  OB transport truststore ob-transport-truststore.p12	Used in SSA Validation. Generated from OB Root CA and Issuing CA
  OB AS signing crt obsigning.pem	Added to the JVM. Used in SSA Validation
  OB AS signing key obsigning.key	Added to the JVM. Used in SSA Validation

• Download the Open Banking values file openbanking-values.yaml:

  wget https://raw.githubusercontent.com/GluuFederation/flex/main/charts/gluu/openbanking-values.yaml
  

• Based on the provider/platform you're using, you can follow the docs to install your platform prerequisites, nginx-ingress, and the yaml changes needed in openbanking-values.yaml based on the Gluu persistence choosed.

• The auth-server and persistence images are hosted in a private repository and require authentication to pull:

  • Create a Kubernetes secret in the gluu namespace using your provided registry credentials:

    kubectl create secret docker-registry -n gluu regcred --docker-server=https://index.docker.io/v1/ --docker-username=<some-username> --docker-password=<some-password>
    

  • Update openbanking-values.yaml:

    auth-server:
        image:
            pullSecrets:
            - name: regcred
    persistence:
        image:
            pullSecrets:
            - name: regcred
    

• To enable mTLS in ingress-nginx, add the following to your openbanking-values.yaml:

  nginx-ingress:
    ingress:
        additionalAnnotations:
            nginx.ingress.kubernetes.io/auth-tls-verify-client: "optional"
            nginx.ingress.kubernetes.io/auth-tls-secret: "gluu/tls-ob-ca-certificates"
            nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
            nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
  

  Adding these annotations will enable client certificate authentication.

• Enable authServerProtectedToken and authServerProtectedRegister:

  global:
    auth-server:
      ingress:
        # -- Enable mTLS on Auth server endpoint /jans-auth/restv1/token.
        authServerProtectedToken: true
        # -- Enable mTLS on Auth server endpoint /jans-auth/restv1/register.
        authServerProtectedRegister: true
  

• Enable HTTPS

  During fresh installation, the config-job checks if SSL certificates and keys are mounted as files. If no mounted files are found, it attempts to download SSL certificates from the FQDN supplied. If the download is successful, an empty key file is generated. If no mounted or downloaded files are found, it generates self-signed SSL certificates, CA certificates, and keys.

  certificates and keys of interest in https	Notes
  web_https.crt	(nginx) web server certificate. This is commonly referred to as server.crt
  web_https.key	(nginx) web server key. This is commonly referred to as server.key
  web_https.csr	(nginx) web server certificate signing request. This is commonly referred to as server.csr
  web_https_ca.crt	Certificate authority certificate that signed/signs the web server certificate.
  web_https_ca.key	Certificate authority key that signed/signs the web server certificate.

• Create a secret containing the OB CA certificates (issuing, root, and signing CAs) and the OB AS transport crt. For more information read here.

  cat web_https_ca.crt issuingca.crt rootca.crt signingca.crt >> ca.crt
  kubectl create secret generic tls-ob-ca-certificates -n gluu --from-file=tls.crt=web_https.crt --from-file=tls.key=web_https.key --from-file=ca.crt=ca.crt
  

  If you have an existing helm deployment, those secrets can be retrieved and then create using the following commands:

  kubectl get secret cn -n gluu --template={{.data.ssl_ca_cert}} | base64 -d > ca.crt
  kubectl get secret cn -n gluu --template={{.data.ssl_cert}} | base64 -d > server.crt
  kubectl get secret cn -n gluu --template={{.data.ssl_key}} | base64 -d > server.key
  
  kubectl create secret generic tls-ob-ca-certificates -n gluu --from-file=tls.crt=server.crt --from-file=tls.key=server.key --from-file=ca.crt=ca.crt
  

• Inject OBIE certificates, keys and URI:

  1. base64 encode all .pem and .key files.

     cat obsigning.pem | base64 | tr -d '\n' > obsigningbase64.pem
     cat obsigning.key | base64 | tr -d '\n' > obsigningbase64.key
     cat obtransport.pem | base64 | tr -d '\n' > obtransportbase64.pem
     cat obtransport.key | base64 | tr -d '\n' > obtransportbase64.key
     

  2. Generate your transport truststore or convert it to .p12 format. Please name it as ob-transport-truststore.p12

     cat obissuingca.pem obrootca.pem obsigningca.pem > transport-truststore.crt
     keytool -importcert -file transport-truststore.crt -keystore ob-transport-truststore.p12 -alias obkeystore
     

  3. base64 encode the ob-transport-truststore.p12

     cat ob-transport-truststore.p12 | base64 | tr -d '\n' > obtransporttruststorebase64.pem
     

  4. Configure your Signing Key IDs: You must define both the external identifier for your signing key and its internal Java Keystore label. To ensure the system correctly maps the outgoing signature to the internal private key, these two values must be identical:

     • cnObStaticSigningKeyKid (External ID): This is the unique Key ID (kid) provided by your Open Banking Directory (e.g., XkwIzWy44xWSlcWnMiEc8iq9s2G). Gluu stamps this ID onto the header of outgoing JWTs so receiving parties know which public key to fetch from your JWKS URI. This exact kid must exist at your published JWKS endpoint.

     • cnObInternalSigningAlias (Internal Label): This is the internal label ("alias") used by the Authorization Server to locate your private key inside its local Java Keystore (.jks). Set this to match your kid value exactly(cnObStaticSigningKeyKid).

  5. Add those values to openbanking-values.yaml:

       global:
         # -- Open banking external signing jwks uri. Used in SSA Validation.
         cnObExtSigningJwksUri: "https://mykeystore.openbanking.wow/xxxxx/xxxxx.jwks"
         # -- Open banking external signing jwks AS certificate authority string. Used in SSA Validation. This must be encoded using base64. Used when `.global.cnObExtSigningJwksUri` is set.
         cnObExtSigningJwksCrt: <base64 string in obsigningbase64.pem>
         # -- Open banking external signing jwks AS key string. Used in SSA Validation. This must be encoded using base64. Used when `.global.cnObExtSigningJwksUri` is set.
         cnObExtSigningJwksKey: <base64 string in obsigningbase64.key>
         # -- Open banking external signing jwks AS key passphrase to unlock provided key. This must be encoded using base64. Used when `.global.cnObExtSigningJwksUri` is set.
         cnObExtSigningJwksKeyPassPhrase: <base64 string passphrase of obsigningbase64.key>
         # -- External Key ID (kid) stamped onto the header of outgoing JWTs. This tells receiving parties which public key to fetch from your JWKS URI to verify the signature.
         cnObStaticSigningKeyKid: "XkwIzWy44xWSlcWnMiEc8iq9s2G"        
         # -- Internal Java Keystore (JKS) alias used to locate the Open Banking private signing key. To ensure correct internal mapping, this string must identically match your `cnObStaticSigningKeyKid`.
         cnObInternalSigningAlias: "XkwIzWy44xWSlcWnMiEc8iq9s2G"
         # -- Open banking AS transport crt. Used in SSA Validation. This must be encoded using base64.
         cnObTransportCrt: <base64 string in obtransportbase64.pem>
         # -- Open banking AS transport key. Used in SSA Validation. This must be encoded using base64.
         cnObTransportKey: <base64 string in obtransportbase64.key>
         # -- Open banking AS transport key passphrase to unlock AS transport key. This must be encoded using base64.
         cnObTransportKeyPassPhrase: <base64 string passphrase in obtransportbase64.key>
         # -- Open banking transport Alias used inside the JVM.
         cnObTransportAlias: ""
         # -- Open banking AS transport truststore crt. This is normally generated from the OB issuing CA, OB Root CA and Signing CA. Used when .global.cnObExtSigningJwksUri is set. Used in SSA Validation. This must be encoded using base64.
         cnObTransportTrustStore: <base64 string in obtransporttruststorebase64.pem>
     

• Please note that the password for the keystores created can be fetched by executing the following command:

  kubectl get secret cn -n gluu --template={{.data.auth_openid_jks_pass}} | base64 -d

  The above password is needed in custom scripts such as the Client Registration script

• After finishing all the tweaks to the openbanking-values.yaml file, run helm install or helm upgrade if Gluu is already installed

  helm repo add gluu-flex https://docs.gluu.org/charts
  helm repo update
  helm install gluu gluu-flex/gluu -n gluu -f openbanking-values.yaml
  

Testing the setup

After successful installation, you can access and test the Gluu Open Banking Platform using either curl or Jans-CLI.

Changing the signing key kid for the AS dynamically

1. Get a client id and its associated password. We will use the jans-config-api client id and secret:

   TESTCLIENT=$(kubectl get cm cn -n gluu --template={{.data.jca_client_id}})
   TESTCLIENTSECRET=$(kubectl get secret cn -n gluu --template={{.data.jca_client_pw}} | base64 -d)
   

2. Get a token. To pass the mTLS network boundary, you must use your Open Banking transport certificates (replace obtransport.pem and obtransport.key with your actual filenames):

   TOKEN=$(curl -s -k -u $TESTCLIENT:$TESTCLIENTSECRET https://demoexample.gluu.org/jans-auth/restv1/token -d "grant_type=client_credentials&scope=https://jans.io/oauth/jans-auth-server/config/properties.write" --cert obtransport.pem --key obtransport.key | grep -o '"access_token":"[^"]*' | cut -d'"' -f4)
   
   echo "My Token is: $TOKEN"
   

3. Add the entry staticKid to force the AS to use a specific signing key. Please modify XhCYDfFM7UFXHfykNaLk1aLCnZM to the kid to be used:

   curl -k -X PATCH "https://demoexample.gluu.org/jans-config-api/api/v1/jans-auth-server/config" \
   -H "accept: application/json" \
   -H "Content-Type: application/json-patch+json" \
   -H "Authorization: Bearer $TOKEN" \
   -d '[{"op":"add","path":"/staticKid","value":"XhCYDfFM7UFXHfykNaLk1aLCnZM"}]'
   

4. Perform a rolling restart for the auth-server and config-api deployments.

   kubectl rollout restart deployment gluu-auth-server -n gluu
   kubectl rollout restart deployment gluu-config-api -n gluu
   

Adding custom scopes upon installation

1. Download the original scopes file

   wget https://raw.githubusercontent.com/JanssenProject/docker-jans-persistence-loader/master/templates/scopes.ob.ldif
   

2. Add to the file the custom scopes desired.

3. Create a configmap with the scopes file

   kubectl create cm custom-scopes -n gluu --from-file=scopes.ob.ldif
   

4. Mount the configmap in your openbanking-values.yaml under persistence.volumes and persistence.volumeMounts

   persistence:
       volumes:
           - name: custom-scopes
               configMap:
                   name: custom-scopes
       volumeMounts:
           - name: custom-scopes
             mountPath: "/app/templates/scopes.ob.ldif"
             subPath: scopes.ob.ldif
   

5. Run helm install or helm upgrade if Gluu has already been installed.