Security

 View Only
last person joined: 7 hours ago 

Forum to discuss Enterprise security using HPE Aruba Networking NAC solutions (ClearPass), Introspect, VIA, 360 Security Exchange, Extensions, and Policy Enforcement Firewall (PEF).
Expand all | Collapse all

Simulate Login to ClearPass Guest using F5 External Monitor

This thread has been viewed 30 times
  • 1.  Simulate Login to ClearPass Guest using F5 External Monitor

    Posted May 23, 2023 02:48 PM

    I just finished writing a bash script which simulates login to ClearPass Guest with HTTPS from F5 external monitor shell script using curl: GitHub - wd-tim-haynie/bt-netengops-f5-sim-cp-login: Simulates login to ClearPass from F5 external monitor shell script using curl 

    # F5 ClearPass Guest Login Simulation
    
    The `f5-sim-cp-login` script serves as an F5 external monitor, specifically designed to simulate login and logout of the ClearPass Guest application's default login page located at `/guest/auth_login.php`. This simulation offers a more reliable alternative to the standard HTTPS monitor proposed in the "Deploying CPPM with F5 BIG-IP Local Traffic Manager (LTM)" guide, which hasn't been updated since 2014. By employing this script, you gain a robust method to monitor the status of the ClearPass Guest application, surpassing the capabilities of the BIG-IP's built-in HTTP/HTTPS monitor.
    
    Notably, it enables the detection of potential issues such as corrupted Web Login pages, which would otherwise pass the stock HTTP/HTTPS healthcheck monitor and even return an HTTP status code of 200 despite having a blank body. This can happen if the ClearPass Guest database somehow gets corrupt. Moreover, the script can also load and verify the status of any additional pages that you wish to monitor. This feature enhances the monitoring capabilities, ensuring not just the functionality of the login page, but also the accessibility and health of other critical pages in your application. 
    
    ## Installation and Update
    
    Follow these steps to install or update the script on an F5 device:
    
    1. Login to the F5 User Interface (UI).
    2. Navigate to `System > File Management > External Monitor Program File List`.
    3. Click `Import`.
    
    To create a monitor object:
    
    - On an LTM device, go to Local Traffic > Monitors > Create. Fill in the name and description fields, and select 'External' as the type.
    - On a GTM (BigIP DNS) device, go to DNS > GSLB > Monitors > Create. Fill in the name and description fields, and select 'External' as the type.
    
    Consider including a link to this GitHub repository in the description field of the monitor to facilitate future references and updates, especially since the operational details of this script aren't documented elsewhere.
    
    Then, add USERNAME and PASSWORD variables. In the Variables section of the monitor configuration, set USERNAME to your test username and click 'Add'. Then set PASSWORD to your test password and click 'Add' again. For a quick setup, you can initially use the plaintext PASSWORD variable. However, it's recommended to switch to an encrypted password once the monitor is operational (refer to the Password Encryption section).
    
    Finally, click 'Finished' to complete the configuration of your monitor object.
    
    The script must be installed on all LTM pairs AND each GTM for accurate functioning. For GTM devices, you must manually install or update the script as these changes don't sync like other GTM configurations.
    
    On the ClearPass side, configure your guest operator login policy to map the test username to the default "Null Profile". This allows login but assigns no privileges. The test username/password can be configured in the local user database, or an external resource like Active Directory if desired.
    
    ## Script Variables
    
    The script uses the following variables, which are set in the monitor object itself:
    
    - `USERNAME`: your monitor username
    - `PASSWORD`: plaintext password (should only be used for testing)
    - `ENCRYPTED_PASSWORD`: an aes-256-cbc encrypted password (overrides `PASSWORD` if set)
    - `DECRYPTION_KEY_FILE_NAME`: filename of the decryption key iFile for `ENCRYPTED_PASSWORD`
    - `LOG_LEVEL`: (optional) logger level (debug, info, notice, warning, err, crit, alert, emerg)
    
    There is no need to encode special characters with URL encoding (e.g., '%21' for '!') on the tested versions. However, this could be version-dependent. 
    
    ## Script Arguments
    
    If you wish to monitor other pages on the ClearPass appliance, you can add their URIs as arguments in the monitor. For instance, you could effectively monitor the ClearPass admin server service (cpass-admin-server) by adding `/tips/welcome.action` as an argument. It's also best practice to monitor any critical pages involved in your captive portal login process. 
    
    For monitoring captive portal pages in the ClearPass Guest application, append the URI with `?_browser=1`. This query parameter simulates the behavior of a real browser. Failing to include it may result in a different status code than expected.
    
    For example, you could add `/tips/welcome.action /guest/mycaptiveportallanding.php?_browser=1` as arguments to the script, which will then monitor these two pages.
    
    ## Behavior and Error Detection
    
    The script frequently uses "> /dev/null 2>&1". This is to ensure that the monitor only returns "UP" when the script completes fully. This is due to the behavior of the F5 external monitor, which considers the monitor successful if ANYTHING is output to STDOUT or STDERR.
    
    The script is designed to intentionally check for an HTTP status code 302. This is because an incorrect login attempt will still return a status code 200 with an error message will be embedded within the HTML body. Conversely, a successful login will generate a 302 status code, signifying appropriate redirection after the authentication process.
    
    ## Password Encryption
    
    1. Generate a secure, random 32-character (or longer) decryption key. Save this key in a text file temporarily.
    2. Import this file into your LTMs and GTMs as an iFile via `System > File Management > iFile List`.
    3. Run this command to encrypt your password: `echo 'your-password' | openssl enc -aes-256-cbc -base64 -k 'your-decryption-key'`
    4. Save the encrypted password as a variable in the monitor with the name `ENCRYPTED_PASSWORD`.
    
    ### Password Decryption Key File
    
    Only the first line of this file is read as the decryption key; all subsequent lines are disregarded. 
    
    It's essential to upload this iFile to EVERY device - remember, GTMs don't automatically sync this information. If you have LTMs that are part of a sync group, they will synchronize this iFile among themselves.
    
    ## Limitations
    
    1. When you upload a file as an iFile, the BIG-IP will append some numeric identifier, which isn't predictable. To avoid accidentally matching the wrong file, ensure you're using a unique file name for the decryption key file.
    2. If you want to monitor the same resource in multiple locations (e.g., in two different pools), create a separate monitor (with a unique name) for each location. Using the same monitor for the same resource in different locations could unintentionally cause the scripts to interfere with each other due to the shared usage of the same process ID (pid) file.
        
    ## Troubleshooting
    
    In case you encounter issues while running the script, refer to the following troubleshooting steps:
    
    1. **Check Login Credentials:** Ensure your username and password can successfully log into `/guest/auth_login.php` from a web browser. Use the Access Tracker in ClearPass to confirm a successful login status.
    2. **Open Log:** Log into the F5 bash shell and execute the command `tail -f /var/log/ltm`. Keep this window open for further troubleshooting.
    3. **Set Debug Level:** In the monitor configuration, set the `LOG_LEVEL` variable to `debug`.
    4. **Configure Password:** Remove the `ENCRYPTED_PASSWORD` variable and set the `PASSWORD` variable to your plaintext password.
    5. **Check Log for Errors:** With the log still open, verify if the script functions as expected with the plaintext password. Any errors or issues will be logged here.
    6. **Verify ClearPass Access Tracker:** Check the ClearPass Access Tracker to confirm if it's receiving the request from the test username and verify its response.
    7. **Test Encrypted Password:** Once the script functions correctly with the plaintext password, retry with the encrypted password. Ensure `DECRYPTION_KEY_FILE_NAME` is correctly set to the appropriate file. If necessary, uncomment the following lines in your script for additional debugging:
            `#LOG_MESSAGE "Decryption Key: $DECRYPTION_KEY" "debug"`
            `#LOG_MESSAGE "Decrypted Password: $PASSWORD" "debug"`
       Remember that this could potentially expose sensitive information in your logs, especially if they're transmitted in cleartext to a syslog server. To avoid this risk, consider redirecting these messages to a separate output file by uncommenting these lines and replacing `/path/to/outputfile` with a valid path:
            `#echo "Decryption Key: $DECRYPTION_KEY" >> /path/to/outputfile`
            `#echo "Decrypted Password: $PASSWORD" >> /path/to/outputfile`
       Ensure to securely delete this output file once you're done with debugging.
    8. **Unset Debug Level:** Once everything functions as expected, delete the `LOG_LEVEL` variable to stop the verbose logging and return it to the default level. Also, remember to re-comment any lines that were uncommented during the debugging process in step 7 to maintain the security of your environment and prevent potentially sensitive information from being logged.
    
    ## About
    
    Please refer to the ClearPass F5 Tech Note here: https://www.arubanetworks.com/techdocs/ArubaDocPortal/content/cp-resources/cp-tech-notes.htm (Click the link for F5 Load Balancers)
    
    The project has been tested on ClearPass 6.9.13 and BigIP 14.1.4.6.
    
    ### Version History
    
    - **1.4**: Added the capability to monitor any page, using arguments passed from the monitor.
    - **1.3**: Simplified and improved logging, enhanced error handling, added the ability to specify any decryption key file, and fixed minor bugs.
    - **1.2.1**: Moved MIN_LOG_LEVEL and LOGGING variables to be configured by the monitor. Enabled logging by setting LOGGING to true or specifying a valid MIN_LOG_LEVEL.
    - **1.2**: Added password encryption and improved PID management, error detection, and cleanup.
    - **1.1**: Initial published version with cleartext passwords and limited logging.
    
    ### Disclaimer
    
    This script is provided for the purpose of testing and troubleshooting, and is intended to be used in a responsible manner. It is not designed for, and should not be used for, unauthorized access to any systems. While efforts have been made to ensure its accuracy and reliability, the author assumes no responsibility for any issues or complications that may arise from the use of this script within your environment. Users are advised to carefully evaluate the script's applicability to their specific needs and to take appropriate precautions in its usage.
    
    ### License
    
    This project is licensed under the MIT License. See the LICENSE file for more details.
    
    ### Author
    
    Tim Haynie, CWNE #254, ACMX #508 [LinkedIn Profile](https://www.linkedin.com/in/timhaynie/)
    



    ------------------------------
    Tim Haynie, CWNE 254, ACMX 508, ACDX 384
    ------------------------------



  • 2.  RE: Simulate Login to ClearPass Guest using F5 External Monitor

    MVP
    Posted May 24, 2023 07:20 AM

    What is the purpose of the Guest monitor? All Guest registration needs to go through the publisher. We deploy 2 RADIUS authentication monitors. One uses a local CPPM User account & the other uses an AD account.

    We proved years ago that the F5 Tech note is incorrect and can cause major outages. We experienced that when following the Tech Note. We have used the F5 successfully for years using an iRule instead of the built-in F5 iApp. After many attempts to help get the Tech Note updated, I gave up on doing that. Feel free to PM me for details.



    ------------------------------
    Bruce Osborne ACCP ACMP
    Liberty University

    The views expressed here are my personal views and not those of my employer
    ------------------------------



  • 3.  RE: Simulate Login to ClearPass Guest using F5 External Monitor

    Posted May 25, 2023 11:45 PM

    The reason I wrote this monitor is because I had a single ClearPass node which passed the stock health checks and returned a 200 HTTP code, yet was actually broken - it returned a null body in one of the captive portal pages and also didn't use our custom skin. So I decided to get a little more thorough with the health checking and that's why I wrote this monitor. It still may not catch absolutely every type of failure, but certainly is more robust than the built-in F5 monitor capabilities. I did an external monitor because I found iRules cannot mark a resource up and down, so I resorted to a bash script. It does NOT do a formal guest login; it is logging in as an operator/admin, but this is good enough.

    I still use a RADIUS monitor for an AD check, and I use this monitor for the local user. A third monitor I have is an accounting monitor. That more or less validates nearly everything you need to validate on the appliance, botb front-end (RADIUS, HTTP) and back-end (SQL database, LDAPS).

    At this point I've made the monitor quite feature rich, it logs in using a test username and password, monitor any page you want on the ClearPass appliance (the tips landing page and custom captive portal pages are good ones to monitor) and provide detailed logging.

    On the subject of documentation, I happen to know that the author of the Tech Note is no longer with Aruba, so not much chance they'll ever update it.



    ------------------------------
    Tim Haynie, CWNE 254, ACMX 508, ACDX 384
    ------------------------------



  • 4.  RE: Simulate Login to ClearPass Guest using F5 External Monitor

    Posted May 26, 2023 02:04 AM

    Furthermore, it sounds like you're saying "guest registration goes through the publisher", I think that is very distinct from guest authentication. Yes, the account must get created on the publisher, but the actual authentication itself happens on the subscriber. So monitoring HTTP on subscribers makes sense.



    ------------------------------
    Tim Haynie, CWNE 254, ACMX 508, ACDX 384
    ------------------------------



  • 5.  RE: Simulate Login to ClearPass Guest using F5 External Monitor

    MVP
    Posted May 26, 2023 07:28 AM

    OK, that makes sense for you then.

    I have a cluster of 5 25K hardware servers. 4 are  F5 load-balanced, with the publisher available, but not in the pool. The publisher handles all our Guest authentication in addition to registration.

    2 of our subscribers are primary & secondary for TACACS authentication since we have not found a load balance solution for TACACS. 

    Thank you for your insights and sharing,



    ------------------------------
    Bruce Osborne ACCP ACMP
    Liberty University

    The views expressed here are my personal views and not those of my employer
    ------------------------------



  • 6.  RE: Simulate Login to ClearPass Guest using F5 External Monitor

    MVP
    Posted May 26, 2023 07:38 AM

    OK, I was not aware Danny Jump had left Aruba. Last I heard he was moved to the ClearPass PLM team.



    ------------------------------
    Bruce Osborne ACCP ACMP
    Liberty University

    The views expressed here are my personal views and not those of my employer
    ------------------------------