For Developers‎ > ‎Design Documents‎ > ‎

HTTP authentication

As specified in RFC 2617, HTTP supports authentication using the WWW-Authenticate request headers and the Authorization response headers (and the Proxy-Authenticate and Proxy-Authorization headers for proxy authentication).

Supported authentication schemes

Chrome supports four authentication schemes: Basic, Digest, NTLM, and Negotiate. Basic, Digest, and NTLM are supported on all platforms by default. Negotiate is supported on all platforms except ChromeOS by default.

The Basic and Digest schemes are specified in RFC 2617. NTLM is a Microsoft proprietary protocol. The Negotiate (or SPNEGO) scheme is specified in RFC 4559 and can be used to negotiate multiple authentication schemes, but typically defaults to either Kerberos or NTLM.

The defaults for supported schemes may be overridden using the --auth-schemes command line flag:
  --auth-schemes="digest,ntlm,negotiate" will disable basic, for example.

Choosing an authentication scheme

When a server or proxy accepts multiple authentication schemes, our network stack selects the authentication scheme with the highest score:
    • Basic: 1
    • Digest: 2
    • NTLM: 3
    • Negotiate: 4
The Basic scheme has the lowest score because it sends the username/password unencrypted to the server or proxy.

So we choose the most secure scheme, and we ignore the server or proxy's preference, indicated by the order in which the schemes are listed in the WWW-Authenticate or Proxy-Authenticate response headers. This could be a source of compatibility problems because MSDN documents that "WinInet chooses the first method it recognizes." Note: In IE7 or later, WinInet chooses the first non-Basic method it recognizes.

Integrated Authentication

With Integrated Authentication, Chrome can authenticate the user to an Intranet server or proxy without prompting the user for a username or password. It does this by using cached credentials which are established when the user initially logs in to the machine that the Chrome browser is running on. Integrated Authentication is supported for Negotiate and NTLM challenges only.

Due to potential attacks, Integrate Authentication is only enabled when Chrome receives an authentication challenge from a proxy, or when it receives a challenge from a server which is in the permitted list.

This list is passed in to Chrome using a comma-separated list of URLs to Chrome via the "auth-server-whitelist" command-line switch.  For example, you can pass in:
--auth-server-whitelist="*example.com,*foobar.com,*baz"

which would tell chrome that any URL ending in either 'example.com', 'foobar.com' or 'baz' is in the permitted list.  Without the '*' prefix, the URL has to match exactly.

In Windows only, if the command-line switch is not present, the permitted list consists of those servers in the Local Machine or Local Intranet security zone (for example, when the host in the URL includes a "." character it is outside the Local Intranet security zone), which is the behavior present in IE. Treating servers that bypass proxies as being in the intranet zone is not currently supported.

If a challenge comes from a server outside of the permitted list, the user will need to enter the username and password.

Kerberos SPN generation

When a server or proxy presents Chrome with a Negotiate challenge, Chrome tries to generate a Kerberos SPN (Service Principal Name) based on the host and port of the original URI. Unfortunately, the server does not indicate what the SPN should be as part of the authentication challenge, so Chrome (and other browsers) have to guess what it should be based on standard conventions. 

The default SPN is: HTTP/<host name>, where <host name> is the canonical DNS name of the server. This mirrors the SPN generation logic of IE and Firefox.

The SPN generation can be customized via command line flags. 

If --disable-auth-negotiate-cname-lookup is specified, the original hostname in the URL is used rather than the canonical name.
If --enable-auth-negotiate-port is specified, the port is appended to the SPN if it is a non-standard (not 80 or 443) port.

For example, assume that an intranet has a DNS configuration like

auth-a.example.com       IN CNAME auth-server.example.com
auth-server.example.com  IN A     10.0.5.3

URL                                 Default SPN                      --disable-auth-negotiate-cname-lookup   --enable-auth-negotiate-port

http://auth-a                       HTTP/auth-server.example.com     HTTP/auth-a                             HTTP/auth-server.example.com
https://auth-a                      HTTP/auth-server.example.com     HTTP/auth-a                             HTTP/auth-server.example.com
http://auth-a:80                    HTTP/auth-server.example.com     HTTP/auth-a                             HTTP/auth-server.example.com
https://auth-a:443                  HTTP/auth-server.example.com     HTTP/auth-a                             HTTP/auth-server.example.com
http://auth-a:4678                  HTTP/auth-server.example.com     HTTP/auth-a                             HTTP/auth-server.example.com:4678
http://auth-a.example.com           HTTP/auth-server.example.com     HTTP/auth-a.example.com                 HTTP/auth-server.example.com
http://auth-server                  HTTP/auth-server.example.com     HTTP/auth-server                        HTTP/auth-server.example.com
http://auth-server.example.com      HTTP/auth-server.example.com     HTTP/auth-server.example.com            HTTP/auth-server.example.com

Kerberos Delegation (Forwardable Tickets)

Some services require delegation of the users identity (for example, an IIS server accessing a MSSQL database). By default, Chrome does not allow this. You can specify --auth-negotiate-delegate-whitelist to enable it for the servers. 

Delegation does not work for proxy authentication.

Negotiate external libraries

On Windows, Negotiate is implemented using the SSPI libraries and depends on code in secur32.dll. 

On other platforms, Negotiate is implemented using the system GSSAPI libraries. The first time a Negotiate challenge is seen, Chrome tries to dlopen one of several possible shared libraries. If it is unable to find an appropriate library, Chrome remembers for the session and all Negotiate challenges are ignored for lower priority challenges. 

If --gssapi-library-name=<gss library path> is specified on the command line, it is used. (Introduced in Chrome 9)

Otherwise, Chrome tries to dlopen/dlsym each of the following fixed names in the order specified:
    • OSX: libgssapi_krb5.dylib
    • Linux: libgssapi_krb5.so.2, libgssapi.so.4, libgssapi.so.1
ChromeOS follows the Linux behavior, but does not have a system gssapi library, so all Negotiate challenges are ignored.

Remaining work
  • Support NTLMv2 on Mac and Linux. Our portable NTLM code supports NTLMv1 only.
  • Support GSSAPI on Windows [for MIT KfW or Heimdal]
  • Warn about Basic authentication scheme over unencrypted channels.
Questions?

Please feel free to send mail to cbentzel@chromium.org

Comments