docs: debugging CE - #3257 (#3342)

docs/admin/developer/interception-scripts-debug-ce.md

@@ -0,0 +1,122 @@
+# Debugging a custom script:
+### Setup
+Assuming that the Jans-auth server is already installed, perform the following steps:
+
+1. Install https://repo.gluu.org/tools/tools-install.sh
+1. Run opt/jans/bin/prepare-dev-tools.py
+1. Log in to CE
+1. Run /opt/jans/bin/eclipse.sh
+Once complete, start the PyDev debug server:
+
+* Open the Eclipse Debug perspective
+* From the menu: `Pydev` > `Start Debug Server`
+
+### Development & Debugging
+1. 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
+1. Then instruct jans-auth to load the script from the file system instead of LDAP
+1. Add debug instructions to the script, as specified in the next section
+1. 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
+
+```
+1. Add the following lines wherever breakpoints are needed:
+
+```
+if REMOTE_DEBUG:
+    pydevd.settrace('localhost', port=5678, stdoutToServer=True, stderrToServer=True)
+```
+
+### Example
+
+1. Copy the [script](https://github.com/JanssenProject/jans/blob/main/jans-linux-setup/jans_setup/static/extension/person_authentication/BasicExternalAuthenticator.py) to /root/eclipse-workspace/basic.py
+2. Change script Location type to File using a jans-cli 
+3. Assume that we're using basic.py,  Specify the Script Path location to: /root/eclipse-workspace/basic.py
+4. Enable the script using jans-cli 
+Check the following log to verify that jans-auth loaded the script properly: /opt/jans/jetty/jans-auth/logs/jans-auth_script.log. It should look like this:
+```
+... (PythonService.java:239) - Basic. Initialization
+
+... (PythonService.java:239) - Basic. Initialized successfully
+```
+5. Open the following file in Eclipse: /root/eclipse-workspace/basic.py
+
+6. 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"
+
+7. 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  
+
+```
+8. Add this break condition to the first line in the authenticate method:
+
+```
+if REMOTE_DEBUG:   
+    pydevd.settrace('localhost', port=5678, stdoutToServer=True, stderrToServer=True) 
+``` 
+9. Save basic.py
+
+10. Within one minute, jans-auth should load the changed file. Check the following log file again to make sure there are no load errors: /opt/jans/jetty/jans-auth/logs/jans-auth_script.log
+11. To check if the script works, update the default authentication method to Basic Authentication. Use jans-cli.
+
+12. 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.
+13. 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
+14. After debugging is finished, resume script execution to transfer execution control back to jans-auth
+
+### Useful link : https://www.pydev.org/manual_adv_remote_debugger.html
+
+### X Server troubleshooting : Running `/opt/jans/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-jans generate :0 . trusted 2>1 >> /root/prepare-dev-tools.log
+
+# Generate our own key, xauth requires 128 bit hex encoding
+xauth -f /root/.Xauthority-jans add ${HOST}:0 . $(xxd -l 16 -p /dev/urandom)
+
+# Copy result key to chroot
+cp -f /root/.Xauthority-jans /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.