Skip to content

Custom Script Debugging#

The following guide will explain how to debug custom interception scripts.

Setup#

The following instructions assume Gluu Server is already installed and available. If not, perform a standard Gluu Server installation, then do the following:

  1. Install https://repo.gluu.org/tools/tools-install.sh
  2. Log out of CE
  3. Run /opt/gluu-server/opt/gluu/bin/prepare-dev-tools.py
  4. Log in to CE
  5. Run /opt/gluu/bin/eclipse.sh

Once complete, start the PyDev debug server:

  1. Open the Eclipse Debug perspective
  2. Run this command from the menu: Pydev > Start Debug Server

Development & Debugging#

Now we are ready to perform script development and debugging. Here is a quick overview:

  1. In order to simplify development, put the script into a shared folder like /root/eclipse-workspace
  2. Then instruct oxAuth to load the script from the file system instead of LDAP
  3. Add debug instructions to the script, as specified in the next section
  4. Execute the script

Enable Remote Debug in Custom Script#

  1. After the import section, add:

    REMOTE_DEBUG = True
    
    if REMOTE_DEBUG:
        try:
            import sys
            sys.path.append('/opt/libs/pydevd')
            import pydevd
        except ImportError as ex:
            print "Failed to import pydevd: %s" % ex
            raise
    
  2. Add the following lines wherever breakpoints are needed:

    if REMOTE_DEBUG:
        pydevd.settrace('localhost', port=5678, stdoutToServer=True, stderrToServer=True)
    

Sample Scenario#

  1. Log in to oxAuth
  2. Navigate to Manage Custom Script Section
  3. Expand Basic script section
  4. Copy the script to /root/eclipse-workspace/basic.py
  5. Change script Location type to File
  6. Specify the Script Path location to: /root/eclipse-workspace/basic.py
  7. Enable the script
  8. Check the following log to verify that oxAuth loaded the script properly: /opt/gluu/jetty/oxauth/logs/oxauth_script.log. It should look like this:

    ... (PythonService.java:239) - Basic. Initialization
    
    ... (PythonService.java:239) - Basic. Initialized successfully
    
  9. Open the following file in Eclipse: /root/eclipse-workspace/basic.py

  10. When opening the Python file for the first time, we need to instruct Eclipse to use a specific interpreter. Follow these steps:

    • Press the "Manual Config" button in the dialog box after opening the Python file
    • Open "PyDev->Interpreters->Jython Interpreters"
    • Click the "New..." button in the right panel. Name it "Jython" and specify the interpreter executable "/opt/jython/jython.jar"
    • Click "OK", then confirm the settings by clicking "OK" again, then "Apply and Close"
    • In the final dialog, confirm the settings by clicking "OK"
  11. Open basic.py in a file editor. After the import section, add the following lines to load the PyDev libraries:

    REMOTE_DEBUG = True  
    
    if REMOTE_DEBUG:  
        try:  
            import sys  
            sys.path.append('/opt/libs/pydevd')  
            import pydevd  
        except ImportError as ex:  
            print "Failed to import pydevd: %s" % ex  
            raise  
    
  12. Add this break condition to the first line in the authenticate method:

    if REMOTE_DEBUG:   
        pydevd.settrace('localhost', port=5678, stdoutToServer=True, stderrToServer=True)  
    
  13. Save basic.py

  14. Within one minute, oxAuth should load the changed file. Check the following log file again to make sure there are no load errors: /opt/gluu/jetty/oxauth/logs/oxauth_script.log
  15. To check if the script works, update the default authentication method to Basic Authentication. This can be performed in oxTrust by navigating to Manage Authentication > Default Authentication Method
  16. Open another browser or session and try to log in. Make sure to keep the first session open in order to disable the Basic Authentication method in case the script doesn't work as expected.
  17. After executing pydevd.settrace the script will transfer execution control to the PyDev server in Eclipse. You can use any debug commands. For example: Step Over (F6), Resume (F8), etc
  18. After debugging is finished, resume script execution to transfer execution control back to oxAuth

Additional Resources#

X Server troubleshooting#

Running /opt/gluu-server/opt/gluu/bin/prepare-dev-tools.py allows Eclipse to access X server.

It runs the following commands:

# Only this one key is needed to access from chroot 
xauth -f /root/.Xauthority-gluu generate :0 . trusted 2>1 >> /root/prepare-dev-tools.log

# Generate our own key, xauth requires 128 bit hex encoding
xauth -f /root/.Xauthority-gluu add ${HOST}:0 . $(xxd -l 16 -p /dev/urandom)

# Copy result key to chroot
cp -f /root/.Xauthority-gluu /opt/gluu-server/root/.Xauthority

# Allow to access local server X11   
sudo su $(logname) -c "xhost +local:

Unable to access x11#

If Eclipse is unable to access X11, run the following command from the host to check if it has the necessary permissisons:

user@u144:~$ xhost +local:
non-network local connections being added to access control list
user@u144:~$ xhost 
access control enabled, only authorized clients can connect
LOCAL:
SI:localuser:user

If the user is still unable to access X11, remove .Xauthority from user home and log out/log in again.

Setup#

For development the kubernetes setup must be local and accessible to the debug server address. The following steps will walk you trough a setup using Minikube with docker driver, and ksync for syncing the files between local and the container. The following instructions assume a fresh ubuntu 20.04, however the setup can be done on a diffrrent operating systems such as macOS or Windows.

System Requirements#

The minimum system requirement for running all Gluu services are 8GB RAM, 4 CPU, and 50GB disk. This can be dropped to 4GB RAM, 4CPU and 20GB disk space if operating with required services oxTrust, oxAuth, Jackrabbit , and LDAP.

Setup Minikube#

  1. Install Docker 18.09 or higher. For other operating systems follow the appropriate docs.

  2. Install minikube but do not start it yet.

  3. Install kubectl.

  4. Once Minikube is installed start it with the docker driver.

    minikube start --driver=docker
    
  5. If not automatically set configure kubectl to use the cluster:

    kubectl config use-context minikube
    
  6. Enable ingress on minikube

    minikube addons enable ingress
    

Install Gluu#

  1. Install Helm3

  2. Download pygluu-kubernetes.pyz. This package can be built manually.

  3. Optional: If using couchbase as the persistence backend. Download the couchbase kubernetes operator package for linux and place it in the same directory as pygluu-kubernetes.pyz

  4. Run :

./pygluu-kubernetes.pyz helm-install

Install Ksync#

Once Gluu is fully running we want to create an active sync between a local folder, and the folder that will hold the interception scripts inside the oxAuth server container.

  1. Create a folder that will hold the interception script inside the oxAuth container. Place the namespace where gluu is installed in the env GLUU_NAMESPACE and execute:

    GLUU_NAMESPACE=<gluu-namespace>
    for pod in $(kubectl get pods -n $GLUU_NAMESPACE --selector=app=oxauth --output=jsonpath={.items..metadata.name}); do
        kubectl exec -ti $pod -n $GLUU_NAMESPACE -- mkdir -p /opt/gluu/interception-scripts-ksync
    done        
    
  2. Install ksync

    curl https://ksync.github.io/gimme-that/gimme.sh | bash
    
  3. Initialize ksync

    ksync init -n <gluu-namespace>
    
  4. Start ksync.

    ksync watch -n <gluu-namespace> &
    
  5. Open a new terminal and create a folder called interception-scripts-ksync

    mkdir -p $(pwd)/interception-scripts-ksync
    
  6. Create a spec to start syncing folders between local and oxAuth container.

    ksync create --selector=app=oxauth $(pwd)/interception-scripts-ksync /opt/gluu/interception-scripts-ksync -n <gluu-namespace>
    
  7. Check the status. Also check the terminal where the watch command is running.

    ksync get
    
  8. Move the interception script to the local folder $(pwd)/interception-scripts-ksync. In this example we logged in Gluu, Configuration -> Person Authentication Scripts -> basic and copied the script to the local folder.

Install an IDE#

The IDE can be of choice but must contain PyDev. We chose Liclipse for this demonstartion.

Once complete, start the PyDev debug server:

  1. Open Liclipse

  2. Download the jython jar for the interpreter.

    wget https://repo1.maven.org/maven2/org/python/jython-standalone/2.7.2/jython-standalone-2.7.2.jar
    
  3. From the menu: go to File -> Open File and choose the interception script that will be debugged in $(pwd)/interception-scripts-ksync.

  4. When opening the Python file for the first time, we need to instruct Liclipse to use a specific interpreter. Follow these steps:

    • Press the "Manual Config" button in the dialog box after opening the Python file

    • Open "PyDev->Interpreters->Jython Interpreters"

    • Click the "New..." button in the right panel. Name it "Jython" and specify the interpreter executable that was downloaded previously "jython-standalone-2.7.2.jar"

    • Click "OK", then confirm the settings by clicking "OK" again, then "Apply and Close"

    • In the final dialog, confirm the settings by clicking "OK"

  5. From the menu: go to Window -> Perspective -> Open Perspective -> Other.. -> Debug

  6. From the menu: go to Pydev > Start Debug Server. Now the server should have started at port 5678. Take a note of the ip of the computer running Liclipse and save it for later use. Remember that the oxAuth pod must be able to communicate with this ip. If you have followed the instructions above and installed minikube on your local computer which is the same computer Liclipse is operating on you should be able to reach it from within the pods.

Development & Debugging#

Now we are ready to perform script development and debugging. Here is a quick overview:

  1. Instruct oxAuth to load the script from the file system instead of LDAP

  2. Add debug instructions to the script, as specified in the next section

  3. Execute the script

Enable Remote Debug in Custom Script#

  1. After the import section, add:

    REMOTE_DEBUG = True
    
    if REMOTE_DEBUG:
        try:
            import sys
            import pydevd
        except ImportError as ex:
            print "Failed to import pydevd: %s" % ex
            raise
    
  2. Add the following lines wherever breakpoints are needed:

    if REMOTE_DEBUG:
        pydevd.settrace('localhost', port=5678, stdoutToServer=True, stderrToServer=True)
    

Sample Scenario#

  1. Log in to Gluu

  2. Navigate to Configuration -> Person Authentication Scripts -> basic

  3. Expand basic script section

  4. Copy the script to $(pwd)/interception-scripts-ksync/basic.py

  5. Change script Location type to File

  6. Specify the Script Path location to the location of the folder inside oxAuth pods: /opt/gluu/interception-scripts-ksync/basic.py

  7. Enable the script

  8. Check the following log inside the the oxauth container to verify that oxAuth loaded the script properly: /opt/gluu/jetty/oxauth/logs/oxauth_script.log. It should look like this:

    kubectl exec -ti <oxauth-pod-name> -n <gluu-namespace> -- tail -f /opt/gluu/jetty/oxauth/logs/oxauth_script.log
    

    You should find the following in the log:

    ... (PythonService.java:239) - Basic. Initialization
    
    ... (PythonService.java:239) - Basic. Initialized successfully
    
  9. Download the jython jar for the interpreter.

    wget https://repo1.maven.org/maven2/org/python/jython-standalone/2.7.2/jython-standalone-2.7.2.jar
    
  10. From the IDE (Liclipse) menu: navigate to File -> Open File and choose the interception script that will be debugged in $(pwd)/interception-scripts-ksync/basic.py

  11. When opening the Python file for the first time, we need to instruct Liclipse to use a specific interpreter. Follow these steps:

    • Press the "Manual Config" button in the dialog box after opening the Python file

    • Open "PyDev->Interpreters->Jython Interpreters"

    • Click the "New..." button in the right panel. Name it "Jython" and specify the interpreter executable that was downloaded previously "jython-standalone-2.7.2.jar"

    • Click "OK", then confirm the settings by clicking "OK" again, then "Apply and Close"

    • In the final dialog, confirm the settings by clicking "OK"

  12. Open basic.py in a file editor. After the import section, add the following lines to load the PyDev libraries:

    REMOTE_DEBUG = True  
    
    if REMOTE_DEBUG:  
        try:  
            import sys  
            import pydevd  
        except ImportError as ex:  
            print "Failed to import pydevd: %s" % ex  
            raise  
    
  13. Add this break condition to the first line in the authenticate method. Place the ip of the maching running the ide , here liclipse i.e 192.168.140.2.

    if REMOTE_DEBUG:   
        pydevd.settrace('<ip-of-machine-running-ide>', port=5678, stdoutToServer=True, stderrToServer=True)  
    
  14. Save basic.py

  15. Within one minute, oxAuth should load the changed file. Check the following log file again to make sure there are no load errors: /opt/gluu/jetty/oxauth/logs/oxauth_script.log

  16. To check if the script works, update the default authentication method to Basic Authentication. This can be performed in oxTrust by navigating to Configuration -> Manage Authentication -> Default Authentication Method

  17. Open another browser or session and try to log in. Make sure to keep the first session open in order to disable the Basic Authentication method in case the script doesn't work as expected.

  18. After executing pydevd.settrace the script will transfer execution control to the PyDev server in Liclipse. You can use any debug commands. For example: Step Over (F6), Resume (F8), etc

  19. After debugging is finished, resume script execution to transfer execution control back to oxAuth