--------------------------------------------------------------------------------
README FOR LINUX OPENCONNECT INSTALL & SETUP

Date: May 5, 2024
--------------------------------------------------------------------------------

This is a guide on getting OpenConnect working with the VT VPN service using
the SAML authentication method.

OpenConnect (via the SAML login method) to the Pulse Secure/Ivanti VPN server 
requires the use of a web browser cookie. This means that a web browser is 
required to perform the login and authentication, after which the provided 
script can capture the web cookie from the browser session to pass to 
OpenConnect to complete the VPN connection.  Both Firefox and Chrome have been 
tested on Ubuntu (23.10) and Linux Mint (21.3) to verify they work, but the 
initial setup is slightly different depending on the browser used.

-------------
Requirements:
-------------

BASH is the shell that was used for creating and testing these scripts.  But 
ZSH, FISH, CSH, TCSH shells should also be supported (but are untested). A 
supported shell is required so that it can call the appropriate Python 
Virtual Machine activation script which will perform the bulk of the VPN 
authentication.

--------------
Prerequisites:
--------------

ALL:
	- Install OpenConnect:

		# sudo apt-get install openconnect

	- Install the Python virtual environment:

		# sudo apt-get install python3-venv

CHROME USERS:
	- Chrome is not included by default in Ubuntu or Linux Mint, so if we 
	  wish to use it to connect to the VPN we can install it with the 
	  following command:

		# sudo apt install chromium-browser

-----------------------
Installation and Setup:
-----------------------

1) Download and Copy the "OC-VPN.tar.gz" file to the home directory of your 
   Linux computer. Then extract the contents:

	# cp OC-VPN.tar.gz $HOME
	# cd $HOME
        # tar -xzf OC-VPN.tar.gz

2) After extracting the contents there will be a new directory named 
   "OpenConnect-VPN".  Within this directory run the script "create-vpn.sh" to 
   create the required Python Virtual Machine and install the required Python 
   modules into it.

        # ~/OpenConnect-VPN/create-vpn.sh

3) FIREFOX USERS ONLY, if you use Chrome skip to Step 4.  Firefox has an issue 
   that if you already have a browser window open it prevents your existing 
   profile from being used to open another instance for the VPN authentication.  
   To get around this we create a new profile directory that the VPN script is 
   able to utilize:

        a) In Ubuntu (or "snap" installed firefox):

            # mkdir -p ~/snap/firefox/common/.mozilla/firefox/oc-vpn

        b) In other flavors on Linux (with "apt" installed firefox):

            # mkdir -p ~/.mozilla/firefox/oc-vpn

	c) If your installation has a different location for the profiles you 
	   will need to find that location and create a directory named 
	   "oc-vpn".

4) Edit the "vpn-connect.py" file in the "OpenConnect-VPN" directory and 
   change the items in the "user defined variables" section to match your 
   setup:

        a) browser - uncomment the line that matches your chosen browser.

        b) FProfile - Only applicable for Firefox users.  Set the path to the 
	   the profile directory you created in Step 3 above.

        c) host - use either "vpn.nis.vt.edu/vttraffic" (preferred) or 
	   "vpn.nis.vt.edu/alltraffic" depending on if you only want VT 
	   traffic or All traffic to go over the VPN link.

        d) user - set this to your VT PID (minus the @vt.edu portion)

5) Connect to the VT VPN by running the following script:

		# ~/OpenConnect-VPN/start-vpn.sh

The start-vpn.sh script activates the Python VM and then run the python 
VPN connection script. This python script will open a new browser window 
for logging into the VPN.   

    - The first screen with ask you for your VT PID (which is the first part of 
      your @vt.edu email address) and PID password. 
    - The second screen will ask for your preferred 2-factor authentication. 
    - There may be a third screen asking "Is this your device?" You have two 
      options:
        a) "Yes, this is my device".  Select this if you are the only one who uses
           this computer.
        b) "No, other people use this device".  Select this if the computer is 
           shared with others.  This option with not save any of your VPN 
           login credentials.

The browser window should then close shortly.  You may be prompted from the 
terminal for you Linux password as OpenConnect requires sudo permissions.

You should now be connected to the VPN.  The terminal window needs to remain 
open for the VPN connection.  When you are done with the VPN session use the 
CTRL-C keystroke in this terminal window.  The VPN connection will close and 
the script will then automatically deactivate the virtual environment and 
return you to a normal terminal prompt.

Now that everything is setup, in the future only the "start-vpn.sh" script needs 
to be run to connect to the VPN.