include clientos in output command-lines and environment variables

[nu-vpn-proxy.git] / README.md

diff --git a/README.md b/README.md
index 6df9f5d9e07756f9de5c6594923a0c2259ab8f8f..03d7d66557ed6b38511e8a8a223171dd8703e7e8 100644 (file)
--- a/README.md
+++ b/README.md
@@ -8,19 +8,43 @@ Interactive login is, unfortunately, sometimes a necessary alternative to automa
 login via scripts such as
 [zdave/openconnect-gp-okta](https://github.com/zdave/openconnect-gp-okta).
 
+Installation
+============
+
+gp-saml-gui uses GTK, which requires Python 3 bindings.
+
+On Debian / Ubuntu, these are packaged as `python3-gi`, `gir1.2-gtk-3.0`, and
+`gir1.2-webkit2-4.0`:
+
+```
+$ sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-webkit2-4.0
+```
+
+Then, set up a virtual environment that can access these system packages,
+activate it, and install the Python dependencies:
+
+```
+$ virtualenv --python=python3 --system-site-packages venv
+$ . venv/bin/activate
+$ pip install requests
+```
+
 How to use
 ==========
 
-Specify the GlobalProtect server URL (portal or gateway) and optional arguments.
+Specify the GlobalProtect server URL (portal or gateway) and optional
+arguments, such as `--clientos=Windows` (because many GlobalProtect
+servers don't require SAML login, but apparently omit it in their configuration
+for OSes other than Windows).
 
 This script will pop up a [GTK WebKit2 WebView](https://webkitgtk.org/) window.
 After you succesfully complete the SAML login via web forms, the script will output
-`HOST`, `USER`, and `COOKIE` variables in a form that can be used by
+`HOST`, `USER`, `COOKIE`, and `OS` variables in a form that can be used by
 [OpenConnect](http://www.infradead.org/openconnect/juniper.html)
 (similar to the output of `openconnect --authenticate`):
 
 ```sh
-$ eval $( gp-saml-gui.py -v vpn.company.com )
+$ eval $( gp-saml-gui.py --clientos=Windows vpn.company.com )
 Got SAML POST content, opening browser...
 Finished loading about:blank...
 Finished loading https://company.okta.com/app/panw_globalprotect/deadbeefFOOBARba1234/sso/saml...
@@ -31,21 +55,21 @@ Got SAML relevant headers, done: {'prelogin-cookie': 'blahblahblah', 'saml-usern
 SAML response converted to OpenConnect command line invocation:
 
     echo 'blahblahblah' |
-        openconnect --protocol=gp --user='foo12345@corp.company.com' --usergroup=prelogin-cookie:gateway --passwd-on-stdin vpn.company.com
+        openconnect --protocol=gp --user='foo12345@corp.company.com' --os=win --usergroup=prelogin-cookie:gateway --passwd-on-stdin vpn.company.com
 
-$ echo $HOST; echo $USER; echo $COOKIE
+$ echo $HOST; echo $USER; echo $COOKIE; echo $OS
 https://vpn.company.com/gateway:prelogin-cookie
 foo12345@corp.company.com
-blahblahblah'
+blahblahblah
+win
 
-$ echo "$COOKIE" | openconnect --protocol=gp -u "$USER" --passwd-on-stdin "$HOST"
+$ echo "$COOKIE" | openconnect --protocol=gp -u "$USER" --os="$OS" --passwd-on-stdin "$HOST"
 ```
 
 TODO
 ====
 
 * Packaging
-* Explain dependencies
 
 License
 =======