BITS supports Basic authentication, Passport authentication, and several challenge/response authentication schemes. If the server or proxy requires user authentication, use the IBackgroundCopyJob2::SetCredentials method to specify the user's credentials. BITS uses the CryptoAPI to protect the credentials.
BITS 1.2 and earlier: The SetCredentials method is not available.
Basic authentication requires the user name and password to be embedded in the URL, for example, HTTP://username:password@server/path/file. Because the user name and password are clear text, an administrator can enumerate the jobs in the transfer queue and see the user name and password. The user name and password can also be seen by a network monitor program that is on the same physical network link as the client and server (unless you use HTTPS).
Instead of embedding the user name and password in the URL, you should use the SetCredentials method to specify the user name and password for Basic authentication. This prevents others from viewing the credentials. If you specify credentials in both places, BITS uses the user name and password from the URL.
For Passport authentication, BITS supports explicit credentials only, not implicit credentials tied to the account.
For challenge/response authentication, BITS impersonates the user and uses Snego to determine which challenge/response authentication to use, such as NTLM or the Kerberos protocol. For a list of challenge/response schemes that BITS supports, see BG_AUTH_SCHEME.
BITS jobs can fail if the virtual directory on the server has anonymous authentication and another authentication scheme enabled and if ACLs protect the virtual directory or download files. For example, a job fails with "access denied" if the virtual directory has anonymous and integrated authentication enabled and the file contains an ACL that allows only Ben to read the file. This occurs because the virtual directory allows anonymous access, so IIS does not explicitly authenticate Ben (Ben's credentials are not used to access the file and access is denied).
To use the user's implicit (logon) credentials for NTLM or Kerberos authentication, call the IBackgroundCopyJob2::SetCredentials method and set the UserName and Password members of the BG_BASIC_CREDENTIALS structure to NULL. If you specify implicit credentials for a proxy, BITS will also use the implicit credentials for server authentication unless you specify explicit server credentials.
For additional information for services, see Service Accounts and BITS.
You could also change the LMCompatibilityLevel or UseLMCompat registry value; however, you should change these values only if you have an existing application that cannot be changed to call the SetCredentials method.
BITS will use implicit credentials for authentication if the LMCompatibilityLevel registry value is two or greater, and you have not called the SetCredentials method. The full path to the LMCompatibilityLevel registry value is HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\LSA\LmCompatibilityLevel.
Note that changing the LMCompatibilityLevel registry value can affect other applications and services running on the computer. For more information about using the LMCompatibilityLevel registry value, see KB147706.
If setting the LMCompatibilityLevel registry value is an issue, you can create the UseLMCompat registry value under HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\BITS. The registry value is a DWORD. The following table lists the possible values for UseLMCompat:
|0||BITS will send implicit credentials whenever the server prompts for NTLM or Kerberos credentials.|
|1||BITS will send implicit credentials only if the client computer's LMCompatibilityLevel registry value is greater than or equal to 2.|
Prior to BITS 1.5: Not supported
|2||BITS will send implicit credentials only if the application called the SetCredentials method. |
Prior to BITS 2.0: Not supported
BITS will use the following default values for the UseLMCompat registry value if the registry value does not exist:
|Windows XP with Service Pack 1 (SP1)||0|
|Windows XP with Service Pack 2 (SP2)||1|
|Windows XP with Service Pack 3 (SP3)||1|
|Windows Server 2003||1|
|Windows Server 2003 R2||1|
|Windows Server 2008||2|
BITS 1.2 and earlier: BITS uses implicit credentials for NTLM or Kerberos authentication. If you wrote an application based on BITS 1.0 or 1.2, the same application may not run using later versions of BITS if the LMCompatibilityLevel value is less than two. Note that the default LMCompatibilityLevel value for Windows XP is zero.
In secure client/server communication, clients and servers can use digital certificates to mutually authenticate each other. BITS automatically supports certificate-based server authentication for secure HTTP transports. To provide BITS the client certificate needed for mutual authentication, call either the IBackgroundCopyJobHttpOptions::SetClientCertificateByID or IBackgroundCopyJobHttpOptions::SetClientCertificateByName method.
When a website accepts but does not require an SSL client certificate, and the BITS job does not specify a client certificate, the job will fail with ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED (0x80072f0c).
Prior to Windows Vista: BITS supports certificate-based server authentication for secure HTTP transports, but certificate-based client authentication is not supported.
If you are using BITS in an environment that requires proxy authentication while running as an account without usable NTLM or Kerberos credentials in the machine's network domain, you must take extra steps to authenticate properly by using the credentials of another user account that does have credentials on the domain. This is a typical scenario when your BITS code is running as a system service such as LocalService, NetworkService, or LocalSystem, as those accounts do not have usable NTLM or Kerberos credentials.
The proxy detection logic used in BITS does the following when a network helper token (BG_TOKEN_NETWORK) is set:
- If IBackgroundCopyJob::SetProxySettings was called with BG_JOB_PROXY_USAGE_PRECONFIG, then detect local IE proxy settings using job owner token context impersonation via WinHttpGetIEProxyConfigForCurrentUser.
- If IBackgroundCopyJob::SetProxySettings was called with BG_PROXY_USAGE_AUTODETECT or if the IE settings from the BG_JOB_PROXY_USAGE_PRECONFIG case specify auto-detect or an auto-config URL, then conduct auto-proxy detection, or Web Proxy Autodiscovery Protocol (WPAD), using helper token impersonation via WinHttpGetProxyForUrl.
After that, helper token impersonation is used for proxy or server authentication throughout.
This means that the correct user identity (the helper token's identity) is used for network-based proxy detection (WPAD) and for proxy authentication, but that the actual detection of local (IE) proxy settings is always done using the job owner's token, even when a helper token is configured. This behavior is by design in BITS, but there is a workaround you can use when necessary for your situation.
- Impersonate the user account you're using for NTLM/Kerberos credentials.
- Retrieve the user account's IE proxy settings by calling WinHttpGetIEProxyConfigForCurrentUser.
- Revert impersonation.
- Call the BITS job's SetCredentials method with BG_AUTH_SCHEME_NEGOTIATE, UserName set to NULL, Password set to NULL, and Target set to BG_AUTH_TARGET_PROXY. This causes the user account's implicit credentials to be used for NTLM and Kerberos authentication with the proxy and server.
- If step 2 yielded any user-specific proxy settings (i.e. lpszProxy or lpszProxyBypass are not NULL), set the corresponding job settings manually, using SetProxySettings with the BG_JOB_PROXY_USAGE_OVERRIDE setting.
- If step 2 did not yield any user-specific proxy settings, call SetProxySettings with BG_JOB_USAGE_PRECONFIG.
- QueryInterface for IBitsTokenOptions.
- Impersonate the user account again.
- Call SetHelperToken.
- Call SetHelperTokenFlags with BG_TOKEN_NETWORK.
- Revert impersonation.
- Continue job setup.
- Call Resume on the job.
The following table shows the authentication requests that BITS does not support.
|Scenario not supported||Windows XP||Windows Server 2003|
|Passport authentication on the server when the proxy requires authentication (using the HTTPS protocol).||Not supported||Not supported|
|Passport authentication when the auto-detect proxy setting is set.||Not supported||Not supported|
|Any authentication scheme on the server when the proxy requires Digest authentication.||Not supported||Not supported|
|Negotiate authentication on the server when the proxy requires Basic authentication.||Not supported|
|Using HTTPS when the proxy requires Digest authentication.||Not supported|