|
| 1 | +# NTLM and Kerberos Authentication |
| 2 | + |
| 3 | +## Background |
| 4 | + |
| 5 | +NTLM and Kerberos are two authentication protocols that are commonly used in |
| 6 | +Windows environments. |
| 7 | + |
| 8 | +In Git Credential Manager (GCM), we refer to these protocols under the umbrella |
| 9 | +term "Windows Integrated Authentication". |
| 10 | + |
| 11 | +### NTLM |
| 12 | + |
| 13 | +[NTLM (NT LAN Manager)][ntlm-wiki] is a challenge-response authentication |
| 14 | +protocol used in various Microsoft network protocols, such as |
| 15 | +[SMB file sharing][smb-docs]. |
| 16 | + |
| 17 | +> [!CAUTION] |
| 18 | +> NTLM is now considered _**insecure**_ due to weak cryptographic algorithms and |
| 19 | +> vulnerabilities to various attacks, such as pass-the-hash and relay attacks. |
| 20 | +> As such, it is not recommended for use in modern applications. |
| 21 | +> |
| 22 | +> There are several versions of NTLM, with NTLMv2 being the latest, however |
| 23 | +> **all versions** are considered weak by modern security standards. |
| 24 | +> |
| 25 | +> Microsoft lists [NTLM as a deprecated protocol][ntlm-deprecated] and has |
| 26 | +> removed NTLMv1 from Windows as of Windows 11 build 24H2 / Server 2025. |
| 27 | +
|
| 28 | +NTLM is advertised by HTTP servers using the `WWW-Authenticate: NTLM` header. |
| 29 | +When a client receives this header, it can respond with an NTLM authentication |
| 30 | +message to prove its identity. |
| 31 | + |
| 32 | +### Kerberos |
| 33 | + |
| 34 | +[Kerberos][kerberos-wiki], on the other hand, is a more secure and robust |
| 35 | +authentication protocol that uses tickets to authenticate users and services. |
| 36 | +It is the recommended authentication protocol for Windows domains and is widely |
| 37 | +used in enterprise environments. |
| 38 | + |
| 39 | +Unlike NTLM, Kerberos is typically not directly advertised by HTTP servers, but |
| 40 | +is instead advertised using "SPNEGO" and the `WWW-Authenticate: Negotiate` |
| 41 | +header. |
| 42 | + |
| 43 | +#### GSS-API Negotiate and SPNEGO |
| 44 | + |
| 45 | +Kerberos (or NTLM) authentication is typically initially established using the |
| 46 | +[GSS-API][gssapi-wiki] ([RFC 2743][gssapi-rfc]) negotiation mechanism |
| 47 | +["SPNEGO"][spnego-wiki] ([RFC 4178][spnego-rfc]). SPNEGO allows the client and |
| 48 | +server to agree on which authentication protocol to use (Kerberos or NTLM) based |
| 49 | +on their capabilities. Typically Kerberos is preferred if both the client and |
| 50 | +server support it, with NTLM acting as a fallback. |
| 51 | + |
| 52 | +## Built-in Support in Git |
| 53 | + |
| 54 | +Git provides built-in support for NTLM and Kerberos authentication through the |
| 55 | +use of [libcurl][libcurl], which is the underlying library used by Git for HTTP |
| 56 | +and HTTPS communications. When Git is compiled with libcurl support, it can |
| 57 | +leverage the authentication mechanisms provided by libcurl, including NTLM and |
| 58 | +Kerberos. |
| 59 | + |
| 60 | +On Windows, Git can use the native Windows [SSPI][sspi-wiki] (Security Support |
| 61 | +Provider Interface) to perform NTLM and Kerberos authentication. This allows Git |
| 62 | +to integrate seamlessly with the Windows authentication infrastructure. |
| 63 | + |
| 64 | +> [!NOTE] |
| 65 | +> As of Git for Windows version 2.XX.X, **NTLM support is disabled by default**. |
| 66 | +> Kerberos support _remains enabled_. |
| 67 | +
|
| 68 | +### Re-enabling NTLM Support |
| 69 | + |
| 70 | +You can re-enable NTLM support in Git for Windows for a particular remote by |
| 71 | +setting Git config option [`http.<url>.allowNTLMAuth`][ntlm-config] to `true`. |
| 72 | +For example, to enable NTLM authentication for `https://example.com`, you would |
| 73 | +run the following command: |
| 74 | + |
| 75 | +```shell |
| 76 | +git config --global http.https://example.com.allowNTLMAuth true |
| 77 | +``` |
| 78 | + |
| 79 | +> [!WARNING] |
| 80 | +> Enabling NTLM authentication may expose you to security risks, as NTLM is |
| 81 | +> considered insecure. It is recommended to use Kerberos authentication where |
| 82 | +> possible, and to only use NTLM with trusted servers in secure environments. |
| 83 | +
|
| 84 | +> [!WARNING] |
| 85 | +> Only ever use NTLM authentication over secure connections (i.e., HTTPS) to |
| 86 | +> protect against eavesdropping and man-in-the-middle attacks. |
| 87 | +
|
| 88 | +When using GCM with a remote that supports NTLM authentication, GCM will warn |
| 89 | +you if NTLM authentication is not enabled in Git but the remote server |
| 90 | +advertises NTLM support. |
| 91 | + |
| 92 | +![GCM warning prompt that NTLM is disabled inside of Git][ntlm-warning-image] |
| 93 | + |
| 94 | +* Selecting "Just this time" will continue with NTLM authentication, but only |
| 95 | + for the current operation. The next time you interact with that remote, you |
| 96 | + will be prompted again. |
| 97 | + |
| 98 | +* Selecting "Always for this remote" will set the `http.<url>.allowNTLMAuth` |
| 99 | + configuration option to `true` for that remote, and continue with NTLM |
| 100 | + authentication. |
| 101 | + |
| 102 | +* Selecting "No" will prompt for a basic username/password credential, and Git's |
| 103 | + NTLM authentication support will remain disabled. If the remote server only |
| 104 | + supports NTLM then authentication will fail. |
| 105 | + |
| 106 | +### Seamless Authentication |
| 107 | + |
| 108 | +When using NTLM or Kerberos authentication with Git on Windows, it is possible |
| 109 | +to achieve seamless authentication without prompting for credentials. This is |
| 110 | +because Git can leverage the existing Windows user credentials to authenticate |
| 111 | +with the server. |
| 112 | + |
| 113 | +This means that if you are logged into your Windows account, Git can use those |
| 114 | +credentials to authenticate with the remote server automatically, without |
| 115 | +prompting you for a username or password. |
| 116 | + |
| 117 | +This feature is enabled by default in Git. To disable this behavior, you can set |
| 118 | +the [`http.<url>.emptyAuth`][emptyauth] configuration option to `false`. For |
| 119 | +example, to disable seamless authentication for `https://example.com`, you would |
| 120 | +run the following command: |
| 121 | + |
| 122 | +```shell |
| 123 | +git config --global http.https://example.com.emptyAuth false |
| 124 | +``` |
| 125 | + |
| 126 | +If you disable seamless authentication, Git will prompt you for credentials |
| 127 | +when accessing a remote that advertises NTLM or Kerberos support rather than |
| 128 | +using the current Windows user's credentials. |
| 129 | + |
| 130 | +[ntlm-wiki]: https://en.wikipedia.org/wiki/NTLM |
| 131 | +[kerberos-wiki]: https://en.wikipedia.org/wiki/Kerberos_(protocol) |
| 132 | +[smb-docs]: https://learn.microsoft.com/en-gb/windows/win32/fileio/microsoft-smb-protocol-and-cifs-protocol-overview |
| 133 | +[ntlm-deprecated]: https://learn.microsoft.com/en-us/windows/whats-new/deprecated-features |
| 134 | +[ntlm-config]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpallowNTLMAuth |
| 135 | +[gssapi-rfc]: https://datatracker.ietf.org/doc/html/rfc2743 |
| 136 | +[gssapi-wiki]: https://en.wikipedia.org/wiki/GSSAPI |
| 137 | +[spnego-rfc]: https://datatracker.ietf.org/doc/html/rfc4178 |
| 138 | +[spnego-wiki]: https://en.wikipedia.org/wiki/SPNEGO |
| 139 | +[libcurl]: https://curl.se/libcurl/ |
| 140 | +[sspi-wiki]: https://en.wikipedia.org/wiki/Security_Support_Provider_Interface |
| 141 | +[emptyauth]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpemptyAuth |
| 142 | +[ntlm-warning-image]: img/ntlm-warning.png |
0 commit comments