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.

#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: bash 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>

    Copy

  • Update openbanking-values.yaml:

    auth-server:
        image:
            repository: gluufederation/openbanking-auth-server
            pullSecrets:
            - name: regcred
    persistence:
        image:
            repository: gluufederation/openbanking-persistence-loader
            pullSecrets:
            - name: regcred

    Copy

• 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"

  Copy

  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

  Copy

• 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.

```bash
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:

```bash
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 > web_https.crt
kubectl get secret cn -n gluu --template={{.data.ssl_key}} | base64 -d > web_https.key

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
```

1. 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

      Copy

   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

      Copy

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

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

      Copy

   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>

   Copy

• 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

• Install after finishing all the tweaks to the openbanking-values.yaml file:

```bash
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)

   Copy

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"

   Copy

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"}]'

   Copy

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

   Copy

#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

   Copy

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

   Copy

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

   Copy

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