Squid configuration directive auth_param

Available in: 3.4   3.3   3.2   2.7   3.1   3.0   2.6  

History:

Changes in 3.4 auth_param

New result code BH to signal helper internal errors available in all authentication schemes.

New key message= for error message details in all authentication schemes.

New result code OK and key ha1= in Digest authentication.

New result codes OK, ERR replace result codes AF, and NA in NTLM and Negotiate authentication.

New key token= for NTLM and Negotiate authentication OK responses.

Details at http://wiki.squid-cache.org/Features/AddonHelpers.

Changes in 3.2 auth_param

New options for Basic, Digest, NTLM, Negotiate children settings. startup=N determines minimum number of helper processes used. idle=N determines how many helper to retain as buffer against sudden traffic loads. concurrency=N previously called auth_param ... concurrency as a separate option.

Removed Basic, Digest, NTLM, Negotiate auth_param ... concurrency setting option.

Known Issue: NTLM and Negotiate protocols do not support concurrency. When set this option is ignored.

Changes in 3.1 auth_param ntlm, basic, digest

BASIC, DIGEST: New parameter option utf8 on|off to permit helpers to selectively process UTF-8 characters even though HTTP accepts only ISO-8859-1.

NCSA authenticator updated in 3.1.15 to alert if passwords with more than 8 characters are used with DES encryption method.

NTLM: The helper binary bundled with Squid under the name ntlm_auth has been renamed to accurately reflect its real behavior and to prevent confusion with the more useful Samba helper using the same name.

Despite being used for NTLM, the helper does not in fact provide true NTLM function. What it does provide is SMB LanManager authentication through the NTLM interface without the need for a domain controller. Thus the new name is ntlm_smb_lm_auth.

WARNING: due to the name clash with Samba helper, admin should be careful to only update their squid.conf if the Squid bundled binary is used and needed. If the Samba helper is in use, the squid.conf should not be altered.

For older versions see the linked page above

Configuration Details:

Option Name:auth_param
Replaces:
Requires:--enable-auth
Default Value:none
Suggested Config:
#Recommended minimum configuration per scheme:
#auth_param negotiate program <uncomment and complete this line to activate>
#auth_param negotiate children 20 startup=0 idle=1
#auth_param negotiate keep_alive on
#
#auth_param ntlm program <uncomment and complete this line to activate>
#auth_param ntlm children 20 startup=0 idle=1
#auth_param ntlm keep_alive on
#
#auth_param digest program <uncomment and complete this line>
#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 basic program <uncomment and complete this line>
#auth_param basic children 5 startup=5 idle=1
#auth_param basic realm Squid proxy-caching web server
#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.
	To use authentication you must in addition make use of ACLs based
	on login name in http_access (proxy_auth, proxy_auth_regex or
	external with %LOGIN used in the format tag). The browser will be
	challenged for authentication on the first such acl encountered
	in http_access processing and will also be re-challenged for new
	login credentials if the request is being denied by a proxy_auth
	type acl.

	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 for the basic scheme follow. ===

	"program" cmdline
	Specify the command for the external authenticator.  Such a program
	reads a line containing "username password" and	replies with one of
	three results:

	  OK
		the user exists.

	  ERR
		the user does not exist.

	  BH
		An internal error occurred in the helper, preventing
		a result being identified.

	"ERR" and "BH" results may optionally be followed by message="..."
	containing a description available as %m in the returned error page.

	If you use an authenticator, make sure you have 1 acl of type
	proxy_auth.

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

	If you want to use the traditional NCSA proxy authentication, set
	this line to something like

	auth_param basic program /usr/local/squid/libexec/basic_ncsa_auth /usr/local/squid/etc/passwd

	"utf8" on|off
	HTTP uses iso-latin-1 as character set, while some authentication
	backends such as LDAP expects UTF-8. If this is set to on Squid will
	translate the HTTP iso-latin-1 charset to UTF-8 before sending the
	username & password to the helper.

	"children" numberofchildren [startup=N] [idle=N] [concurrency=N]
	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 number first on the
	request/response line, allowing multiple requests to be sent to the
	same helper in parallel without waiting for the response.
	Must not be set unless it's known the helper supports this.

	auth_param basic children 20 startup=0 idle=1

	"realm" realmstring
	Specifies the realm name which is to be reported to the
	client for the basic proxy authentication scheme (part of
	the text the user will see when prompted their username and
	password). There is no default.
	auth_param basic realm Squid proxy-caching web server

	"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 if usernames are case sensitive. Most user databases are
	case insensitive allowing the same username to be spelled using both
	lower and upper case letters, but some are case sensitive. This
	makes a big difference for user_max_ip ACL processing and similar.
	auth_param basic casesensitive off

	=== Parameters for the digest scheme follow ===

	"program" cmdline
	Specify the command for the external authenticator.  Such
	a program reads a line containing "username":"realm" and
	replies with one of three results:

	  OK ha1="..."
		the user exists. The ha1= key is mandatory and
		contains the appropriate H(A1) value, hex encoded.
		See rfc 2616 for the definition of H(A1).

	  ERR
		the user does not exist.

	  BH
		An internal error occurred in the helper, preventing
		a result being identified.

	"ERR" and "BH" results may optionally be followed by message="..."
	containing a description available as %m in the returned error page.

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

	If you want to use a digest authenticator, set this line to
	something like

	auth_param digest program /usr/local/squid/bin/digest_pw_auth /usr/local/squid/etc/digpass

	"utf8" on|off
	HTTP uses iso-latin-1 as character set, while some authentication
	backends such as LDAP expects UTF-8. If this is set to on Squid will
	translate the HTTP iso-latin-1 charset to UTF-8 before sending the
	username & password to the helper.

	"children" numberofchildren [startup=N] [idle=N] [concurrency=N]
	The maximum number of authenticator processes to spawn (default 5).
	If you start too few Squid will have to wait for them to
	process a backlog of H(A1) calculations, slowing it down.
	When the H(A1) calculations 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 number first on the
	request/response line, allowing multiple requests to be sent to the
	same helper in parallel without waiting for the response.
	Must not be set unless it's known the helper supports this.

	auth_param digest children 20 startup=0 idle=1

	"realm" realmstring
	Specifies the realm name which is to be reported to the
	client for the digest proxy authentication scheme (part of
	the text the user will see when prompted their username and
	password). There is no default.
	auth_param digest realm Squid proxy-caching web server

	"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 sends
	an incorrect request digest in POST requests when reusing
	the same nonce as acquired earlier on a GET request.

	=== NTLM scheme options follow ===

	"program" cmdline
	Specify the command for the external NTLM authenticator.
	Such a program reads exchanged NTLMSSP packets with
	the browser via Squid until authentication is completed.
	If you use an NTLM authenticator, make sure you have 1 acl
	of type proxy_auth.  By default, the NTLM authenticator program
	is not used.

	auth_param ntlm program /usr/bin/ntlm_auth

	"children" numberofchildren [startup=N] [idle=N]
	The maximum number of authenticator processes to spawn (default 5).
	If you start too few Squid will have to wait for them to
	process a backlog of credential verifications, slowing it
	down. When credential 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.

	auth_param ntlm children 20 startup=0 idle=1

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

	auth_param ntlm keep_alive on

	=== Options for configuring the NEGOTIATE auth-scheme follow ===

	"program" cmdline
	Specify the command for the external Negotiate authenticator.
	This protocol is used in Microsoft Active-Directory enabled setups with
	the Microsoft Internet Explorer or Mozilla Firefox browsers.
	Its main purpose is to exchange credentials with the Squid proxy
	using the Kerberos mechanisms.
	If you use a Negotiate authenticator, make sure you have at least
	one acl of type proxy_auth active. By default, the negotiate
	authenticator program is not used.
	The only supported program for this role is the ntlm_auth
	program distributed as part of Samba, version 4 or later.

	auth_param negotiate program /usr/bin/ntlm_auth --helper-protocol=gss-spnego

	"children" numberofchildren [startup=N] [idle=N]
	The maximum number of authenticator processes to spawn (default 5).
	If you start too few Squid will have to wait for them to
	process a backlog of credential verifications, slowing it
	down. When credential 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.

	auth_param negotiate children 20 startup=0 idle=1

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

	auth_param negotiate keep_alive on

	
	Examples:


 

Back

Search

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors