requests-ntlm2: NTLM Authentication for Requests

Common errors

• ConnectionError: HTTPSConnectionPool(host='...', port=443): Max retries exceeded with url: / (Caused by ProxyError('Cannot connect to proxy.', error('Tunnel connection failed: 407 Proxy Authentication Required',)))

  cause This error typically indicates that your HTTPS proxy requires NTLM authentication for the CONNECT method, but `requests-ntlm2` is not configured to handle it at the `httplib` level.
  fix Use `HttpNtlmAdapter` with `requests.Session` and mount it to handle the proxy authentication: `session = requests.Session(); session.mount('https://', HttpNtlmAdapter(auth=HttpNtlmAuth(username, password)))`.

• ImportError: No module named requests_ntlm2

  cause The `requests-ntlm2` package is either not installed, or Python is trying to import it from a conflicting directory (e.g., a local file named `requests_ntlm2.py`).
  fix Ensure `pip install requests-ntlm2` completed successfully. Check your working directory for any files that might shadow the installed package. If using a virtual environment, activate it.

• requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: ...

  cause This usually means the NTLM credentials provided are incorrect, or the server's NTLM configuration does not accept the client's authentication attempt (e.g., unsupported NTLM compatibility level).
  fix Verify the username (including domain, e.g., `DOMAIN\username`) and password. Experiment with different `NtlmCompatibility` levels if the credentials are known to be correct but still failing.

Warnings

• breaking Version 6.6.0 removed support for Python 2.x. This version and future releases are strictly Python 3.x only. [cite: Changelog for 6.6.0]
  Fix: Ensure your project runs on Python 3.x (3.6+ is recommended as per PyPI classifiers for similar NTLM libraries).
• gotcha By default, `requests-ntlm2` uses NTLM compatibility level 3, which supports NTLMv2 only. Older NTLM environments might require a different compatibility level.
  Fix: Specify the `ntlm_compatibility` parameter when initializing `HttpNtlmAuth`, using constants from `requests_ntlm2.NtlmCompatibility`. For example, `HttpNtlmAuth(username, password, ntlm_compatibility=NtlmCompatibility.LM_AND_NTLMv1_WITH_ESS)` for level 1.
• gotcha For HTTPS CONNECT proxies requiring NTLM authentication, `HttpNtlmAuth` alone is insufficient. You must use `HttpNtlmAdapter` with a `requests.Session`.
  Fix: Mount the `HttpNtlmAdapter` to your `requests.Session` for both `http://` and `https://` protocols when dealing with NTLM-authenticated proxies.
• gotcha Making multiple NTLM-authenticated requests without a `requests.Session` can be inefficient as each request performs a new NTLM challenge-response handshake.
  Fix: Always use `HttpNtlmAuth` in conjunction with a `requests.Session` object to leverage connection pooling and optimize NTLM authentication.

Install

• pip install requests-ntlm2 Install latest version

Imports

• HttpNtlmAuth
  wrong:

  from requests_ntlm import HttpNtlmAuth

  correct:

  from requests_ntlm2 import HttpNtlmAuth

  requests-ntlm2 is a fork of requests-ntlm; ensure you import from the correct package.
• HttpNtlmAdapter

  from requests_ntlm2 import HttpNtlmAdapter

  Required for NTLM authentication with HTTP CONNECT proxies.
• NtlmCompatibility

  from requests_ntlm2 import NtlmCompatibility

  Used to specify NTLM compatibility levels (e.g., NTLMv2, LM_AND_NTLMv1_WITH_ESS).

Quickstart

This quickstart demonstrates basic NTLM authentication with `requests-ntlm2` using `HttpNtlmAuth`. It also shows the recommended approach of using it with a `requests.Session` for improved efficiency and connection pooling. Replace placeholder environment variables with your actual NTLM credentials and target URL.

import requests
from requests_ntlm2 import HttpNtlmAuth
import os

# Replace with your NTLM domain, username, and password
NTLM_USERNAME = os.environ.get('NTLM_USERNAME', 'DOMAIN\\username')
NTLM_PASSWORD = os.environ.get('NTLM_PASSWORD', 'password')
TARGET_URL = os.environ.get('TARGET_URL', 'http://ntlm_protected_site.com')

# Basic NTLM authentication
try:
    auth = HttpNtlmAuth(NTLM_USERNAME, NTLM_PASSWORD)
    response = requests.get(TARGET_URL, auth=auth)
    response.raise_for_status() # Raise an exception for bad status codes
    print(f"Successfully authenticated to {TARGET_URL}. Status: {response.status_code}")
    # print(response.text[:200]) # Print first 200 characters of content
except requests.exceptions.RequestException as e:
    print(f"Error during basic NTLM authentication: {e}")

# Using with a Session for efficiency (recommended for multiple requests)
from requests import Session
session = Session()
session.auth = HttpNtlmAuth(NTLM_USERNAME, NTLM_PASSWORD)

try:
    session_response = session.get(TARGET_URL)
    session_response.raise_for_status()
    print(f"Successfully authenticated with session to {TARGET_URL}. Status: {session_response.status_code}")
except requests.exceptions.RequestException as e:
    print(f"Error during session NTLM authentication: {e}")