lsanders/openconnect

OpenConnect client extended to support Palo Alto Networks' GlobalProtect VPN

OpenConnect with PAN GlobalProtect support

Table of Contents

• What is this?
  • Feedback and troubleshooting
  • Installation
    • Building from source on Linux
    • Building on the Mac
  • Connecting
    • Docker
    • Portal vs. gateway servers
    • HIP report submission
  • TODO

What is this?

This is a modified version of the fantastic open-source VPN client OpenConnect which supports the PAN GlobalProtect VPN in its native modes (SSL and ESP)—with no assistance or cooperation needed from your VPN administrators.

I began developing it in October 2016, and started using it for "real work" almost immediately. It has become increasingly polished since then.

Feedback and troubleshooting

GlobalProtect support is not yet part of any official OpenConnect release (but see discussions on official mailing list). Keep this in mind when discussing GlobalProtect issues on the mailing list.

Please report any problems as Github issues. If you are having trouble authenticating to your GlobalProtect server, please run OpenConnect with the --dump -vvv flags to dump the authentication flow; please compare the back-and-forth configuration requests to this anonymized transcript and include information about relevant differences in your issue report.

Bonus points: If your VPN uses a weird authentication flow, please check out the Gist where I wrote a quick-and-dirty "GlobalProtect server simulator" in Python. It's fairly straightforward to understand, and if you can modify it to reproduce the authentication flow used by your VPN, it'll make it a whole lot easier to add support.

Installation

Please refer to the build requirements for the official releases of OpenConnect. This version has the exact same build dependencies as OpenConnect v7.06; modern versions of autoconf, automake, gcc, libxml, etc.

Building from source on Linux

Under Debian-based or Ubuntu-based distributions, this should install the requirements:

$ sudo apt-get install build-essential gettext autoconf automake libproxy-dev libxml2-dev libtool vpnc-scripts pkg-config \
                       libgnutls-dev # may be named libgnutls28-dev on some recent Debian/Ubuntu-based distros

Once you have all the build dependencies installed, checkout and build the globalprotect branch from this repository.

$ git clone https://github.com/dlenski/openconnect.git
$ cd openconnect
$ git checkout globalprotect
$ ./autogen.sh
$ ./configure
$ make
$ sudo make install && sudo ldconfig

Building on the Mac

Homebrew is required. To build and install into /usr/local:

$ brew install pkg-config gettext gnutls lz4 automake
$ export LIBTOOLIZE=glibtoolize
$ ./autogen.sh
$ ./configure --prefix=/usr/local --with-vpnc-script=/usr/local/etc/vpnc-script --disable-nls
$ make
$ make install

Please see this Gist on how to set up and use OpenConnect on the Mac. Don't forget to install vpnc-script into /usr/local/etc.

Connecting

Run openconnect like this to test it with your GlobalProtect VPN provider.

$ ./openconnect --protocol=gp server.company.com --dump -vvv
Please enter your username and password.
Username:
Password:

It currently supports the following authentication mechanisms:

• username and password
• "challenge"-based multi-factor authentication, wherein the server requests a secondary username and password after the first one
• TLS/SSL client certificate (include --certificate cert_with_privkey.pem if your VPN requires a client certificate and private key)

I'd welcome feedback on how to support other authentication methods in use with GlobalProtect.

Docker

Building an openconnect Docker image is as easy as:

$ docker build -t openconnect .

Then, you can run that docker image as a container:

$ docker run -ti openconnect
/openconnect# ./openconnect --protocol=gp server.company.com

But that'll restrict the use of the tunnel to inside the container, and maybe you want to use it system-wide. For that, you'll need a privileged container making use of the host (you computer) network:

$ docker run -ti --rm --privileged --net=host openconnect
/openconnect# ./openconnect --protocol=gp server.company.com

Leave that container running, open another terminal, and you'll see a newly created tun connection for your whole system to use.

HIP report submission

The HIP ("Host Integrity Protection") mechanism is a security scanner for PAN GlobalProtect VPNs, in the same vein as Cisco's CSD and Juniper's Host Checker.

The server requests a "HIP report" upon client connection, then the client generates a "HIP report" XML file, and then the client uploads it to the server.

If all goes well, the client should have the expected level of access to resources on the network after these steps are complete. At least two things can go wrong:

• Many GlobalProtect servers report that they require HIP reports, but don't actually enforce this requirement. (For this reason, OpenConnect does not currently fail if a HIP report is required but no HIP report script is provided.)
• Many GlobalProtect servers will claim that the HIP report was accepted successfully but silently fail to enable the expected network access, presumably because some aspect of the HIP report contents were not approved.

OpenConnect supports HIP report generation and submission by passing the --csd-wrapper=SCRIPT argument with a shell script to generate a HIP report in the format expected by the server. This shell script must output the HIP report to standard output and exit successfully (status code 0).

An example hipreport.sh script is included in the repository. Depending on how picky your GlobalProtect VPN is, it may be necessary to spoof or alter some of the parameters of the HIP report to match your GlobalProtect VPN's expectations as to its contents.

Portal vs. gateway servers

For some GlobalProtect VPNs, there is a distinction between "portal" and "gateway" servers, although in many GlobalProtect VPNs they run on the same server. "Portal" application URLs are found under /global-protect, while "gateway" application URLs are under /ssl-vpn.

Try using both the "Portal address" and the "GlobalProtect Gateway IP" shown in the Windows client with OpenConnect:

[]

The official GlobalProtect VPN clients always connect first via the portal. The portal then sends a choice of one or more gateways. However, this behavior is unnecessary, and adds an additional delay in establishing a connection.

Recent versions of openconnect can connect via either the portal endpoint or the gateway endpoint:

• If unspecified, the gateway endpoint is tried first, then the portal endpoint.
• For the gateway, include a URL-path starting with /ssl-vpn or specify --usergroup=gateway
• For the portal, include a URL-path starting with /global-protect or specify --usergroup=portal
  • To choose a specific gateway from the portal without further prompting, add --authgroup $GATEWAYNAME

Example of connecting via the portal interface and getting a choice of gateway servers:

$ openconnect --protocol=gp --usergroup=portal server.company.com
Please enter your username and password.
Username:
Password:
..
Connected to HTTPS on server.company.com
3 gateway servers available:
  NorthAmerica (vpn-na.company.com)
  Europe (vpn-eu.company.com)
  Asia (vpn-asia.company.com)
Please select GlobalProtect gateway.
GATEWAY: [NorthAmerica|Europe|Asia]:
...

TODO

• Support web-based/SAML-based authentication flows (see pull #98 for preliminary work)
• Configure multi-stage build into the Dockerfile, to get a smaller Docker image