Skip to content

Configuration Instructions

Generate/install keys and certs for Gluu Open Banking Identity Platform#

This section covers details about setting up the keys and certificates in both VM and Cloud-Native distribution.

Remember, MTLS is needed not only for the TPPs to call the authorization and token endpoints for OpenID Connect flows, but also by clients that are calling the configuration API.

Add/Update Custom Scripts:#

To add or update custom scripts, you can use either jans-cli or curl.

  • jans-cli in interactive mode, option 13 enables you manage custom scripts. For more info, see the docs.

  • jans-cli in command line argument mode is more conducive to scripting and automation. To display the available operations for custom scripts, use config-cli.py --info CustomScripts. See the docs for more info.

  • To use curl see these docs

Note: you can normally find jans-cli.py in the /opt/jans/jans-cli/ folder.

New Custom Scripts:#

This section presents details about useful interception scripts for an OBIE deployment. The scripts are accessible [here] (https://github.com/JanssenProject/jans-setup/tree/openbank/static/extension). Please setup jans-cli prior to continuing.

Client Registration Script:#

The properties required for this script are defined in a json file that follows the custom script schema as discussed here. Download the script, JSON and keep them in a folder.

From this folder, run the following command:

./jans-cli/config-cli.py --host <FQDN> --client-id $TESTCLIENT --client_secret $TESTCLIENTSECRET --operation-id post-config-scripts --data /clientregistration.json \
-cert-file yourcertfile.pem -key-file yourkey.key

Note: You will need keys and certificates to call the config-api using mutually authenticated TLS.

  1. This script uses jose4j library for JavaScript object signing and encryption.
  1. Download the jose4j-0.7.7.jar

  2. Create a ConfigMap containing the jar.

    kubectl create cm jose4j -n <gluu-namespace> --from-file=jose4j-0.7.7.jar
    
  3. Add the volume and volume mount to auth-server in your override.yaml helm configuration.

     volumes:
       - name: jose4j
         configMap:
           name: jose4j
     volumeMounts:
       - name: jose4j
         mountPath: "/opt/jans/jetty/jans-auth/custom/libs/jose4j-0.7.7.jar"
         subPath: jose4j-0.7.7.jar
    
  4. Run helm upgrade.

    helm upgrade gluu gluu/gluu -n <gluu-namespace> --version=5.0.0 -f override.yaml
    
  1. Download the jose4j-0.7.7.jar and Place in /opt/jans/jetty/jans-auth/custom/libs/

  2. Change your current working directory to /opt/jans/jetty/jans-auth/webapps and edit jans-auth.xml to add this line:

    <Set name="extraClasspath">/opt/jans/jetty/jans-auth/custom/libs/jose4j-0.7.7.jar</Set>
    

  3. Restart the Auth Server, systemctl restart jans-auth

Person Authentication Script:#

The properties required for this script are defined in a json file that follows the custom script schema as discussed here. Download the script, JSON and keep them in a folder.

From this folder, run the following command:

./jans-cli/config-cli.py --host <FQDN> --client-id $TESTCLIENT --client_secret $TESTCLIENTSECRET --operation-id post-config-scripts --data /personauthentication.json \
-cert-file yourcertfile.pem -key-file yourkey.key

Note: You will need keys and certificates to call the config-api using mutually authenticated TLS.

The authorize endpoint when invoked passes the control to the PersonAuthentication Script.

  • pepareForStep method: This is the first method that gets called in the PersonAuthentication Script.

The flow is as follows:

  1. Build the URL to the consent app from the Internal OP (First party OP). The openbanking_intent_id is an important parameter that typically goes to the consent app.
  2. Redirect to the 3rd Party URL.

  3. authenticate method: When the third party consent app redirects back to Jans- Auth server, it returns to https:///jans-auth/postlogin.htm. This takes us to the authenticate() method in the Person Authentication Script

This is what needs to be done here:

  1. To access request parameters use:

signedRequest = ServerUtil.getFirstValue(requestParameters, "request")

  1. Add claims to session (those which you hope to find in access_token, refresh_token and id_token. The Introspection and UpdateToken script reads these session variables)
        sessionIdService = CdiUtil.bean(SessionIdService)
        sessionId = sessionIdService.getSessionId() # fetch from persistence
        sessionId.getSessionAttributes().put("openbanking_intent_id",openbanking_intent_id )
        sessionId.getSessionAttributes().put("acr_ob", acr_ob )
  • All session variables should be returned from this method
def getExtraParametersForStep(self, configurationAttributes, step):
          return Arrays.asList("openbanking_intent_id", "acr_ob")

Introspection Script:#

To easily setup this script, parameters are defined in a json file that follows the custom script schema as discussed here. Download the script, JSON and keep them in a folder.

From this folder, run the following command:

./jans-cli/config-cli.py --host <FQDN> --client-id $TESTCLIENT --client_secret $TESTCLIENTSECRET --operation-id post-config-scripts --data /introspection.json \
-cert-file yourcertfile.pem -key-file yourkey.key

Note: You will need keys and certificates to call the config-api using mutually authenticated TLS.

This script can be used to add (persist) custom claims in an access token (and refresh token) * Access values from the session

sessionIdService = CdiUtil.bean(SessionIdService)
sessionId = sessionIdService.getSessionByDn(context.getTokenGrant().getSessionDn()) # fetch from persistence
  • Add it to access token
     openbanking_intent_id = sessionId.getSessionAttributes().get("openbanking_intent_id")
     responseAsJsonObject.accumulate("openbanking_intent_id", openbanking_intent_id)
  • To persist claims in a refresh token refer to the following article

Update Token Script:#

To easily setup this script, parameters are defined in a json file that follows the custom script schema as discussed here. Download the script, JSON and keep them in a folder.

From this folder, run the following command:

./jans-cli/config-cli.py --host <FQDN> --client-id $TESTCLIENT --client_secret $TESTCLIENTSECRET --operation-id post-config-scripts --data /updatetoken.json \
-cert-file yourcertfile.pem -key-file yourkey.key
Note: You will need keys and certificates to call the config-api using mutually authenticated TLS.

This script can be used to add custom claims to the id_token. As per the open banking standard, the token should contain claim openbanking_intent_id and the same value should also reflect in the sub claim. A similar expectation is required to be fulfilled by the FAPI-RW standard where the sub claim should have the user id.

  • Access values from the session
sessionIdService = CdiUtil.bean(SessionIdService)
sessionId = sessionIdService.getSessionByDn(context.getTokenGrant().getSessionDn()) # fetch from persistence
  • Add it to id_token token.
    # header claims
    jsonWebResponse.getHeader().setClaim("custom_header_name", "custom_header_value")

    #custom claims
    jsonWebResponse.getClaims().setClaim("openbanking_intent_id", openbanking_intent_id)

    #regular claims        
    jsonWebResponse.getClaims().setClaim("sub", openbanking_intent_id)

Note

After any changes in the custom scripts remember to restart the jans-auth service to apply them by restarting kubectl rollout restart deployment gluu-auth-server -n <gluu-namespace>.