Setting up git in a corporate environment

Working in a corporate environment exposes some issues when trying to access git repositories on the internet such as Bitbucket or github. The main pain points are proxy servers.

A typical corporate environment uses proxy servers such as the open source squid or the commercial BlueCoat's ProxySG to access the internet.

A proxy server is used, to cache frequently accessed web pages and to deny access to certain content. For this to work most proxies are using some kind of authentication.

Corporate networks which are using Active Directory to authorize users are often using NTLM. The "NT Lan Manager protocol" is an old protocol and not common in the Linux or non-windows world.

Git does support proxy servers with basic authentication (username:password) but does not support NTLM authentication.

But there is a solution for the problem. Setup another proxy! Don't worry, this is easy.

Download CNTLM and install it.

CNTLM is a proxy server which accepts anonymous connection on one side and forwards it to a upstream proxy, which requires NTLM authentication.

Befor we start CNTLM, we have to configure it.

What info is needed?

  • Your credentials
  • The upstream proxy

Edit "C:\Program Files (x86)\Cntlm\cntlm.ini" and make sure the file is writable (CNTLM is a bit old and stores the ini file in the "program files (x86)" folder which is only writable with elevated permission).

Insert Username and Domain and comment out Password, because we don't want to store the password in plain text.

#
# Cntlm Authentication Proxy Configuration
#
# NOTE: all values are parsed literally, do NOT escape spaces,
# do not quote. Use 0600 perms if you use plaintext password.
#

Username      USERNAME	
Domain		DOMAIN
#Password	password
# NOTE: Use plaintext password only at your own risk
# Use hashes instead. You can use a "cntlm -M" and "cntlm -H"
# command sequence to get the right config for your environment.
# See cntlm man page
# Example secure config shown below.
# PassLM          1AD35398BE6565DDB5C4EF70C0593492
# PassNT          77B9081511704EE852F94227CF48A793
### Only for user 'testuser', domain 'corp-uk'
PassNTLMv2      YOURHASHGOESHERE

# Specify the netbios hostname cntlm will send to the parent
# proxies. Normally the value is auto-guessed.
#
# Workstation	netbios_hostname

# List of parent proxies to use. More proxies can be defined
# one per line in format <proxy_ip>:<proxy_port>
#
Proxy		 YOURPROXYIP.YOUPROXYPORT

Save the file.

Open an elevated command prompt or powershell and cd into "C:\Program Files (x86)\Cntlm". CNTLM needs your credentials as a hash. Therefore you have to generate your hash. Run cntlm.exe with the -H switch. When prompted for your password, type it in. The result is a list of hashes for the different authentication methods.

Copy the line starting with PassNTLMv2 and paste it in the cntlm.ini.

Save the ini file.

Next step: Define your upstream proxy.

This can be a bit tricky to figure out if you're on windows and the admins applied some group policies.

The most obvious way to figure out what you proxy server is: Ask the admin!

If there is no admin available ;) , look into the Internet Properties (hint inetcpl.cpl from the command line). Connections/Lan settings will show you the details.
But what if there is no proxy defined but the check-box "Automatically detect settings" is selected? Now it's getting tricky...

The advanced solution is to look in your registry for HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings\Wpad and the value of WpadDetectedUrl. Open the URL in a browser and analyze the JavaScript. Somewhere should be a return "PROXY 10.11.12.13" statement. That IP is hopefully your proxy.

An easier way is to look at your network connections. Again from your elevated command line or powershell type netstat | find ":8080" (or the powershell equivalent netstat | select-string :8080). Most proxy installations listen on port 8080 so this should give you the proxy.

Paste your proxy ip and port into cntlm.ini and save.

Now you can try to start the cntlm service: net start cntlm. If there are no errors, your local proxy is up and running.

The next step is to configure git to use the proxy.

CNTLM listens on port 3128 so we need to edit the (global) git config accordingly:

git config --global http.proxy http://localhost:3128
git config --global https.proxy http://localhost:3128

git is now ready to work. Happy coding!

Some additional notes:

Your are NOT circumventing your corporate proxy. Everything runs as usual through the upstream proxy.

Make sure you don't open your proxy for incoming connections (gateway mode). Otherwise anyone can access the internet with your credentials.

Your credentials live as a hash inside cntlm.ini. Make sure to restrict access to this file so that no one can grab your hashed credentials.

Make sure to update your hash when changing your password. Otherwise your account might get locked.