squid-cache.org

#auth_param negotiate program <uncomment and complete this line to activate>
#auth_param negotiate children 20 startup=0 idle=1
#
#auth_param digest program <uncomment and complete this line to activate>
#auth_param digest children 20 startup=0 idle=1
#auth_param digest realm Squid proxy-caching web server
#auth_param digest nonce_garbage_interval 5 minutes
#auth_param digest nonce_max_duration 30 minutes
#auth_param digest nonce_max_count 50
#
#auth_param ntlm program <uncomment and complete this line to activate>
#auth_param ntlm children 20 startup=0 idle=1
#
#auth_param basic program <uncomment and complete this line>
#auth_param basic children 5 startup=5 idle=1
#auth_param basic credentialsttl 2 hours

	This is used to define parameters for the various authentication
	schemes supported by Squid.

		format: auth_param scheme parameter [setting]

	The order in which authentication schemes are presented to the client is
	dependent on the order the scheme first appears in config file. IE
	has a bug (it's not RFC 2617 compliant) in that it will use the basic
	scheme if basic is the first entry presented, even if more secure
	schemes are presented. For now use the order in the recommended
	settings section below. If other browsers have difficulties (don't
	recognize the schemes offered even if you are using basic) either
	put basic first, or disable the other schemes (by commenting out their
	program entry).

	Once an authentication scheme is fully configured, it can only be
	shutdown by shutting squid down and restarting. Changes can be made on
	the fly and activated with a reconfigure. I.E. You can change to a
	different helper, but not unconfigure the helper completely.

	Please note that while this directive defines how Squid processes
	authentication it does not automatically activate authentication. For a
	given transaction, (re)authentication is requested in two primary cases
	detailed below: initial authentication and re-authentication.

	A client without credentials is requested to authenticate if one of the
	following ACLs is evaluated by an http_access or adapted_http_access rule:

		* proxy_auth ACL
		* proxy_auth_regex ACL
		* max_user_ip ACL
		* external ACL with %ul logformat %code used in FORMAT parameters
		* external ACL with %LOGIN macro used in FORMAT parameters;
		  this legacy macro currently behaves the same as %ul logformat %code

	A client with credentials is requested to re-authenticate if http_access
	or adapted_http_access denies its request _and_ the last evaluated ACL was
	either proxy_auth, proxy_auth_regex, or an external
	ACL with %ul or %LOGIN parameter (regardless of whether that last
	evaluated ACL matched the denied request). Note that a max_user_ip ACL
	does not have this effect: Requests denied after evaluating max_user_ip
	trigger an HTTP 403 (Forbidden) response rather than re-authentication.

	In both initial authentication and re-authentication cases, client access
	is denied, typically with an HTTP 407 (Proxy Authentication Required) or
	an HTTP 401 (Unauthorized) response.

	WARNING: authentication can't be used in a transparently intercepting
	proxy as the client then thinks it is talking to an origin server and
	not the proxy. This is a limitation of bending the TCP/IP protocol to
	transparently intercepting port 80, not a limitation in Squid.
	Ports flagged 'transparent', 'intercept', or 'tproxy' have
	authentication disabled.

	=== Parameters common to all schemes. ===

	"program" cmdline
		Specifies the command for the external authenticator.

		By default, each authentication scheme is not used unless a
		program is specified.

		See https://wiki.squid-cache.org/Features/AddonHelpers for
		more details on helper operations and creating your own.

	"key_extras" format
		Specifies a string to be append to request line format for
		the authentication helper. "Quoted" format values may contain
		spaces and logformat %macros. In theory, any logformat %macro
		can be used. In practice, a %macro expands as a dash (-) if
		the helper request is sent before the required macro
		information is available to Squid.

		By default, Squid uses request formats provided in
		scheme-specific examples below (search for %credentials).

		The expanded key_extras value is added to the Squid credentials
		cache and, hence, will affect authentication. It can be used to
		authenticate different users with identical user names (e.g.,
		when user authentication depends on http_port).

		Avoid adding frequently changing information to key_extras. For
		example, if you add user source IP, and it changes frequently
		in your environment, then max_user_ip ACL is going to treat
		every user+IP combination as a unique "user", breaking the ACL
		and wasting a lot of memory on those user records. It will also
		force users to authenticate from scratch whenever their IP
		changes.

	"realm" string
		Specifies the protection scope (aka realm name) which is to be
		reported to the client for the authentication scheme. It is
		commonly part of the text the user will see when prompted for
		their username and password.

		For Basic the default is "Squid proxy-caching web server".
		For Digest there is no default, this parameter is mandatory.
		For NTLM and Negotiate this parameter is ignored.

	"children" numberofchildren [startup=N] [idle=N] [concurrency=N]
		[queue-size=N] [on-persistent-overload=action]
		[reservation-timeout=seconds]

		The maximum number of authenticator processes to spawn. If
		you start too few Squid will have to wait for them to process
		a backlog of credential verifications, slowing it down. When
		password verifications are done via a (slow) network you are
		likely to need lots of authenticator processes.

		The startup= and idle= options permit some skew in the exact
		amount run. A minimum of startup=N will begin during startup
		and reconfigure. Squid will start more in groups of up to
		idle=N in an attempt to meet traffic needs and to keep idle=N
		free above those traffic needs up to the maximum.

		The concurrency= option sets the number of concurrent requests
		the helper can process.  The default of 0 is used for helpers
		who only supports one request at a time. Setting this to a
		number greater than 0 changes the protocol used to include a
		channel ID field first on the request/response line, allowing
		multiple requests to be sent to the same helper in parallel
		without waiting for the response.

		Concurrency must not be set unless it's known the helper
		supports the input format with channel-ID fields.

		The queue-size option sets the maximum number of queued
		requests. A request is queued when no existing child can
		accept it due to concurrency limit and no new child can be
		started due to numberofchildren limit. The default maximum is
		2*numberofchildren. Squid is allowed to temporarily exceed the
		configured maximum, marking the affected helper as
		"overloaded". If the helper overload lasts more than 3
		minutes, the action prescribed by the on-persistent-overload
		option applies.

		The on-persistent-overload=action option specifies Squid
		reaction to a new helper request arriving when the helper
		has been overloaded for more that 3 minutes already. The number
		of queued requests determines whether the helper is overloaded
		(see the queue-size option).

		Two actions are supported:

		  die	Squid worker quits. This is the default behavior.

		  ERR	Squid treats the helper request as if it was
			immediately submitted, and the helper immediately
			replied with an ERR response. This action has no effect
			on the already queued and in-progress helper requests.

		NOTE: NTLM and Negotiate schemes do not support concurrency
			in the Squid code module even though some helpers can.

		The reservation-timeout=seconds option allows NTLM and Negotiate
		helpers to forget about clients that abandon their in-progress
		connection authentication without closing the connection. The
		timeout is measured since the last helper response received by
		Squid for the client. Fractional seconds are not supported.

		After the timeout, the helper will be used for other clients if
		there are no unreserved helpers available. In the latter case,
		the old client attempt to resume authentication will not be
		forwarded to the helper (and the client should open a new HTTP
		connection and retry authentication from scratch).

		By default, reservations do not expire and clients that keep
		their connections open without completing authentication may
		exhaust all NTLM and Negotiate helpers.

	"keep_alive" on|off
		If you experience problems with PUT/POST requests when using
		the NTLM or Negotiate schemes then you can try setting this
		to off. This will cause Squid to forcibly close the connection
		on the initial request where the browser asks which schemes
		are supported by the proxy.

		For Basic and Digest this parameter is ignored.

	"utf8" on|off
		Useful for sending credentials to authentication backends that
		expect UTF-8 encoding (e.g., LDAP).

		When this option is enabled, Squid uses HTTP Accept-Language
		request header to guess the received credentials encoding
		(ISO-Latin-1, CP1251, or UTF-8) and then converts the first
		two encodings into UTF-8.

		When this option is disabled and by default, Squid sends
		credentials in their original (i.e. received) encoding.

		This parameter is only honored for Basic and Digest schemes.
		For Basic, the entire username:password credentials are
		checked and, if necessary, re-encoded. For Digest -- just the
		username component. For NTLM and Negotiate schemes, this
		parameter is ignored.

if --enable-auth-basic
	=== Basic authentication parameters ===

	"credentialsttl" timetolive
		Specifies how long squid assumes an externally validated
		username:password pair is valid for - in other words how
		often the helper program is called for that user. Set this
		low to force revalidation with short lived passwords.

		NOTE: setting this high does not impact your susceptibility
		to replay attacks unless you are using an one-time password
		system (such as SecureID). If you are using such a system,
		you will be vulnerable to replay attacks unless you also
		use the max_user_ip ACL in an http_access rule.

	"casesensitive" on|off
		Specifies whether upper case letters in client-sent usernames are
		preserved. By default and when explicitly set to "off", a username
		extracted from Proxy-Authorization or Authorization request header is
		forced to lower case before user credentials are checked or stored.

		Most user databases are case insensitive, allowing the same username to be
		spelled using both lower and upper case letters. For such databases, any
		casesenstive setting should work, but forcing usernames to lower case may
		still make a big difference for Squid internal caches like those used by
		an external ACL with %un logformat code in FORMAT and a user_max_ip ACL.

		When working with a case sensitive database, set casesensitive to "on".

		Squid ACLs like proxy_auth are case-sensitive by default. An ACL using
		upper case letters in user names (e.g., `acl badGuys proxy_auth Bob`)
		will not match any user with Basic Authentication credentials unless
		casesensitive is explicitly turned "on" (to preserve "Bob" username
		instead of converting it to "bob" before the ACL is checked).

endif
if --enable-auth-digest
	=== Digest authentication parameters ===

	"nonce_garbage_interval" timeinterval
		Specifies the interval that nonces that have been issued
		to client_agent's are checked for validity.

	"nonce_max_duration" timeinterval
		Specifies the maximum length of time a given nonce will be
		valid for.

	"nonce_max_count" number
		Specifies the maximum number of times a given nonce can be
		used.

	"nonce_strictness" on|off
		Determines if squid requires strict increment-by-1 behavior
		for nonce counts, or just incrementing (off - for use when
		user agents generate nonce counts that occasionally miss 1
		(ie, 1,2,4,6)). Default off.

	"check_nonce_count" on|off
		This directive if set to off can disable the nonce count check
		completely to work around buggy digest qop implementations in
		certain mainstream browser versions. Default on to check the
		nonce count to protect from authentication replay attacks.

	"post_workaround" on|off
		This is a workaround to certain buggy browsers who send an
		incorrect request digest in POST requests when reusing the
		same nonce as acquired earlier on a GET request.

endif

	=== Example Configuration ===

	This configuration displays the recommended authentication scheme
	order from most to least secure with recommended minimum configuration
	settings for each scheme: