Skip to content

Commit 1b63a99

Browse files
mjcheethammjcheetham
committed
docs: add NTLM and Kerberos documentation page
Add documentation around the Windows Integrated Authentication protocols: NTLM and Kerberos (via GSS-Negotiate). Signed-off-by: Matthew John Cheetham <mjcheetham@outlook.com>
1 parent 09ddfae commit 1b63a99

File tree

3 files changed

+144
-0
lines changed

3 files changed

+144
-0
lines changed

‎docs/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ The following are links to GCM user support documentation:
1414
- [Azure Managed Identities and Service Principals][gcm-misp]
1515
- [GitLab support][gcm-gitlab]
1616
- [Generic OAuth support][gcm-oauth]
17+
- [NTLM and Kerberos authentication][gcm-ntlm-kerberos]
1718

1819
[gcm-azure-tokens]: azrepos-users-and-tokens.md
1920
[gcm-config]: configuration.md
@@ -27,3 +28,4 @@ The following are links to GCM user support documentation:
2728
[gcm-net-config]: netconfig.md
2829
[gcm-oauth]: generic-oauth.md
2930
[gcm-usage]: usage.md
31+
[gcm-ntlm-kerberos]: ntlm-kerberos.md

‎docs/img/ntlm-warning.png‎

54.4 KB
Loading

‎docs/ntlm-kerberos.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
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

Comments
 (0)