NTLM Over HTTP Protocol Specification
NTLM Over HTTP Protocol Specification
NTLM Over HTTP Protocol Specification
No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation.
Patents. Microsoft has patents that may cover your implementations of the technologies
described in the Open Specifications. Neither this notice nor Microsoft's delivery of the
documentation grants any licenses under those or any other Microsoft patents. However, a given
Open Specification may be covered by Microsoft's Open Specification Promise (available here:
http://www.microsoft.com/interop/osp) or the Community Promise (available here:
http://www.microsoft.com/interop/cp/default.mspx). If you would prefer a written license, or if
the technologies described in the Open Specifications are not covered by the Open Specifications
Promise or Community Promise, as applicable, patent licenses are available by contacting
[email protected].
Trademarks. The names of companies and products contained in this documentation may be
covered by trademarks or similar intellectual property rights . This notice does not grant any
licenses under those rights.
Reservation of Rights. All other rights are reserved, and this notice does not grant any rights
other than specifically described above, whether by implication, estoppel, or otherwise.
Tools. The Open Specifications do not require the use of Microsoft programming tools or
programming environments in order for you to develop an implementation. If you have access to
Microsoft programming tools and environments you are free to take advantage of them. Certain
Open Specifications are intended for use in conjunction with publicly available standard
specifications and network programming art, and assumes that the reader either is familiar with the
aforementioned material or has immediate access to it.
1 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
Revision Revision
Date History Class Comments
10/26/2007 2.0 Major Converted document to unified format and updated the
technical content.
2 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
2 Messages .......................................................................................................................... 8
2.1 Transport .......................................................................................................................8
2.2 Message Syntax .............................................................................................................8
2.2.1 WWW -Authenticate Response Header.......................................................................8
2.2.2 Authorization Request Header ..................................................................................8
2.2.3 Proxy-Authenticate Response Header .......................................................................9
2.2.4 Proxy-Authorization Request Header.........................................................................9
3 Protocol Details.............................................................................................................. 11
3.1 Common Details........................................................................................................... 11
3.1.1 Abstract Data Model ............................................................................................... 11
3.1.2 Timers ................................................................................................................... 11
3.1.3 Initialization ........................................................................................................... 11
3.1.4 Higher-Layer Triggered Events ............................................................................... 11
3.1.5 Message Processing Events and Sequencing Rules .................................................. 11
3.1.5.1 Unexpected Messages ...................................................................................... 11
3.1.6 Timer Events.......................................................................................................... 11
3.1.7 Other Local Events ................................................................................................. 11
3.2 Server Details .............................................................................................................. 11
3.2.1 Abstract Data Model ............................................................................................... 11
3.2.2 Timers ................................................................................................................... 12
3.2.3 Initialization ........................................................................................................... 12
3.2.4 Higher-Layer Triggered Events ............................................................................... 12
3.2.5 Message Processing Events and Sequencing Rules .................................................. 12
3.2.6 Timer Events.......................................................................................................... 12
3.2.7 Other Local Events ................................................................................................. 12
3.3 Client Details................................................................................................................ 12
3.3.1 Abstract Data Model ............................................................................................... 12
3.3.2 Timers ................................................................................................................... 12
3.3.3 Initialization ........................................................................................................... 12
3.3.4 Higher-Layer Triggered Events ............................................................................... 12
3.3.5 Message Processing Events and Sequencing Rules .................................................. 12
3.3.6 Timer Events.......................................................................................................... 13
3.3.7 Other Local Events ................................................................................................. 13
3.4 Proxy Details................................................................................................................ 13
3.4.1 Abstract Data Model ............................................................................................... 13
3.4.2 Timers ................................................................................................................... 13
3 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
5 Security........................................................................................................................... 17
5.1 Security Considerations for Impleme nters..................................................................... 17
5.2 Index of Security Parameters ....................................................................................... 17
8 Index............................................................................................................................... 20
4 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
Support for NTLM authentication is as specified in [RFC4559], using native NTLM Authentication
Protocol (as specified in [MS-NLMP]) data units instead of encoded tokens (as specified in
[RFC4178]). The tokens are still transmitted using base64 encoding. This document calls out the
differences in the Microsoft implementation from what is specified in [RFC4559], where applicable.
1.1 Glossary
Backus-Naur Form (BNF): Used to describe grammars. Also referred to as "Augmented BNF"
in [RFC2616] section 2.1.
MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as
described in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or
SHOULD NOT.
We conduct frequent surveys of the normative references to assure their continued availability. If
you have any issue with finding a normative reference, please contact [email protected]. We
will assist you in finding the relevant information. Please check the archive site,
http://msdn2.microsoft.com/en-us/library/E4BD6494-06AD-4aed-9823-445E921C9624, as an
additional source.
[MS-NLMP] Microsoft Corporation, "NT LAN Manager (NTLM) Authentication Protocol Specification",
July 2006.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requireme nt Levels", BCP 14, RFC
2119, March 1997, http://www.ietf.org/rfc/rfc2119.txt
[RFC2616] Fielding, R., Gettys, J., Mogul, J., et al., "Hypertext Transfer Protocol -- HTTP/1.1", RFC
2616, June 1999, http://www.ietf.org/rfc/rfc2616.txt
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and
Stewart, L., "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999,
http://www.ietf.org/rfc/rfc2617.txt
5 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
[RFC4559] Jaganathan, K., Zhu, L., and Brezak, J., "SPNEGO -based Kerberos and NTLM HTTP
Authentication in Microsoft Windows", RFC 4559, June 2006, http://www.ietf.org/rfc/rfc4559.txt
None.
The NTLM over HTTP Protocol authentication variant is similar to the SPNEGO HTTP (as specified in
[RFC4559]) authentication mechanism. Both are used to authenticate a Web client to a Web server.
Although SPNEGO HTTP (as specified in [RFC4559]) works with both Kerberos and NTLM
authentication, the NTLM over HTTP Protocol authentication variant only works with NTLM. The
Kerberos protocol is not supported.
NTLM over HTTP Protocol authentication assumes the following in addition to any assumptions
specified in [MS-NLMP].
1. The Web server is operating in an environment with a database of user identities, and the NT
LAN Manager (NTLM) Authentication Protocol, as specified in [MS-NLMP], is available to
authenticate those users.
2. The Web client has implemented the NT LAN Manager (NTLM) Authentication Protocol, as
specified in [MS-NLMP], so that it can participate in user authentication to the Web server.
NTLM HTTP authentication is used in environments where SPNEGO -based Kerberos and NTLM HTTP
authentication, as specified in [RFC4559], are not available, and the Web client and server support
NTLM authentication, as specified in [MS-NLMP].
Versioning and capability negotiation is handled by the HTTP protocols specified in [RFC2617] (for
more information, see [RFC2616]). This protocol has no additional versioning or capability
negotiation.
None.
6 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
7 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
2.1 Transport
NTLM over HTTP Protocol messages are carried in the HTTP authentication exchanges as
authentication data (auth-data), as specified in [RFC4559] sections 4.1 and 4.2.
The use of NTLM over HTTP Protocol authentication is indicated by an HTTP authentication scheme
(auth-scheme) NTLM. The authentication parameters (auth-params) that are exchanged are
base64-encoded messages. For more details about auth-scheme and auth-params, see [RFC2617]
section 1.2.
If the server receives a request for an access -protected object and an acceptable Authorization
Request Header has not been sent, the server MUST respond with a "401 Unauthorized" status code
and a WWW -Authenticate Response Header, per the framework in [RFC2616]. The initial WWW -
Authenticate Response Header MUST NOT carry any auth-data. For more details about the text in
this section, see [RFC2616], and specifically for the 401 status code, see [RFC2616] section 10.4.2.
ntlm-data
Upon receipt of the response containing a WWW -Authenticate header from the server, the client is
expected to retry the HTTP request with the authorization header, per the framework in [RFC2616]
in the following.
ntlm-data
8 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
Any return code other than a client error HTTP 401 status code (for more information, see
[RFC2616] section 10.4.2), represents successful authentication. If the client is not ab le to access
the requested resource and the response status code is not HTTP 401, the problem is HTTP protocol-
specific (for more information, see [RFC2616] section 10).
If the client must authenticate itself to a proxy and an acceptable proxy-authorization header has
not been sent, the proxy MUST respond with a "407 Proxy Authentication Required" status code (for
more information, see [RFC2616] section 10.4.8) and a "Proxy-Authenticate" header, per the
framework in [RFC2616]. The initial proxy-authenticate header MUST NOT carry any auth-data.
The meanings of the values of the directives used above are as follows:
ntlm-data
Upon receipt of the response containing a proxy-authenticate header from the proxy, the client is
expected to retry the HTTP request with the proxy-authorization header, per the framework in
[RFC2616].
The meanings of the values of the directives used above are as follows:
ntlm-data
9 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
10 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
3.1.2 Timers
None.
3.1.3 Initialization
None.
None.
The WWW -Authenticate header is only sent from the server. The Authorization header is only sent
by the client. (For details, see [RFC2617] and also see [RFC2616] sections 14.47 and 14.8.) Clients,
servers, and proxys MUST be compliant with [RFC2617] and [RFC2616].
The Proxy-Authenticate header is only sent from the proxy. The Proxy-Authorization header is only
sent by the client. (For more information, see [RFC2617] and [RFC2616] sections 14.33 and 14.34.)
Clients, servers, and proxys MUST be compliant with [RFC2617] and [RFC2616].
If the server receives an unexpected message, it sends an HTTP 401 message to the client.
If the client receives an unexpected message, it does not send a new request to the server.
None.
11 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
None.
3.2.3 Initialization
None.
None.
The WWW -Authenticate header is only sent from the server. The Authorization header is only sent
by the client. (For more information, see [RFC2617] and [RFC2616] sections 14.7 and 14.8.)
Servers MUST be compliant with [RFC2617] and [RFC2616].
The Proxy-Authenticate header is only sent from the proxy. The Proxy-Authorization header is only
sent by the client. (For more information, see [RFC2617] and [RFC2616] sections 14.33 and 14.34.)
Servers MUST be compliant with [RFC2617] and [RFC2616].
None.
3.3.2 Timers
None.
3.3.3 Initialization
None.
None.
The WWW -Authenticate header is only sent from the server. The Authorization header is only sent
by the client. (For more information, see [RFC2617] and [RFC2616] sections 14.7 and 14.8.)
Servers MUST be compliant with [RFC2617] and [RFC2616].
12 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
None.
3.4.2 Timers
None.
3.4.3 Initialization
None.
None.
The WWW -Authenticate header is only sent from the server. The Authorization header is only sent
by the client. (For more information, see [RFC2617] and [RFC2616] sections 14.7 and 14.8.)
Servers MUST be compliant with [RFC2617] and [RFC2616].
The Proxy-Authenticate header is only sent from the proxy. The Proxy-Authorization header is only
sent by the client. (For more information, see [RFC2617] and [RFC2616] sections 14.33 and 14.34.)
Servers MUST be compliant with [RFC2617] and [RFC2616].
None.
13 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
This scenario shows the messages exchanged when a Web client requests an access -protected
document from a Web server using a GET method request at the URL:
http://www.nowhere.org/dir/index.html.
C: GET dir/index.html
The first time the client requests the document, no Authorization header is sent; so the server
responds with the following.
The client obtains the local user credentials by using the [MS-NLMP] security package and then
generates a new GET request to the server. The request contains an Authorization header with an
NTLM NEGOTIATE_MESSAGE (as specified in [MS-NLMP] section 2.2.1.1) in ntlm-data.
C: GET dir/index.html
C: Authorization: NTLM tESsBmE/yNY3lb6a0L6vVQEZNqwQn0s8Unew
The server decodes the ntlm-data that is contained in the auth-data2 base64-encoded data and
passes this to its implementation of [MS-NLMP]. If the server accepts this authentication data from
the client, it responds with an HTTP 401 code (for more information, see [RFC2616] section 10.2)
and a WWW -Authenticate header with an NTLM CHALLENGE_MESSAGE (as specified in [MS-NLMP]
section 2.2.1.2) in ntlm-data.
The client decodes the ntlm-data that is contained in the auth-data base64-encoded data and
passes this to its implementation of [MS-NLMP]. If this authentication data is valid, the client
responds by reissuing the GET request with an Authorization header that contains an NTLM
AUTHENTICATE_MESSAGE (as specified in [MS-NLMP] section 2.2.1.3) in ntlm-data.
C: GET dir/index.html
C: Authorization: NTLM kGaXHz6/owHcWRlvGFk8ReUZKHo=QEZNqwQn0s8U
The server decodes the ntlm-data that is contained in the auth-data2 base64-encoded data and
passes this to its implementation of [MS-NLMP]. If the server accepts this authentication data from
the client, it responds with an HTTP 2xx code (for more information, see [RFC2616] section 10.2)
indicating success. The requested content is also included in the server response.
Note The base64 values used previously are for illustrative purposes only and do not represent
valid base64-encoded NTLM messages.
14 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
This scenario shows the messages that are exchanged when a Web client requests an access -
protected document from a proxy using a GET method request at the URL:
http://www.nowhere.org/dir/index.html.
C: GET dir/index.html
The first time the client requests the document, no Proxy-Authorization header is sent; so the proxy
responds with the following.
The client obtains the local user credentials using the [MS-NLMP] security package and then
generates a new GET request to the proxy. The request contains a Proxy-Authorization header with
an NTLM NEGOTIATE_MESSAGE (as specified in [MS-NLMP] section 2.2.1.1) in ntlm-data.
C: GET dir/index.html
C: Proxy-Authorization: NTLM tESsBmE/yNY3lb6a0L6vVQEZNqwQn0s8Unew
The proxy decodes the ntlm-data that is contained in the auth-data2 base64-encoded data and
passes this to its implementation of [MS-NLMP]. If the proxy accepts this authentication data from
the client, it responds with an HTTP 407 code (for more information, see [RFC2616] section 10.2)
and a Proxy-Authenticate header with an NTLM CHALLENGE_MESSAGE (as specified in [MS-NLMP]
section 2.2.1.2) in ntlm-data.
The client decodes the ntlm-data that is contained in the auth-data base64-encoded data and
passes this to its implementation of [MS-NLMP]. If this authentication data is valid, the client
responds by reissuing the GET request with a Proxy-Authorization header that contains an NTLM
AUTHENTICATE_MESSAGE (as specified in [MS-NLMP] section 2.2.1.3) in ntlm-data.
C: GET dir/index.html
C: Proxy-Authorization: NTLM kGaXHz6/owHcWRlvGFk8ReUZKHo=QEZNqwQn0s8U
The proxy decodes the ntlm-data that is contained in the auth-data2 base64-encoded data and
passes this to its implementation of [MS-NLMP]. If the proxy accepts this authentication data from
the client, it responds with an HTTP 2xx code (for more information, see [RFC2616] section 10.2)
indicating success. The requested content is also included in the proxy response.
15 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
16 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
The NTLM Authentication Protocol (see [MS-NLMP]) does not provide any facilities for mutual
authentication; therefore, server identities cannot be verified. Other security considerations are as
specified in [RFC4559] section 6.
None.
17 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
Exceptions, if any, are noted below. If a service pack number appears with the product version,
behavior changed in that service pack. The new behavior also applies to subsequent service packs of
the product unless otherwise specified.
Unless otherwise specified, any statement of optional behavior in this specification prescribed using
the terms SHOULD or SHOULD NOT implies Windows behavior in accordance with the SHOULD or
SHOULD NOT prescription. Unless otherwise specified, the term MAY implies that Windows does not
follow the prescription.
18 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
19 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
C Local events
client (section 3.1.7 11, section 3.3.7 13)
Capability negotiation 6 proxy (section 3.1.7 11, section 3.4.7 13)
Change tracking 19 server (section 3.1.7 11, section 3.2.7 12)
Client
abstract data model (section 3.1.1 11, section M
3.3.1 12)
higher-layer triggered events (section 3.1.4 11, Message processing
section 3.3.4 12) client (section 3.1.5 11, section 3.3.5 12)
initialization (section 3.1.3 11, section 3.3.3 12) proxy (section 3.1.5 11, section 3.4.5 13)
local events (section 3.1.7 11, section 3.3.7 13) server (section 3.1.5 11, section 3.2.5 12)
message processing (section 3.1.5 11, section Messages
3.3.5 12) syntax 8
sequencing rules (section 3.1.5 11, section 3.3.5 transport 8
12)
timer events (section 3.1.6 11, section 3.3.6 13) N
timers (section 3.1.2 11, section 3.3.2 12)
Normative references 5
D
O
Data model - abstract
client (section 3.1.1 11, section 3.3.1 12) Overview 6
proxy (section 3.1.1 11, section 3.4.1 13)
server (section 3.1.1 11, section 3.2.1 11) P
I R
20 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification
Security
implementer considerations 17
parameter index 17
Sequencing rules
client (section 3.1.5 11, section 3.3.5 12)
proxy (section 3.1.5 11, section 3.4.5 13)
server (section 3.1.5 11, section 3.2.5 12)
Server
abstract data model (section 3.1.1 11, section
3.2.1 11)
examples 14
higher-layer triggered events (section 3.1.4 11,
section 3.2.4 12)
initialization (section 3.1.3 11, section 3.2.3 12)
local events (section 3.1.7 11, section 3.2.7 12)
message processing (section 3.1.5 11, section
3.2.5 12)
sequencing rules (section 3.1.5 11, section 3.2.5
12)
timer events (section 3.1.6 11, section 3.2.6 12)
timers (section 3.1.2 11, section 3.2.2 12)
Standards assignments 7
Syntax 8
Timer events
client (section 3.1.6 11, section 3.3.6 13)
proxy (section 3.1.6 11, section 3.4.6 13)
server (section 3.1.6 11, section 3.2.6 12)
Timers
client (section 3.1.2 11, section 3.3.2 12)
proxy (section 3.1.2 11, section 3.4.2 13)
server (section 3.1.2 11, section 3.2.2 12)
Tracking changes 19
Transport 8
Triggered events - higher-layer
client (section 3.1.4 11, section 3.3.4 12)
proxy (section 3.1.4 11, section 3.4.4 13)
server (section 3.1.4 11, section 3.2.4 12)
Vendor-extensible fields 6
Versioning 6
21 / 21
[MS-NTHT] — v20090924
NTLM Over HTTP Protocol Specification