README-GP-SAML.md

   1 gp-saml-gui
   2 ===========
   3
   4 [![Test Workflow Status](https://github.com/dlenski/gp-saml-gui/workflows/build/badge.svg)](https://github.com/dlenski/gp-saml-gui/actions/workflows/test.yml)
   5
   6 Table of Contents
   7 =================
   8
   9   * [Introduction](#introduction)
  10   * [Installation](#installation)
  11     * [First, non-Python Dependencies](#first-non-python-dependencies)
  12     * [Second, gp-saml-gui itself](#second-gp-saml-gui-itself)
  13   * [How to use](#how-to-use)
  14     * [Extra arguments to OpenConnect](#extra-arguments-to-openconnect)
  15   * [License](#license)
  16
  17 Introduction
  18 ============
  19
  20 This is a helper script to allow you to interactively login to a GlobalProtect VPN
  21 that uses [SAML](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language)
  22 authentication, so that you can subsequently connect with [OpenConnect](https://www.infradead.org/openconnect).
  23 (The GlobalProtect protocol is supported in OpenConnect v8.0 or newer; v8.06+ is recommended.)
  24
  25 Interactive login is, unfortunately, sometimes a necessary alternative to automated
  26 login via scripts such as
  27 [zdave/openconnect-gp-okta](https://github.com/zdave/openconnect-gp-okta).
  28
  29 This script is known to work with many GlobalProtect VPNs using the major single-sign-on (SSO) providers:
  30
  31 - Okta (sign-in URLs typically `https://<company>.okta.com/login/*`)
  32 - Microsoft (sign-in URLs typically `https://login.microsoftonline.com/*`)
  33
  34 Please search and file [issues](https://github.com/dlenski/gp-saml-gui/issues) if you can report success
  35 or failure with other SSO SAML providers.
  36
  37 Installation
  38 ============
  39
  40 First, non-Python Dependencies
  41 ------------------------------
  42
  43 gp-saml-gui uses GTK, which requires Python 3 bindings.
  44
  45 On Debian / Ubuntu, these are packaged as `python3-gi`, `gir1.2-gtk-3.0`, and
  46 `gir1.2-webkit2-4.0`:
  47
  48 ```
  49 $ sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-webkit2-4.0
  50 ```
  51
  52 On Fedora (and possibly RHEL/CentOS) the matching libraries are packaged in
  53 `python3-gobject`, `gtk3-devel`, and `webkit2gtk3-devel`:
  54
  55 ```
  56 $ sudo dnf install python3-gobject gtk3-devel webkit2gtk3-devel
  57 ```
  58
  59 On Arch Linux, the libraries are packaged in `gtk3`, `gobject-introspection`
  60 and `webkit2gtk`:
  61
  62 ```
  63 $ sudo pacman -S gtk3 gobject-introspection webkit2gtk
  64 ```
  65
  66 Second, gp-saml-gui itself
  67 --------------------------
  68
  69 Install gp-saml-gui itself using `pip`:
  70
  71 ```
  72 $ pip3 install https://github.com/dlenski/gp-saml-gui/archive/master.zip
  73 ...
  74 $ gp-saml-gui
  75 usage: gp-saml-gui [-h] [--no-verify] [-C COOKIES | -K] [-p | -g] [-c CERT]
  76                    [--key KEY] [-v | -q] [-x | -P | -S] [-u]
  77                    [--clientos {Windows,Linux,Mac}] [-f EXTRA]
  78                    server [openconnect_extra [openconnect_extra ...]]
  79 gp-saml-gui: error: the following arguments are required: server, openconnect_extra
  80 ```
  81
  82 How to use
  83 ==========
  84
  85 Specify the GlobalProtect server URL (portal or gateway) and optional
  86 arguments, such as `--clientos=Windows` (because many GlobalProtect
  87 servers don't require SAML login, but apparently omit it in their configuration
  88 for OSes other than Windows).
  89
  90 This script will pop up a [GTK WebKit2 WebView](https://webkitgtk.org/) window
  91 alongside your terminal window (see this [screenshot](screenshot.png)).
  92 After you successfully complete the SAML login via web forms, the script will output
  93 `HOST`, `USER`, `COOKIE`, and `OS` variables in a form that can be used by
  94 [OpenConnect](http://www.infradead.org/openconnect/juniper.html)
  95 (similar to the output of `openconnect --authenticate`):
  96
  97 ```sh
  98 $ eval $( gp-saml-gui --gateway --clientos=Windows vpn.company.com )
  99 Got SAML POST content, opening browser...
 100 Finished loading about:blank...
 101 Finished loading https://company.okta.com/app/panw_globalprotect/deadbeefFOOBARba1234/sso/saml...
 102 Finished loading https://company.okta.com/login/sessionCookieRedirect...
 103 Finished loading https://vpn.qorvo.com/SAML20/SP/ACS...
 104 Got SAML relevant headers, done: {'prelogin-cookie': 'blahblahblah', 'saml-username': 'foo12345@corp.company.com', 'saml-slo': 'no', 'saml-auth-status': '1'}
 105
 106 SAML response converted to OpenConnect command line invocation:
 107
 108     echo 'blahblahblah' |
 109         openconnect --protocol=gp --user='foo12345@corp.company.com' --os=win --usergroup=gateway:prelogin-cookie --passwd-on-stdin vpn.company.com
 110
 111 $ echo $HOST; echo $USER; echo $COOKIE; echo $OS
 112 https://vpn.company.com/gateway:prelogin-cookie
 113 foo12345@corp.company.com
 114 blahblahblah
 115 win
 116
 117 $ echo "$COOKIE" | openconnect --protocol=gp -u "$USER" --os="$OS" --passwd-on-stdin "$HOST"
 118 ```
 119
 120 If you specify either the `-P`/`--pkexec-openconnect` or `-S`/`--sudo-openconnect` options, the script
 121 will automatically invoke OpenConnect as described, using either [`pkexec` from Polkit](https://www.freedesktop.org/software/polkit/docs/0.106/polkit.8.html)
 122 or [`sudo`](https://www.sudo.ws/), as specified.
 123
 124 # Extra Arguments to OpenConnect
 125
 126 Extra arguments needed for OpenConnect can be specified by adding ` -- ` to the command line, and then
 127 appending these. For example:
 128
 129 ```sh
 130 $ gp-saml-gui -P --gateway --clientos=Windows vpn.company.com -- --csd-wrapper=hip-report.sh
 131 …
 132 Launching OpenConnect with pkexec, equivalent to:
 133     echo blahblahblahlongrandomcookievalue |
 134         sudo openconnect --protocol=gp --user=foo12345@corp.company.com --os=win --usergroup=gateway:prelogin-cookie --passwd-on-stdin vpn.company.com
 135 <pkexec authentication dialog pops up>
 136 <openconnect runs>
 137 ```
 138
 139 License
 140 =======
 141
 142 GPLv3 or newer